Input

Componente de entrada para escribir contenido con el teclado: el control de formulario más básico.

Úsalo cuando necesites un campo de texto con etiqueta fija encima, icono a la izquierda, estado y mensaje de validación, y participación en formularios nativos: <r-input> cubre la entrada de texto, contraseña y números.

Inicio rápido

Uso básico

<r-input placeholder="Escribe algo"></r-input>

Referencia de la API

Propiedades

Propiedad	Tipo	Por defecto	Descripción
`label`	`string`	`''`	Rótulo fijo dibujado encima del campo
`placeholder`	`string`	`''`	Texto de marcador, reenviado al `<input>` nativo
`value`	`string`	`''`	Valor del campo; se refleja como atributo y se transmite al formulario
`disabled`	`boolean`	`false`	Si el campo está deshabilitado
`type`	`string`	`''`	Tipo nativo reenviado al control interno (`text`, `password`, `number`, …)
`icon`	`string`	`''`	Nombre del icono inicial dentro del campo (se dibuja como `r-icon`)
`name`	`string`	`''`	Nombre del campo cuando participa en un formulario
`status`	`string`	`''`	Estado de validación: `error`, `warning`
`message`	`string`	`''`	Texto de ayuda o de validación dibujado bajo el campo
`min`	`string`	`''`	Valor mínimo; se reenvía al `<input>` interno cuando `type="number"`
`max`	`string`	`''`	Valor máximo; se reenvía al `<input>` interno cuando `type="number"`
`step`	`string`	`''`	Paso del valor; se reenvía al `<input>` interno cuando `type="number"`
`required`	`boolean`	`false`	Se reenvía al `<input>` interno para que actúe la validación nativa
`sheet`	`string`	`''`	CSS inyectado en el shadow root

Un rótulo fijo dibujado encima del campo: siempre visible, nunca se solapa con el contenido contiguo y no descoloca la maquetación al enfocar (las etiquetas alineadas arriba, además, se completan más rápido que las en línea o flotantes; véase la investigación con seguimiento ocular de Luke Wroblewski).

<r-input label="Nombre de usuario"></r-input>

Marcador `placeholder`

Se comporta igual que el atributo placeholder nativo.

<r-input placeholder="Escribe tu nombre de usuario"></r-input>

Valor `value`

<r-input value="1234"></r-input>

Estado deshabilitado `disabled`

<r-input label="Nombre de usuario" disabled></r-input>

Icono `icon`

<r-input icon="user"></r-input>

Tipos de entrada `type`

<r-input icon="lock" type="password" placeholder="Contraseña"></r-input>
<r-input type="number" placeholder="Número"></r-input>

Estado `status`

Acompaña siempre status de un message, para que el estado lo comunique el texto y no solo el color.

<r-input status="error" label="Nombre de usuario" message="Este campo es obligatorio"></r-input>
<r-input status="warning" label="Nombre de usuario" message="Revisa este valor"></r-input>

Mensaje de ayuda `message`

Dibuja texto de ayuda o de validación bajo el campo.

<r-input label="Correo" message="Nunca compartiremos tu correo"></r-input>

Nombre del campo `name`

<r-input name="username" label="Nombre de usuario"></r-input>

Eventos

Ambos eventos se despachan como CustomEvent y llevan el valor actual en detail.

Evento	Cuándo se dispara	`detail`
`input`	En cada pulsación (refleja el `input` nativo)	`{ value: string }`
`change`	Al confirmar o perder el foco (refleja el `change` nativo)	`{ value: string }`

Evento de escritura `input`

const input = document.createElement('r-input');
input.setAttribute('label', 'Nombre de usuario');
input.addEventListener('input', (event) => {
  console.log('Escribiendo:', event.detail.value);
});

Evento de cambio `change`

const input = document.createElement('r-input');
input.setAttribute('label', 'Nombre de usuario');
input.addEventListener('change', (event) => {
  console.log('El valor cambió:', event.detail.value);
});

Asociación con formularios

r-input es un elemento personalizado asociado a formularios (static formAssociated = true). Adjunta ElementInternals y transmite su valor con setFormValue, así que new FormData(form) lo recoge cuando es descendiente real de un <form> nativo; pon name para darle una clave al valor. Consulta Formularios para el ayudante serializeForm(), que convierte un envío en un objeto plano.

<form>
  <r-input name="username" label="Nombre de usuario"></r-input>
</form>

Reinicio: un form.reset() nativo (o un <button type="reset">) devuelve el valor que el campo tenía al conectarse por primera vez, mediante formResetCallback(), uno de los ganchos de ciclo de vida que el navegador llama solo en un elemento personalizado asociado a formularios.

Validación: poner required hace que un campo vacío sea inválido a través de ElementInternals.setValidity(); form.checkValidity() / form.reportValidity() lo ven, y al enviar aparece el globo de validación nativo del navegador anclado al campo. Los campos disabled nunca bloquean la validación, igual que un <input> nativo. r-input expone además los métodos y propiedades habituales de un campo nativo: checkValidity(), reportValidity(), validity, validationMessage.

<form>
  <r-input name="username" label="Nombre de usuario" required></r-input>
  <button type="submit">Enviar</button>
</form>

Parts CSS

Expuestos vía ::part() para darles estilo desde fuera.

Part	Elemento
`input`	El envoltorio del campo
`content`	El control `<input>` nativo interno
`label`	La etiqueta fija sobre el campo (existe cuando hay `label`)
`message`	El texto de ayuda o validación (existe cuando hay `message`)

r-input::part(content) {
  font-size: 16px;
}

Estilos

<r-input> expone 61 propiedades personalizadas de CSS propias, además de los tokens semánticos que lee del tema. Define una allí donde se herede: :root, un contenedor o el propio elemento:

r-input {
  --ran-input-color: var(--ran-color-text-secondary);
}

Partes: content · input · label · message

La lista completa está en tokens de estilo; cuál usar lo explica el sistema de diseño.

Buenas prácticas

Etiquetas: añade un label con sentido para que el campo tenga un nombre accesible.
Marcadores: usa placeholder como pista de escritura, no como sustituto de la etiqueta.
Estado y mensaje: acompaña status de message para que el estado no dependa solo del color.
Iconos: añade un icon pertinente para que el campo se reconozca antes.
Tipos: elige el type adecuado al contenido (text, password, number, …).
Formularios: pon name cuando recojas el valor dentro de un formulario.