Pular para o conteúdo
Faculdade PhorteDesign System

FormField

Em andamento

O invólucro de um campo de formulário: rótulo (Label), o controle, a dica e a mensagem de erro, ligados entre si. É a fonte única de aria-invalid do sistema.

Função
Formulário e ação
Também chamado de
campo de formulário, grupo do campo, form field
Mora em
app/components/molecules/FormField.tsx
Última mudança
2026-10-01
Ver como Markdown(abre em outra aba)Ficha no Storybook(abre em outra aba)

Prévia

A peça ao vivo, vinda da ficha, na largura escolhida. Em larguras fixas, ela roda num quadro do tamanho de uma tela de verdade.

Na largura da página: 0px

Pular a prévia
Variante Padrão, ao vivo — vem da ficha.Abrir sozinha(abre em outra aba)

Variantes na ficha

Lidas da ficha no build, na ordem do palco. Cada uma abre sozinha, sem o styleguide em volta — é o endereço que o palco carrega.

  1. Padrão
  2. Com Erro
  3. Com Dica
  4. Obrigatório
  5. Dica e erro
  6. Com Select
  7. Id do consumidor prevalece
  8. Grupo
  9. Com contador
  10. Desabilitado

Quando usar

Em volta de todo Input, Select ou controle de formulário que precise de rótulo, dica ou erro — ou seja, quase sempre.

Faça

  • Passe um controle como filho: é nele que o FormField põe id, aria-invalid, aria-describedby e aria-required.
  • Escreva a dica como instrução ("Use o e-mail da empresa"); ela continua visível quando o erro aparece.
  • Escreva o erro dizendo como acertar: "Informe um e-mail com @", não "Inválido".

Evite

  • Mais de um filho sem as="fieldset": com uma lista de filhos, o campo único não liga nenhum. Vários controles para uma pergunta são um grupo.
  • Limitar nome ou endereço com o contador: gente de verdade não cabe no limite de alguém.
  • Mostrar o erro antes de a pessoa terminar de preencher.

Quando não usar. Para o Checkbox, o Radio e o Toggle soltos, o rótulo já vem pela prop label. Para um grupo de opções, use as="fieldset" (ou o RadioGroup, para rádios).

Nota de uso

Grupo (E59): as="fieldset" junta várias opções numa pergunta, com a dica e o erro ligados ao <fieldset>. O contador liga o "142 de 280 caracteres" ao campo — e não se limita nome nem endereço. Com asterisco nos campos, a LegendaDeObrigatorio vai uma vez no topo. O erro está ligado ao campo por aria-describedby e é anunciado por região viva. Esta é a fonte única de aria-invalid do sistema: o Checkbox, o Radio e o Toggle derivam o estado visual dela. Com dica e erro, os dois aparecem e o campo é descrito pelos dois, dica primeiro — até a E48 o erro escondia a dica, que é justamente a instrução de como acertar. Com o `ResumoDeErros` (E85), passe anunciarErro={false}: o resumo é o alerta do envio, e o erro continua ligado ao campo, com "Erro:" na frente para quem ouve.

Anatomia

As partes, na ordem em que o olho — e o teclado — passam.

  1. Rótulo — Um Label ligado ao controle, com asterisco se `required` e vermelho com ícone se houver erro.
  2. Controle — O filho — Input, Select… —, com os atributos de ligação injetados.
  3. Dica — `hint`, em `text-xs`, abaixo do controle.
  4. Contador — `contador={{ minimo, maximo }}` (E152), um ou os dois: "142 de 280 caracteres", "faltam 12 para o mínimo de 50". Sem `atual`, conta pelo valor do controle. Ligado por `aria-describedby`; acima do limite, vermelho com ícone e quanto passou; o restante é anunciado depois que a pessoa para de digitar.
  5. Erro — `error`, vermelho com ícone, com "Erro:" na frente para quem ouve (E85); `role="alert"` — menos com `anunciarErro={false}`, quando o formulário tem o ResumoDeErros.
  6. Grupo — Com `as="fieldset"`: `<fieldset>` com `<legend>`; a dica, o contador e o erro ficam ligados ao grupo, e os filhos não são clonados.

Estados

Os estados que a peça tem no código, e o que muda em cada um.

Estados da peça e o que muda em cada um
EstadoO que muda
PadrãoRótulo e controle; aria-describedby só se houver dica.
Obrigatóriorequired: asterisco no rótulo e aria-required no controle.
Com dicaA dica aparece e descreve o controle.
Com erroRótulo vermelho com ícone, mensagem com role="alert", aria-invalid no controle — que pinta a própria borda de vermelho.
Dica e erroOs dois aparecem, e o controle é descrito pelos dois, dica primeiro.

Comportamento

Como a peça reage em cada situação
SituaçãoO que acontece
Erro apareceÉ anunciado na hora pelo role="alert". Com anunciarErro={false} (E85), não: o ResumoDeErros é o alerta, e o erro fica na descrição do campo.
Filho com `id` próprioO id do filho prevalece sobre htmlFor e sobre o gerado.

Relacionados