Pharos
Navegar componentes
← Componentes

TextInput

MiscExemplo
TextInput coleta texto de formulário curto como nomes, e-mails ou consultas de busca. Use-o para valores de uma linha em que a entrada esperada é breve. Emparelhe-o com status de validação para orientar usuários em campos obrigatórios ou formatados.
Importação
import {TextInput} from '@pharos-ds/core/TextInput';

Exemplos

Área interativa

size
isDisabled
Código
import {TextInput} from '@pharos-ds/core/TextInput';

<TextInput
  size="md"
  isDisabled={false}
 />

Boas práticas

  • Faça: Sempre forneça um label visível para que usuários saibam para que serve o campo. Oculte o label apenas quando o contexto ao redor o tornar óbvio, como uma barra de busca com ícone de lupa.
  • Faça: Use status de validação com mensagem para explicar o que deu errado: "Email must include @" é melhor do que apenas deixar a borda vermelha.
  • Faça: Dimensione o input para corresponder ao comprimento esperado do conteúdo para que usuários saibam quanto digitar: small para CEPs, medium para nomes, large para URLs.
  • Faça: Adicione um botão de limpar para inputs de busca e filtro para que usuários possam redefinir rapidamente sem selecionar todo o texto.
  • Evite: Não use placeholder text como substituto de label; placeholders desaparecem no focus e não são lidos de forma confiável por leitores de tela.
  • Evite: Não use TextInput para conteúdo multi-linha como comentários ou descrições; use TextArea em vez disso.
  • Evite: Não marque todo campo como required; marque apenas campos obrigatórios para que usuários não fiquem sobrecarregados com erros de validação.
  • Evite: Não envolva um TextInput desabilitado em Tooltip para explicar por que está desabilitado; controles desabilitados engolem os eventos de hover que o wrapper precisa. Use a prop disabledMessage em vez disso.

Props

PropTipoPadrãoDescrição
type'text' | 'password' | 'email''text'O HTML input type.
label *string—Texto do label do input: sempre renderizado para acessibilidade.
value *string—Valor atual do input.
onChange(value: string, e: ChangeEvent<HTMLInputElement>) => void—Callback disparado quando o valor do input muda.
changeAction(value: string, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>—Ação assíncrona disparada após onChange (se não impedida). Dispara atualização otimista e exibe spinner de carregamento enquanto pendente.
size'sm' | 'md' | 'lg''md'Variante de size do input.
isLabelHiddenbooleanfalseOculta visualmente o label mantendo-o acessível a leitores de tela.
descriptionstring—Texto de description exibido entre o label e o input.
isOptionalbooleanfalseExibe um indicador "Optional" ao lado do label. Mutuamente exclusivo com isRequired.
isRequiredbooleanfalseExibe um indicador "Required" ao lado do label e define aria-required. Mutuamente exclusivo com isOptional.
isDisabledbooleanfalseDesabilita o input, impedindo interação e esmaecendo o elemento.
disabledMessagestring—Explica por que o input está desabilitado. Com isDisabled, exibe um tooltip no hover/foco via teclado e mantém o input focável via aria-disabled (o campo torna-se read-only). Use isto em vez de envolver um TextInput desabilitado em Tooltip. Controles desabilitados engolem os eventos de hover que um Tooltip externo precisa.
isLoadingbooleanfalseColoca o input em estado de carregamento, exibindo um spinner e definindo aria-busy.
placeholderstring—Texto placeholder exibido quando o input está vazio.
labelTooltipstring—Texto de tooltip exibido em um ícone de info no final do label.
startIconIconType—Componente de ícone SVG exibido no início do input. Veja `pharos docs icons` para nomes semânticos válidos.
status{type: 'error' | 'warning' | 'success', message?: string}—Status de validação: aplica uma borda colorida e ícone de status. Se message for fornecida, exibe uma mensagem flutuante abaixo do input. O tipo error também define aria-invalid.
statusVariant'attached' | 'detached' | 'tooltip''attached'Como a mensagem de status é posicionada em relação ao input. attached sobrepõe diretamente abaixo do input (tratamento com borda); detached flutua abaixo como elemento separado com espaçamento; tooltip oculta a caixa de mensagem e a exibe em um tooltip no ícone de status.
hasClearbooleanfalseExibe um botão de limpar (×) quando o input tem um valor. Clicar nele limpa o value e devolve o foco ao input.
hasAutoFocusbooleanfalseFoca automaticamente o input ao montar.
htmlNamestring—Atributo HTML name do input, útil para submissões de formulário.
widthSizeValue—Largura do campo (número = pixels, string usada como está, ex.: "100%"). Dimensiona o campo inteiro (label, controle e status) para que permaneçam alinhados.
Pacote: @pharos-ds/core · Import: @pharos-ds/core/TextInput
TextInput · Pharos