Pular para o conteúdo
Formulário

Field

/componentes/field.mdmarkdown cru, para quem lê com agent em vez de olho

Básico

Razão social como consta no CNPJ

Com erro

Informe um email válido

Tamanhos

Desabilitado

Não pode ser alterado depois do cadastro

Importar
import { Field } from '@rivocode/ui'

Quando usar

Raiz do campo de formulário. Liga rótulo, ajuda e erro por acessibilidade.

Compõe com FieldLabel, Input, FieldDescription e FieldError. A ligação é automática: não escreva htmlFor nem aria-describedby à mão.

Marque inválido com invalid na raiz e mostre a mensagem com <FieldError match>. disabled na raiz desabilita o conjunto.

Quando não usar

Dentro de um formulário do React Hook Form, use FormField, de @rivocode/ui/form: ele monta rótulo, controle, ajuda e erro numa linha e acha o control do Form sozinho. O Field cru é para o campo solto, ou para o estado que mora fora do React Hook Form.

Para agrupar campos que respondem à mesma pergunta (endereço, pagamento), use Fieldset: a legenda dele é anunciada junto com o rótulo de cada campo de dentro. O Field é um controle só, com um rótulo só.

No React Native

Traduz: o @rivocode/ui-native exporta Field - label, description e error como props, e o label nomeia o campo de digitar que está dentro; validate, validationMode e validationDebounceTime com o nome, a assinatura e o momento do web, e o error explícito vence o validate; o validate recebe o texto dos campos de digitar (Input, Textarea, MaskedInput, InputGroup, PasswordInput) e o valor dos que abrem folha (Autocomplete, Select, Combobox, DatePicker, DateRangePicker), e o erro é anunciado, acende a borda deles e vira a dica; nos de folha, fechar a folha é a saída do campo, e o Concluir e a tecla de envio são o envio. O texto que chega depois entra por fade; necessity com o nome do web, e no required o asterisco também se fala ("obrigatório"), porque o controle do celular não tem required que o leitor anuncie. A API não é a mesma do web (no nativo tudo é controlado), e a tabela de paridade diz o que muda peça a peça.

API

PropTipoPadrão
actionsRef0.4.0

Uma ref para as ações imperativas.

RefObject<FieldRootActions | null>sem padrão
dirty0.4.0

Se o valor do campo mudou desde o inicial.

booleansem padrão
disabled0.4.0

Se a peça deve ignorar a interação do usuário.

booleanfalse
invalid0.4.0

Se o campo está inválido.

booleansem padrão
name0.4.0

Identifica o campo quando o formulário é enviado.

stringsem padrão
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, FieldRootState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão
touched0.4.0

Se o campo já foi tocado.

booleansem padrão
validate0.4.0

A function for custom validation.

((value: unknown, formValues: Record<string, any>) => void | string | string[] | Promise<void | string | string[] | null> | null)sem padrão
validationDebounceTime0.4.0

Quanto esperar entre duas chamadas de `validate` quando `validationMode="onChange"`.

number0
validationMode0.4.0

Quando o campo é validado.

FormValidationMode"onSubmit"

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

Partes

Field se monta com estas peças. Todas vivem nesta página, porque separar cada uma num endereço obrigaria a abrir seis abas para montar uma tela.

FieldDescription

/field-description.md

A ajuda abaixo do campo: formato esperado, para que serve, o que vai acontecer.

Entra no aria-describedby do controle, então é lida junto com o campo em vez de ficar invisível para quem usa leitor de tela.

PropTipo
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, FieldDescriptionState> | ReactElement<unknown, string | JSXElementConstructor<any>>

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

FieldError

/field-error.md

A mensagem de erro do campo.

Só aparece quando o campo está inválido, e marca aria-invalid no controle junto. Vermelho sozinho não diz nada a quem não distingue a cor, a frase é que diz.

PropTipo
match0.4.0

Se mostra a mensagem de erro conforme o [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) do campo.

boolean | keyof ValidityState
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, FieldErrorState> | ReactElement<unknown, string | JSXElementConstructor<any>>

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

FieldLabel

/field-label.md

O rótulo do campo.

Dentro de um Field, a Base UI liga rótulo e controle sozinha, sem htmlFor escrito à mão e sem id inventado. Clicar no rótulo foca o campo.

Obrigatório e opcional

necessity põe a marca ao lado do texto. optional escreve "(opcional)" em texto, que entra no nome do campo para o leitor de tela; required desenha um asterisco escondido do leitor, que ouve o required do controle, então ponha required no controle também.

<Field name="complemento">
  <FieldLabel necessity="optional">Complemento</FieldLabel>
  <Input placeholder="Ex.: Sala 4" />
</Field>

A regra da casa é marcar a minoria. Cadastro, matrícula e checkout, onde quase tudo é obrigatório, marcam só o opcional, e é o padrão quando há dúvida: texto escrito não depende de legenda nem de cor. Filtro e preferência, onde quase tudo é opcional, marcam só o obrigatório. Nunca os dois no mesmo formulário, e nunca nenhum quando há dos dois tipos.

PropTipoPadrão
labels

Os textos da peca, para trocar o idioma: `optional` e a marca do opcional.

Partial<FieldLabelLabels>sem padrão
nativeLabel0.4.0

Se a peça renderiza um `<label>` nativo quando é trocada pela prop `render`.

booleantrue
necessity

A marca de obrigatorio ou de opcional, ao lado do texto.

FieldNecessitysem padrão
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, FieldLabelState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.