O padrão **Form Field** encapsula um controle de entrada (como input, select, textarea) junto com sua etiqueta, ajuda contextual e mensagens de validação. É essencial para capturar dados do usuário de forma clara, consistente e acessível. Seu objetivo é maximizar a eficiência, reduzir erros e assegurar a compreensão imediata do 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;Instale o componente via terminal.
npm install @nimbus-ds/formfieldForm Field
Usar Form Field sempre que precisar coletar dados do usuário, seja em formulários simples (como filtros) ou complexos (como configuração de produtos). Pode ser utilizado em combinação com qualquer tipo de input controlado.
Não usar Form Field para mostrar conteúdo estático. Evitar usá-lo quando o campo não precisa de etiqueta, ajuda ou validação visível, como em casos de visualização não editável.
- Foco automático em campos principais para economizar cliques iniciais.
- Submit com Enter em formulários simples para agilizar tarefas.
- Pré-seleção inteligente quando o sistema pode antecipar o valor esperado (exemplo valores, tamanhos ou medidas)
- Feedback instantâneo ao inserir dados errôneos, sem necessidade de esperar para enviar o formulário.
- Etiquetas sempre visíveis e associadas com o input mediante for e id.
- Mensagens de erro e ajuda com aria-describedby.
- Assegurar foco visível em todos os campos interativos.
- Compatível com navegação por teclado e leitores de tela.
- Áreas táteis adequadas em dispositivos móveis (mínimo 44x44px).
O Form Field está composto por:
- Label – Descrição visível do propósito do campo.
- Control – Input, select ou textarea.
- Helper text (opcional) – Guia ou exemplo para preencher o campo.
- State message (opcional) – Feedback visual e textual ante erros.
- Input
- Label
- Helper text
- State message
- As input: Form field com input para carregamento de conteúdo textual.
- As select: Form field com input para seleção de múltiplas opções.
- As text area: Form field com text area para carregamento de grande quantidade de conteúdo textual.
- With custom content: Form field com componentes de seleção customizados como checks ou radio buttons.
- With state disclosure: Form field que mostra diferentes estados de visualização que se ativa com a interação do usuário
- Appearance Success, Warning e Danger: Form field com input com diferentes estados de sistema.
✅ Do
- Mostrar sempre o label, mesmo se for redundante.
- Usar helper text apenas se agregar clareza real.
- Mostrar erros imediatamente ao sair do campo.
- Alinhar todos os campos de forma consistente.
❌ Don't
- Não esconder o label para economizar espaço.
- Não usar texto placeholder como único indicador.
- Não mostrar erros genéricos ou sem contexto.
- Não bloquear o envio se o erro não impedir continuar.
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' | 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' | 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' | 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' | 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' | Sent icon display position |