Form Field
Permite mostrar un control de entrada (input, select, textarea o contenido personalizado) junto con su etiqueta, texto de ayuda y mensaje de validación, para capturar datos del usuario de forma clara, consistente y accesible.
- Recolectar datos del usuario: en formularios simples, como filtros, o complejos, como la configuración de un producto, siempre que el dato necesite una etiqueta visible y pueda requerir ayuda o validación. Ej.: "Nombre de la tienda", "Cantidad mínima de stock".
- Combinar un control de entrada con su etiqueta y su ayuda: envolver un input, select, textarea o contenido de selección personalizado (checks, radios) bajo una misma estructura de label, texto de ayuda y mensaje de validación, sin reconstruir esa asociación a mano en cada formulario.
- Mostrar contenido no editable: presentar un valor fijo que la persona usuaria no puede modificar, sin necesidad de etiqueta ni validación. En su lugar, usar Text.
- Envolver un control que no necesita etiqueta, ayuda ni validación: si ninguna de las tres aporta, usar el control directamente (por ejemplo Input) sin la estructura adicional de Form Field.
Ya usás este nombre en otro producto activo
Form Field
- Label (opcional): describe el propósito del campo; se asocia al control mediante htmlFor/id.
- Control: el input, select, textarea o contenido de selección personalizado que recibe el dato.
- Icon (opcional): acompaña el texto de ayuda; su color cambia según appearance.
- Help text (opcional): guía de ayuda cuando appearance es none, o mensaje de validación cuando es success, warning o danger. Es un único texto que cambia de función según la apariencia, no dos elementos distintos.
As input: para un dato de una sola línea. Ej.: "Nombre del producto", "Email de contacto".
As select: para elegir un valor entre opciones predefinidas. Ej.: "Categoría", "Método de envío".
As text area: para un dato de varias líneas. Ej.: "Descripción del producto", "Notas internas del pedido".
With custom content: para envolver un contenido de selección personalizado, como checks o radio buttons, bajo la misma etiqueta y ayuda que un control estándar.
Se muestra en el catálogo público de la tienda
None (default): sin validación en curso; el texto de ayuda solo orienta sobre el campo. Ej.: aclarar dónde se ve el valor ingresado.
El nombre está disponible
Success: confirma que el valor ingresado es válido. Ej.: un nombre de producto disponible.
Ya usás este nombre en otro producto activo
Warning: advierte sobre un valor que conviene revisar, sin bloquear el envío del formulario. Ej.: un nombre repetido que aun así se puede guardar.
Este campo es obligatorio
Danger: señala un error de validación. Ej.: un campo obligatorio que quedó vacío al enviar el formulario.
Válido solo para la primera compra
Siempre visible: el texto de ayuda se muestra todo el tiempo, con showHelpText fijo en true. Ej.: una condición que conviene ver sin necesidad de interactuar con el campo.
Solo al enfocar: el texto de ayuda aparece únicamente mientras el campo tiene foco, alternando showHelpText con onFocus/onBlur. Ej.: una aclaración que solo importa mientras se completa el campo.
Form Field aparece en formularios de configuración, filtros, checkout y edición de productos: siempre que un control de entrada necesite su etiqueta y, según el caso, un mensaje de ayuda o de validación cerca.
Datos del producto
Mostrar siempre el label, incluso cuando el propósito del campo parezca evidente.
No usar el placeholder como único indicador del campo: desaparece al escribir y no queda ningún label visible.
Mínimo 8 caracteres, con al menos una mayúscula
Usar el texto de ayuda para sumar información que el label no puede dar, como el formato esperado.
Completá este campo
Evitar un texto de ayuda que repite lo obvio sin agregar valor.
Ingresá un email con formato válido, como nombre@dominio.com
Mostrar un mensaje de error específico apenas se detecta el problema, sin esperar al envío del formulario.
Error
Evitar mensajes de error genéricos que no explican qué corregir.
Alinear con el mismo ancho los campos de un mismo formulario, para que el conjunto se lea como una unidad.
Evitar anchos inconsistentes entre campos de un mismo formulario: rompen el ritmo visual sin comunicar ninguna diferencia real.
- Etiqueta siempre asociada: el label se vincula al control mediante htmlFor/id, así los lectores de pantalla anuncian su propósito sin depender del placeholder, que desaparece al escribir.
- Mensaje de ayuda no vinculado por defecto: el texto y el ícono de ayuda se muestran junto al campo, pero Form Field no le agrega aria-describedby al control; si el mensaje necesita anunciarse junto con el campo para lectores de pantalla, agregar aria-describedby a mano apuntando a un id propio en el texto de ayuda.
- Foco visible y navegación por teclado heredados: al componer un <input>, <select> o <textarea> nativo, el control mantiene el anillo de foco y el comportamiento de teclado de Nimbus sin configuración adicional.
- No depender solo del color: las apariencias success, warning y danger van siempre acompañadas de un texto de ayuda o de error; el color del borde por sí solo no comunica el estado a quienes no pueden distinguirlo.
- Estado deshabilitado real: usar la prop disabled del control en lugar de simularlo con estilos, para que se comunique correctamente a las tecnologías de asistencia.
Instalá el componente vía terminal.
npm install @nimbus-ds/formfieldimport React from "react";
import { FormField } from "@nimbus-ds/patterns";
import { ExclamationCircleIcon } from "@nimbus-ds/icons";
const Example: React.FC = () => (
<FormField.Input
label="Label text"
helpText="Help text"
showHelpText={true}
id="input-id"
helpIcon={ExclamationCircleIcon}
placeholder="Placeholder"
/>
);
export default Example;Las propiedades adicionales se pasan al elemento <FormField>. Consultá la documentación del elemento div para ver la lista de atributos aceptados.
- Input — Control de una línea que Form Field compone como FormField.Input.
- Select — Control de selección que Form Field compone como FormField.Select.
- Textarea — Control de varias líneas que Form Field compone como FormField.Textarea.
- Label — Etiqueta que Form Field asocia automáticamente al control.
- Radio — Control de selección excluyente, usable como contenido personalizado dentro de Form Field.
FormField
| Name | Type | Default | Description |
|---|---|---|---|
label | React.ReactNode | Optional label for the field component. | |
helpText | string | Help text displaying optional hints or validation messages under the field. | |
helpIcon | React.FC<IconProps> | Icon supporting the help text message. | |
appearance | 'danger' | 'none' | Appearance of the field and help text elements. |
showHelpText | boolean | 'false' | Control to conditionally show the help text and icon. |
children* | React.ReactNode | Content of the field. |
FormField.Select
| Name | Type | Default | Description |
|---|---|---|---|
label | React.ReactNode | Optional label for the field component. | |
appearance | 'danger' | 'none' | Appearance of the field and help text elements. |
helpText | string | Help text displaying optional hints or validation messages under the field. | |
helpIcon | React.FC<IconProps> | Icon supporting the help text message. | |
showHelpText | boolean | 'false' | Control to conditionally show the help text and icon. |
id* | string | The id of the wrapper element or the select element when native. | |
children* | React.ReactNode | The content of the select. | |
name* | string | The name of the wrapper element or the select element when native. | |
aiGenerated | boolean | 'false' | Shows ai-generative appearance with active ai focus shadow. When true, this styling takes precedence over `appearance`. |
FormField.Textarea
| Name | Type | Default | Description |
|---|---|---|---|
label | React.ReactNode | Optional label for the field component. | |
appearance | 'danger' | 'none' | Appearance of the field and help text elements. |
helpText | string | Help text displaying optional hints or validation messages under the field. | |
helpIcon | React.FC<IconProps> | Icon supporting the help text message. | |
showHelpText | boolean | 'false' | Control to conditionally show the help text and icon. |
id* | string | ID of the textarea | |
resize | boolean | 'true' | Enable/disable textarea resize functionality |
aiGenerated | boolean | Highlights the field to indicate its value was generated by AI. Applies AI gradient border, white background and an AI focus ring. | |
lines | number | '2' | Number of lines to be rendered for the user to input text |
autoGrow | boolean | 'false' | Controls intrinsic sizing behavior of the field. When true, the textarea will grow with content up to the maxLines limit (if provided) and then scroll. |
maxLines | number | Caps the textarea visual height to the given number of lines. When used together with autoGrow=true, the textarea will grow with content up to this limit and then scroll. | |
minLines | number | Sets the minimum height of the textarea to the given number of lines. The textarea will never shrink below this height, even when empty. |
FormField.Input
| Name | Type | Default | Description |
|---|---|---|---|
label | React.ReactNode | Optional label for the field component. | |
appearance | 'ai-generative' | ||
helpText | string | Help text displaying optional hints or validation messages under the field. | |
helpIcon | React.FC<IconProps> | Icon supporting the help text message. | |
showHelpText | boolean | 'false' | Control to conditionally show the help text and icon. |
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. | |
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. |
Ayudanos a mejorar la documentación
¿Encontraste un problema o tenés una sugerencia? Contanos.