TextField

Campo de texto com rótulo, ajuda e validação, em uma ou várias linhas.

O TextField junta rótulo, campo, descrição e erro em um único componente acessível. Dentro dele ficam Input (uma linha), TextArea (várias), InputGroup (com prefixo ou sufixo) e, para busca, o SearchField. Campos do Admin não têm borda: o limite vem do fundo tonalizado e do anel de foco azul.

import { Description, FieldError, Input, Label, TextField } from "@rastreio-x/ui";

Padrão

O Label fica sempre visível. Placeholder é só exemplo de preenchimento, nunca o rótulo.

Nome da Loja

Playground

Ligue estados como obrigatório, desabilitado e inválido; o campo reage ao vivo.

Nome da Loja

import { FieldError, Input, Label, TextField } from "@rastreio-x/ui";

<TextField>
  <Label>Nome da Loja</Label>
  <Input placeholder="Ex.: Casa Aurora" />
  <FieldError>Informe o nome da Loja.</FieldError>
</TextField>

Com descrição

Description explica onde o dado aparece ou o formato esperado.

E-mail de SuporteAparece no rodapé da Página pública.

Validação

isInvalid com FieldError troca a descrição pela mensagem do erro. A mensagem diz o que fazer, não só que há erro.

Nome da LojaUse pelo menos 3 letras no nome da loja.

Várias linhas

Troque o Input por TextArea e defina rows.

Mensagem ao ClienteAté 280 caracteres.

Estados

Desabilitado e somente leitura mantêm o rótulo visível.

Desabilitado

Somente leitura

Prefixo e sufixo

InputGroup com InputGroup.Prefix, InputGroup.Input e InputGroup.Suffix mostra contexto fixo em volta do valor.

Endereço da Página

https://

.sualoja.com.br

Busca

O SearchField traz o ícone de busca e o botão de limpar. Sem rótulo visível, passe aria-label.

Anatomia

TextField

A raiz é um contêiner; as peças são componentes soltos da fachada: Label, Input ou TextArea, Description e FieldError.

Propriedades

Raiz (TextField):

