1.7.0

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/formfield

Form 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:

  1. Label – Descrição visível do propósito do campo.
  2. Control – Input, select ou textarea.
  3. Helper text (opcional) – Guia ou exemplo para preencher o campo.
  4. 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

NameTypeDefaultDescription

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

NameTypeDefaultDescription

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

NameTypeDefaultDescription

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

NameTypeDefaultDescription

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