Form Field

1.7.0

El patrón Form Field encapsula un control de entrada (como input, select, textarea) junto con su etiqueta, ayuda contextual y mensajes de validación. Es esencial para capturar datos del usuario de forma clara, consistente y accesible. Su objetivo es maximizar la eficiencia, reducir errores y asegurar la comprensión inmediata del propósito de cada campo.

import 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;

Implementación

Instalá el componente via terminal.

npm install @nimbus-ds/formfield

Form Field

Cuándo usar

Usar Form Field siempre que necesites recolectar datos del usuario, ya sea en formularios simples (como filtros) o complejos (como configuración de productos). Puede utilizarse en combinación con cualquier tipo de input controlado.

Cuándo no usar

No usar Form Field para mostrar contenido estático. Evitar usarlo cuando el campo no necesita etiqueta, ayuda o validación visible, como en casos de visualización no editable.

Criterios de usabilidad y productividad

Enfoque automático en campos principales para ahorrar clics iniciales.
Submit con Enter en formularios simples para agilizar tareas.
Preselección inteligente cuando el sistema puede anticipar el valor esperado (ejemplo montos, talles o medidas)
Feedback instantáneo al ingresar datos erróneos, sin necesidad de esperar a enviar el formulario.

Accesibilidad

Etiquetas siempre visibles y asociadas con el input mediante for y id.
Mensajes de error y ayuda con aria-describedby.
Asegurar foco visible en todos los campos interactivos.
Compatible con navegación por teclado y lectores de pantalla.
Áreas táctiles adecuadas en dispositivos mobiles (mínimo 44x44px).

Anatomía

El Form Field está compuesto por:

Label – Descripción visible del propósito del campo.
Control – Input, select o textarea.
Helper text (opcional) – Guía o ejemplo para llenar el campo.
State message (opcional) – Feedback visual y textual ante errores.

Dependencias

Input
Label
Helper text
State message

Variantes

As input: Form field con input para carga de contenido textual.
As select: Form field con input para seleccion de multiples opciones.
As text area: Form field con text area para carga de gran cantidad de contenido textual.
With custom content: Form field con componentes de selección customizados como checks o radio buttons.
With state disclusure: Form field que muestra diferentes estados de visualizacion que se activa con la interaccion del usuario
Appearance Succes, Warning y Danger: Form field con input con diferentes estados de sistema.

Do and Don'ts

✅ Do

Mostrar siempre el label, incluso si es redundante.
Usar helper text solo si agrega claridad real.
Mostrar errores inmediatamente al salir del campo.
Alinear todos los campos de forma consistente.

❌ Don't

No esconder el label para ahorrar espacio.
No usar texto placeholder como único indicador.
No mostrar errores genéricos o sin contexto.
No bloquear el envío si el error no impide continuar.

Props

Additional props are passed to the <FormField> element. See div docs for a list of props accepted by the <FormField> element.

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' 'success' 'warning'	'none'	Appearance of the field and help text elements.
showHelpText	boolean		Control to conditionally show the help text and icon.
children*	React.ReactNode		Content of the field.

FormField.Select

Name	Type	Default	Description
appearance	'danger' 'none' 'success' 'warning'	'none'	Appearance of the field and help text elements.
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.
showHelpText	boolean		Control to conditionally show the help text and icon.
id*	string		The id of the wrapper element or the select element when native.
name*	string		The name of the wrapper element or the select element when native.
children*	React.ReactNode		The content of the select.

FormField.Textarea

Name	Type	Default	Description
appearance	'danger' 'none' 'success' 'warning'	'none'	Appearance of the field and help text elements.
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.
showHelpText	boolean		Control to conditionally show the help text and icon.
id*	string		ID of the textarea
lines	number	'2'	Number of lines to be rendered for the user to input text

FormField.Input

Name	Type	Default	Description
appearance	'danger' 'none' 'success' 'warning'	'none'	Appearance of the field and help text elements.
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.
showHelpText	boolean		Control to conditionally show the help text and icon.
append	React.ReactNode		SVG icon to be displayed on input.
disabled	boolean		Disables the input, disallowing user interaction.
data-testid	string		This is an attribute used to identify a DOM node for testing purposes.
appendPosition	'end' 'start'	'start'	Sent icon display position