TextField
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`autoComplete`	`string`	-	Tipo de preenchimento automático que o navegador pode oferecer.
`autoCorrect`	`string`	-	Ativa ou desativa a autocorreção do teclado.
`autoFocus`	`boolean`	-	Foca o elemento ao renderizar.
`children`	`ChildrenOrFunction<TextFieldRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<TextFieldRenderProps>`	`'react-aria-TextField'`	Classes CSS aplicadas ao elemento.
`defaultValue`	`string`	-	Valor inicial, para uso não controlado.
`enterKeyHint`	`'search' \| 'enter' \| 'done' \| 'go' \| 'next' \| 'previous' \| 'send'`	-	Rótulo sugerido para a tecla Enter em teclados virtuais.
`excludeFromTabOrder`	`boolean`	-	Tira o elemento da ordem do Tab. Evite, salvo quando há outro caminho pelo teclado.
`form`	`string`	-	Id do `<form>` ao qual o elemento está associado.
`fullWidth`	`boolean`	-	Ocupa toda a largura disponível.
`id`	`string`	-	Identificador único do elemento.
`inputMode`	`'email' \| 'text' \| 'search' \| 'none' \| 'tel' \| 'url' \| 'numeric' \| 'decimal'`	-	Tipo de teclado virtual sugerido.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`isInvalid`	`boolean`	-	Marca o valor como inválido e mostra o estado de erro.
`isReadOnly`	`boolean`	-	Permite selecionar e copiar o valor, mas não alterá-lo.
`isRequired`	`boolean`	-	Exige um valor antes de enviar o formulário.
`maxLength`	`number`	-	Máximo de caracteres aceitos.
`minLength`	`number`	-	Mínimo de caracteres exigidos.
`name`	`string`	-	Nome do campo enviado com o formulário.
`onChange`	`((value: string) => void)`	-	Chamada quando o valor ou a seleção muda.
`pattern`	`string`	-	Expressão regular que o valor deve satisfazer.
`render`	`DOMRenderFunction<'div', TextFieldRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`spellCheck`	`string`	-	Ativa ou desativa a verificação ortográfica.
`style`	`StyleOrFunction<TextFieldRenderProps>`	-	Estilos em linha aplicados ao elemento.
`type`	`'email' \| 'password' \| 'text' \| 'search' \| (string & {}) \| 'tel' \| 'url'`	`'text'`	Tipo do campo: `text`, `email`, `password`, `search`, `tel` ou `url`.
`validate`	`((value: string) => ValidationError \| true \| null \| undefined)`	-	Função de validação: devolve a mensagem de erro, ou `true` ou `null` quando o valor é válido.
`validationBehavior`	`'native' \| 'aria'`	`'native'`	Como validar: `native` usa a validação do navegador; `aria` só marca o estado e anuncia o erro.
`value`	`string`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.
`variant`	`'primary' \| 'secondary'`	`"primary"`	Estilo: `primary` (com sombra suave) ou `secondary` (sem sombra, para uso dentro de cartões).

Campo (Input):

Input
Prop	Tipo	Padrão	Descrição
`children`	`React.ReactNode`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<InputRenderProps>`	`'react-aria-Input'`	Classes CSS aplicadas ao elemento.
`fullWidth`	`boolean`	-	Ocupa toda a largura disponível.
`placeholder`	`string`	-	Texto de apoio exibido quando o campo está vazio.
`render`	`DOMRenderFunction<'input', InputRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`style`	`StyleOrFunction<InputRenderProps>`	-	Estilos em linha aplicados ao elemento.
`variant`	`'primary' \| 'secondary'`	-	Estilo: `primary` (com sombra suave) ou `secondary` (sem sombra, para uso dentro de cartões).

Várias linhas (TextArea):

TextArea
Prop	Tipo	Padrão	Descrição
`children`	`React.ReactNode`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<InputRenderProps>`	`'react-aria-TextArea'`	Classes CSS aplicadas ao elemento.
`fullWidth`	`boolean`	-	Ocupa toda a largura disponível.
`render`	`DOMRenderFunction<'textarea', InputRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`style`	`StyleOrFunction<InputRenderProps>`	-	Estilos em linha aplicados ao elemento.
`variant`	`'primary' \| 'secondary'`	-	Estilo: `primary` (com sombra suave) ou `secondary` (sem sombra, para uso dentro de cartões).

Grupo (InputGroup):

InputGroup
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`children`	`ChildrenOrFunction<GroupRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<GroupRenderProps>`	`'react-aria-Group'`	Classes CSS aplicadas ao elemento.
`fullWidth`	`boolean`	-	Ocupa toda a largura disponível.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`isInvalid`	`boolean`	-	Marca o valor como inválido e mostra o estado de erro.
`isReadOnly`	`boolean`	-	Permite selecionar e copiar o valor, mas não alterá-lo.
`render`	`DOMRenderFunction<'div', GroupRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`role`	`'group' \| 'presentation' \| 'region'`	`'group'`	Papel ARIA do elemento.
`style`	`StyleOrFunction<GroupRenderProps>`	-	Estilos em linha aplicados ao elemento.
`variant`	`'primary' \| 'secondary'`	-	Variante visual do componente.

Animações

Sem movimento
indicativo

O campo não anima. O anel de foco azul aparece sem transição longa, e o fundo troca de tom no hover. O Input tem transição curta de cor; com prefers-reduced-motion, a folha global a reduz a 0,01 ms.

Acessibilidade

O Label é ligado ao campo (for/id); Description e FieldError entram em aria-describedby.
isRequired expõe aria-required; isInvalid expõe aria-invalid.
O anel de foco azul mantém 3:1 contra a superfície; o limite do campo (sem borda) é um desvio aceito pelo design, e o texto segue em 4,5:1.
Use o type certo (email, tel, url) para o teclado do celular.
O botão de limpar do SearchField é focável e tem nome.

Boas práticas

Faça

Rótulo sempre visível e mensagem de erro que diz como corrigir.

Evite

Placeholder no lugar do rótulo, ou erro genérico como Campo inválido.

Valide ao sair do campo ou ao enviar, não a cada tecla.
Marque obrigatórios com isRequired e diga no texto quando necessário.
Não use disabled para esconder um dado; use somente leitura quando a pessoa precisa copiar.
Dentro de cartões, use variant="secondary" para o campo contrastar com a superfície.

Relacionados

NumberField para valores numéricos.
Select para escolher entre opções conhecidas.
Checkbox para escolhas binárias de formulário.