Form Field
Permite exibir um controle de entrada (input, select, textarea ou conteúdo personalizado) junto com sua etiqueta, texto de ajuda e mensagem de validação, para capturar dados do usuário de forma clara, consistente e acessível.
- Coletar dados do usuário: em formulários simples, como filtros, ou complexos, como a configuração de um produto, sempre que o dado precisar de uma etiqueta visível e puder exigir ajuda ou validação. Ex.: "Nome da loja", "Quantidade mínima em estoque".
- Combinar um controle de entrada com sua etiqueta e sua ajuda: envolver um input, select, textarea ou conteúdo de seleção personalizado (checkboxes, radios) sob uma mesma estrutura de label, texto de ajuda e mensagem de validação, sem reconstruir essa associação manualmente em cada formulário.
- Exibir conteúdo não editável: apresentar um valor fixo que a pessoa usuária não pode modificar, sem necessidade de etiqueta nem validação. Nesse caso, usar Text.
- Envolver um controle que não precisa de etiqueta, ajuda nem validação: se nenhuma das três agrega valor, usar o controle diretamente (por exemplo Input) sem a estrutura adicional do Form Field.
Você já usa esse nome em outro produto ativo
Form Field
- Label (opcional): descreve o propósito do campo; é associado ao controle mediante htmlFor/id.
- Control: o input, select, textarea ou conteúdo de seleção personalizado que recebe o dado.
- Icon (opcional): acompanha o texto de ajuda; sua cor muda de acordo com appearance.
- Help text (opcional): guia de ajuda quando appearance é none, ou mensagem de validação quando é success, warning ou danger. É um único texto que muda de função conforme a aparência, não dois elementos distintos.
As input: para um dado de uma única linha. Ex.: "Nome do produto", "Email de contato".
As select: para escolher um valor entre opções predefinidas. Ex.: "Categoria", "Método de envio".
As text area: para um dado de várias linhas. Ex.: "Descrição do produto", "Notas internas do pedido".
With custom content: para envolver um conteúdo de seleção personalizado, como checkboxes ou radio buttons, sob a mesma etiqueta e ajuda de um controle padrão.
Aparece no catálogo público da loja
None (default): sem validação em andamento; o texto de ajuda apenas orienta sobre o campo. Ex.: esclarecer onde o valor informado é exibido.
O nome está disponível
Success: confirma que o valor informado é válido. Ex.: um nome de produto disponível.
Você já usa esse nome em outro produto ativo
Warning: alerta sobre um valor que vale a pena revisar, sem bloquear o envio do formulário. Ex.: um nome repetido que ainda assim pode ser salvo.
Este campo é obrigatório
Danger: sinaliza um erro de validação. Ex.: um campo obrigatório que ficou vazio ao enviar o formulário.
Válido somente para a primeira compra
Sempre visível: o texto de ajuda é exibido o tempo todo, com showHelpText fixo em true. Ex.: uma condição que vale a pena mostrar sem exigir interação com o campo.
Somente ao focar: o texto de ajuda aparece apenas enquanto o campo está em foco, alternando showHelpText com onFocus/onBlur. Ex.: uma observação que só importa durante o preenchimento do campo.
Form Field aparece em formulários de configuração, filtros, checkout e edição de produtos: sempre que um controle de entrada precisar da sua etiqueta e, conforme o caso, de uma mensagem de ajuda ou de validação próxima.
Dados do produto
Mostrar sempre o label, mesmo quando o propósito do campo pareça evidente.
Não usar o placeholder como único indicador do campo: ele desaparece ao digitar e não deixa nenhum label visível.
Mínimo de 8 caracteres, com pelo menos uma letra maiúscula
Usar o texto de ajuda para somar informação que o label não consegue dar, como o formato esperado.
Preencha este campo
Evitar um texto de ajuda que repete o óbvio sem agregar valor.
Digite um email com formato válido, como nome@dominio.com
Mostrar uma mensagem de erro específica assim que o problema é detectado, sem esperar o envio do formulário.
Erro
Evitar mensagens de erro genéricas que não explicam o que corrigir.
Alinhar com a mesma largura os campos de um mesmo formulário, para que o conjunto seja lido como uma unidade.
Evitar larguras inconsistentes entre campos de um mesmo formulário: elas quebram o ritmo visual sem comunicar nenhuma diferença real.
- Etiqueta sempre associada: o label é vinculado ao controle mediante htmlFor/id, então os leitores de tela anunciam seu propósito sem depender do placeholder, que desaparece ao digitar.
- Mensagem de ajuda não vinculada por padrão: o texto e o ícone de ajuda aparecem junto ao campo, mas o Form Field não adiciona aria-describedby ao controle; se a mensagem precisar ser anunciada junto com o campo para leitores de tela, adicionar aria-describedby manualmente apontando para um id próprio no texto de ajuda.
- Foco visível e navegação por teclado herdados: ao compor um <input>, <select> ou <textarea> nativo, o controle mantém o anel de foco e o comportamento de teclado do Nimbus sem configuração adicional.
- Não depender só da cor: as aparências success, warning e danger vêm sempre acompanhadas de um texto de ajuda ou de erro; a cor da borda por si só não comunica o estado a quem não consegue distingui-la.
- Estado desabilitado real: usar a prop disabled do controle em vez de simulá-lo com estilos, para que seja comunicado corretamente às tecnologias assistivas.
Instale o componente via 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;As propriedades adicionais são passadas ao elemento <FormField>. Consulte a documentação do elemento div para ver a lista de atributos aceitos.
- Input — Controle de uma linha que o Form Field compõe como FormField.Input.
- Select — Controle de seleção que o Form Field compõe como FormField.Select.
- Textarea — Controle de várias linhas que o Form Field compõe como FormField.Textarea.
- Label — Etiqueta que o Form Field associa automaticamente ao controle.
- Radio — Controle de seleção excludente, utilizável como conteúdo personalizado dentro do 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. |
Ajude-nos a melhorar a documentação
Encontrou um problema ou tem uma sugestão? Conte para a gente.