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

Etiqueta label

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.