Input
Permite ingresar o editar un valor de texto breve en una sola línea.
- Capturar un dato breve de una sola línea: recibir texto o números que no necesitan más de una línea para mostrarse. Ej.: "Nombre del producto", "Correo electrónico".
- Buscar dentro de un listado o catálogo: filtrar resultados a partir de un término escrito, con Input.Search. Ej.: "Buscar productos", "Buscar pedidos".
- Ingresar datos sensibles: recibir contraseñas u otra información que debe ocultarse mientras se escribe, con Input.Password. Ej.: "Contraseña de acceso".
- Mostrar el estado de validación de un valor: reforzar visualmente que un dato ingresado es correcto, tiene un error o necesita atención, mediante appearance.
- Ingresar texto de varias líneas: describir algo con más de una línea de extensión, como una descripción o un comentario. En su lugar, usar Textarea.
- Elegir un valor de una lista cerrada de opciones: seleccionar entre alternativas predefinidas en lugar de escribir libremente. En su lugar, usar Select.
- Mostrar el campo con su etiqueta y mensaje de ayuda integrados: el Input no incluye label ni helpText propios. En su lugar, usar Form Field, que compone el Input junto con su etiqueta y su texto de ayuda o error.
Con ícono al inicio
Password
- Container: caja del campo que refleja la apariencia y el estado (fondo y borde).
- Field: área editable donde se escribe o edita el valor.
- Placeholder: texto de ejemplo que sugiere el formato o tipo de valor esperado, visible solo mientras el campo está vacío; desaparece al empezar a escribir, por lo que no debe ser la única guía para completarlo.
- Icon: ícono opcional, ubicado antes o después del campo mediante append y appendPosition. En Input.Search viene incorporado (una lupa) y no se configura.
- Toggle button (solo en Input.Password): alterna la visibilidad del valor ingresado entre oculto y visible. Solo aparece cuando el campo tiene contenido; con el campo vacío, no se renderiza.
Text: recibe texto o números libres, con o sin validación. Es el uso general del componente. Ej.: "Nombre del producto", "Código postal".
Search: campo de búsqueda con un ícono de lupa incorporado; el ícono es solo decorativo y no reemplaza el nombre accesible, por lo que igual necesita un Label, aria-label o aria-labelledby. Ej.: "Buscar pedidos".
Password: oculta el valor mientras se escribe y ofrece un control para alternar su visibilidad. Ej.: "Contraseña de acceso".
Neutral: apariencia por defecto, sin validación en curso.
Success: confirma que el valor ingresado es válido. Ej.: un código de verificación aceptado.
Warning: advierte sobre un valor que conviene revisar, sin bloquear el envío del formulario. Ej.: un tamaño de paquete fuera de lo habitual.
Danger: señala un error de validación. Ej.: un campo obligatorio que quedó vacío al enviar el formulario.
AI generative: aplica el borde en degradé de Nimbus para campos usados en contextos de inteligencia artificial (Lumi). Ej.: un campo de prompt para generar contenido con IA.
aiGenerated: destaca que el valor actual del campo fue generado por IA, con un anillo de foco propio. Es independiente de appearance y puede combinarse con cualquiera de sus valores.
El Input aparece dentro de formularios, junto a su Label y, cuando corresponde, un texto de ayuda o de error compuestos a través de Form Field. Es común encontrarlo agrupado con otros campos relacionados, como los de una dirección de envío.
Dirección
Número
Piso/Depto
Precio de venta
Acompañar el campo con un ícono al inicio cuando refuerza el tipo de dato esperado, como el símbolo de moneda en un precio.
Precio de venta
Evitar usar el ícono para repetir información que ya está en el label o en el placeholder.
Código postal
Barrio
Agrupar en una misma fila los campos que forman parte de un mismo dato, como los de una dirección.
Código postal
Barrio
Evitar apilar en filas separadas campos que tienen una relación directa y podrían agruparse.
Código postal
Dimensionar el campo según la longitud esperada del valor, como uno angosto para un código postal.
Código postal
Evitar campos innecesariamente anchos para valores de pocos caracteres.
- Navegación por teclado: al renderizar un <input> nativo, recibe el foco con Tab y admite edición directa con el teclado.
- Foco visible: Nimbus aplica un anillo de foco propio al enfocar el campo; no suprimir el outline al personalizar estilos.
- Etiqueta asociada: el Input no incluye label propio; para que el campo sea accesible, asociarlo siempre a un Label o componerlo con Form Field, que ya gestiona la asociación entre etiqueta, campo y mensaje de ayuda.
- Estado deshabilitado: usar la prop disabled, no simularlo con color u opacidad; el <input disabled> comunica el estado inactivo a las tecnologías de asistencia.
- No depender del color: el significado de las apariencias success, warning y danger debe reforzarse con un texto de ayuda o de error, no solo con el color del borde, ya que algunas personas usuarias pueden tener dificultad para distinguir los colores.
- Contraseña visible bajo control de la persona usuaria: el botón para alternar la visibilidad de Input.Password permite confirmar el valor ingresado antes de enviarlo, sin obligar a mostrarlo de forma permanente.
Placeholder: sentence case, sin punto final; se agrega solo cuando aporta un ejemplo o formato concreto que el label no puede dar — usarlo por defecto hace que las personas usuarias aprendan a ignorarlo.
Placeholder según el tipo de dato: si el campo tiene un formato específico (fecha, código, SKU), incluir siempre un ejemplo — "Ej.: DD/MM/AAAA". Si es texto libre sin estructura definida, no inventar un ejemplo.
Prefix / Suffix: unidad de medida, símbolo o contexto corto que condiciona el dato, sin espacios extra ni puntuación — "$" · "kg" · "%" · "@dominio.com".
| Variante | Regla de contenido |
|---|---|
Text (default) | Campo de texto libre de una línea, siempre acompañado de Label. El placeholder es opcional: solo cuando agrega un ejemplo o formato que el label no puede dar. |
Search | Requiere un nombre accesible vía Label, aria-label o aria-labelledby — el ícono de lupa es decorativo y no lo reemplaza. El placeholder es la guía: describe qué se puede buscar. Fórmula: verbo "Buscar" + objeto, sin artículo — "Buscar productos" · "Buscar clientes" · "Buscar por nombre o SKU". |
Password | El placeholder no aporta valor en este campo — repetiría el label sin sumar un formato adicional, por eso normalmente se omite. El label nombra el dato, nunca el mecanismo — "Contraseña", no "Ingresá tu contraseña". El help text puede listar los requisitos antes de crear la contraseña — "Mínimo 8 caracteres, una mayúscula y un número." El error no revela qué parte del formato falló, por seguridad — "La contraseña no cumple los requisitos.", no "Falta una mayúscula." |
| Caso | Qué hacer |
|---|---|
Input.Search sin placeholder | Incluir siempre un placeholder — sin él, el campo no tiene guía de qué se puede buscar. |
Input.Password con múltiples requisitos | El help text los lista antes de crear la contraseña. El error no especifica cuál requisito falló, por seguridad — "La contraseña no cumple los requisitos.", no "Falta una mayúscula." |
Campo obligatorio | Nunca usar el placeholder para indicarlo (ej.: "Campo requerido"); resolver la obligatoriedad con el asterisco o la convención de Form Field. |
Instalar el componente vía terminal.
npm install @nimbus-ds/componentsimport React from "react";
import { Input } from "@nimbus-ds/components";
const Example: React.FC = () => <Input placeholder="Nombre del producto" />;
export default Example;Las propiedades adicionales se pasan al elemento <input>. Consultar la documentación del elemento input para ver la lista de atributos aceptados.
- Form Field — Para componer el Input junto con su etiqueta y su mensaje de ayuda o error.
- Textarea — Para ingresar texto de más de una línea.
- Select — Para elegir un valor entre opciones predefinidas.
- Label — Para asociar una etiqueta accesible al campo.
Input
| Name | Type | Default | Description |
|---|---|---|---|
appearance | 'ai-generative' | 'neutral' | Change the visual style of the input. |
aiGenerated | boolean | Highlights the field to indicate its value was generated by AI. Applies AI gradient border, white background and an AI focus ring. | |
disabled | boolean | Disables the input, disallowing user interaction. | |
appendPosition | 'end' | 'start' | Sent icon display position |
append | React.ReactNode | SVG icon to be displayed on input. | |
data-testid | string | This is an attribute used to identify a DOM node for testing purposes. |
Input.Password
| Name | Type | Default | Description |
|---|---|---|---|
appearance | 'ai-generative' | 'neutral' | Change the visual style of the input. |
disabled | boolean | Disables the input, disallowing user interaction. | |
aiGenerated | boolean | Highlights the field to indicate its value was generated by AI. Applies AI gradient border, white background and an AI focus ring. |
Input.Search
| Name | Type | Default | Description |
|---|---|---|---|
appearance | 'ai-generative' | 'neutral' | Change the visual style of the input. |
disabled | boolean | Disables the input, disallowing user interaction. | |
aiGenerated | boolean | Highlights the field to indicate its value was generated by AI. Applies AI gradient border, white background and an AI focus ring. |
Input.Skeleton
| Name | Type | Default | Description |
|---|---|---|---|
width | string | Width of the skeleton. Useful when the skeleton is inside an inline element with no width of its own. | |
className | string | ||
data-testid | string | This is an attribute used to identify a DOM node for testing purposes. |
Ayudanos a mejorar la documentación
¿Encontraste un problema o tenés una sugerencia? Contanos.