Input

Componente estável e recomendada para novos projetos.

Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.

Visão Geral

O componente br-input é o controle padrão do GovBR-DS para entrada de dados textuais em linha única. Totalmente integrado à validação nativa de formulários HTML via ElementInternals (formAssociated), ele suporta múltiplos tipos de entrada, máscaras e formatação.

Para que serve

• Captura de dados curtos em formulários: Entrada de textos, senhas, endereços de e-mail, números, telefones, documentos e termos de busca.
• Alternância de visualização de senha: No tipo type="password", oferece botão embutido para alternar entre texto visível e caracteres mascarados com feedback acessível.
• Validação e mensagens contextuais: Comunica valor, validade e mensagens de erro ou orientação diretamente ao formulário HTML e leitores de tela.
• Densidade e ícones de apoio: Suporta diferentes densidades visuais (alta, média e baixa) e ícones prefixados ou sufixados para enriquecer a experiência.

Quando utilizar

• Utilize quando:
  • A informação digitada couber em uma única linha (ex.: nome, CPF, e-mail, valor monetário, busca).
• Evite e prefira outro componente quando:
  • O texto for extenso ou exigir múltiplas linhas (prefira br-textarea).
  • A escolha for feita a partir de uma lista pré-determinada de opções (prefira br-select, br-radio ou br-checkbox).
  • O valor for uma data ou hora estruturada (prefira br-datetime-picker).

Estrutura e Slots

O br-input é composto pelo campo de entrada e slots de apoio:

• icon: Slot para ícone de apoio visual (prefixado ou sufixado ao campo de digitação).
• feedback: Slot para exibição de mensagens de validação contextual (como br-message).

Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Padrão

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Mais opções

Tela cheia

Carregando preview…

HTML

Controles do componente

Console: logs, eventos e erros

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Desfazer alteração

Refazer alteração

Comparar alterações

Formatar código

Resetar código para o estado inicial

Escolher formato para copiar

Propriedades

actionLabel

Atributo	action-label
Descrição	Texto exibido no botão de ação à direita do input.
Tipo	string
Valor padrão	---

actionTabIndex

Atributo	action-tab-index
Descrição	Define o tabindex do botão de ação. Útil para remover o botão da sequência de tabulação quando o foco é gerenciado externamente (ex.: br-select). Aceita inteiros maiores ou iguais a -1; valores inválidos são ignorados.
Tipo	number
Valor padrão	---

ariaLabel

Atributo	aria-label
Descrição	Nome acessível usado quando não há um rótulo visual.
Tipo	string
Valor padrão	null

autocomplete

Atributo	autocomplete
Descrição	Controla o comportamento de preenchimento automático do navegador para o input.
Tipo	"off" | "on"
Valor padrão	---

autocorrect

Atributo	autocorrect
Descrição	Controla a correção automática do texto.
Tipo	string
Valor padrão	'off'

borderless

Atributo	borderless
Descrição	Remove a borda do input quando não está em foco. Útil para composições contextuais (ex.: paginação).
Tipo	boolean
Valor padrão	false

controlWidth

Atributo	control-width
Descrição	Largura do campo de entrada (por exemplo, '88px'). Quando definido, sobrescreve a largura padrão de 100%.
Tipo	string
Valor padrão	---

customId

Atributo	custom-id
Descrição	Identificador único. Caso não seja fornecido, um ID gerado automaticamente será usado.
Tipo	string
Valor padrão	generateUniqueId('br-input')

density

Atributo	density
Descrição	Ajusta a densidade, alterando o espaçamento interno para um visual mais compacto ou mais expandido. Aceita small, medium ou large. Valores inválidos usam medium.
Tipo	"large" | "medium" | "small"
Valor padrão	'medium'

disabled

Atributo	disabled
Descrição	Desativa o input, tornando-o não interativo.
Tipo	boolean
Valor padrão	false

feedbackState

Atributo	feedback-state
Descrição	Estado de feedback canônico. Quando informado, tem precedência sobre state.
Tipo	"danger" | "info" | "success" | "warning"
Valor padrão	---

helpText

Atributo	help-text
Descrição	Texto adicional que fornece ajuda ou informações sobre o input.
Tipo	string
Valor padrão	---

highlight

Atributo	highlight
Descrição	Habilita destaque visual. Quando informada, tem precedência sobre isHighlight.
Tipo	boolean
Valor padrão	---

inline

Atributo	inline
Descrição	Exibe rótulo e controle em linha. Quando informada, tem precedência sobre isInline.
Tipo	boolean
Valor padrão	---

isHighlight Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	is-highlight
Depreciação	Use highlight.
Descrição	Se verdadeiro, o input terá destaque visual.
Tipo	boolean
Valor padrão	false

isInline Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	is-inline
Depreciação	Use inline.
Descrição	Se verdadeiro, o rótulo e o input estarão na mesma linha (layout inline).
Tipo	boolean
Valor padrão	false

label

Atributo	label
Descrição	Texto exibido como rótulo do input.
Tipo	string
Valor padrão	---

mask

Atributo	mask
Descrição	Formata o valor durante a digitação; use # para marcar posições numéricas. Diferentemente de pattern, esta prop não substitui uma regra de validação.
Exemplo de uso	<br-input label="CPF" mask="###.###.###-##"></br-input>
Tipo	string
Valor padrão	---

max

Atributo	max
Descrição	Define o valor máximo para campos de entrada numéricos. Deve ser um número finito; valores inválidos são ignorados.
Tipo	number
Valor padrão	---

maxlength

Atributo	maxlength
Descrição	Define o comprimento máximo do valor do campo de entrada. Deve ser um inteiro não negativo; valores inválidos são ignorados.
Tipo	number
Valor padrão	---

min

Atributo	min
Descrição	Define o valor mínimo para campos de entrada numéricos. Deve ser um número finito; valores inválidos são ignorados.
Tipo	number
Valor padrão	---

minlength

Atributo	minlength
Descrição	Define o comprimento mínimo do valor do campo de entrada. Deve ser um inteiro não negativo; valores inválidos são ignorados.
Tipo	number
Valor padrão	---

multiple

Atributo	multiple
Descrição	Se verdadeiro, permite a entrada de múltiplos e-mails (quando type="email").
Tipo	boolean
Valor padrão	false

name

Atributo	name
Descrição	Nome do input, utilizado para identificação em formulários.
Tipo	string
Valor padrão	---

pattern

Atributo	pattern
Descrição	Expressão regular usada para validar o valor final, sem alterar o texto digitado. Diferentemente de mask, esta prop valida, mas não formata a entrada.
Exemplo de uso	<br-input label="CPF" pattern="[0-9]{11}"></br-input>
Tipo	string
Valor padrão	---

placeholder

Atributo	placeholder
Descrição	Texto exibido dentro do input quando está vazio, fornecendo uma dica ou sugestão ao usuário.
Tipo	string
Valor padrão	---

readonly

Atributo	readonly
Descrição	Se verdadeiro, o valor do input é exibido, mas não pode ser editado pelo usuário.
Tipo	boolean
Valor padrão	false

required

Atributo	required
Descrição	Se verdadeiro, o input é obrigatório e deve ser preenchido antes que o formulário possa ser enviado.
Tipo	boolean
Valor padrão	false

state

Atributo	state
Descrição	Define o estado do input
Observações	O estado é propagado para o slot de feedback, mas também pode ser controlado diretamente pelo conteúdo do slot.
Tipo	"danger" | "info" | "success" | "warning"
Valor padrão	---

step

Atributo	step
Descrição	Define o valor do passo para campos de entrada numéricos. Deve ser um número finito maior que 0; valores inválidos são ignorados.
Tipo	number
Valor padrão	---

type

Atributo	type
Descrição	Especifica o tipo de entrada do campo.
Tipo	"color" | "email" | "hidden" | "number" | "password" | "range" | "search" | "tel" | "text" | "url"
Valor padrão	'text'

validator Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.

Atributo	validator
Descrição	Função ou regra de validação customizada para o campo. A função pode ser síncrona ou assíncrona. Retorne uma mensagem para invalidar o campo e null ou '' para validá-lo. A regra é executada no change ou pelo método validate(), nunca a cada tecla. Em frameworks, passe a função como property binding, por exemplo: validator={validate} no React, [validator]="validate" no Angular ou :validator="validate" no Vue. Como alternativa para HTML sem binding de propriedades, uma string pode referenciar uma função global em window. A forma inline legada aceita apenas comparação simples; JavaScript arbitrário é rejeitado para manter CSP segura. Prefira sempre a função por binding. Durante validações assíncronas, o campo sinaliza aria-busy="true", exibe o indicador de carregamento e emite brInputValidationChange.
Exemplo de uso	input.validator = async (value) => { if (!value) return 'Campo obrigatório'; const disponivel = await checarDisponibilidade(value); return disponivel ? null : 'Este valor já está em uso'; };
Tipo	((value: string) => string | Promise<string>) | string
Valor padrão	---

value

Atributo	value
Descrição	Valor exibido no input. Pode ser alterado pelo usuário se a propriedade readonly não estiver ativa.
Tipo	string
Valor padrão	''

Slots

Nome	Descrição
"action"	Botão à direita do input.
"feedback"	Mensagem de feedback como resposta específica a uma interação do usuário com o input. Pode ser feedback de erro, aviso, sucesso ou informação.
"help-text"	Personalização do texto de ajuda.
"icon"	Ícone à esquerda do input.
"validation-loading" Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Indicador exibido enquanto o validator assíncrono está pendente.

Eventos

Evento	Descrição	Depreciação	Propagação
brClear	Emitted when the input clear button action is triggered.	---	true
brInputValidationChange Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Informa o início e o resultado do validator, inclusive quando ele consulta um serviço remoto. O detail contém validating, valid e message; escrita programática e reset não representam interação do usuário.	---	true
valueChange Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Valor atualizado do input	Use o evento nativo input e leia event.target.value.	true

Métodos

checkValidity

Descrição	Retorna true se o valor do input for válido, caso contrário false. Se o input for inválido, dispara um evento 'invalid'.
Assinatura	checkValidity() => Promise<boolean>
Parâmetros	---

getValidationState

Descrição	Retorna um snapshot serializável da Constraint Validation API.
Assinatura	getValidationState() => Promise<FormValidationState>
Parâmetros	---

reportValidity

Descrição	Retorna true se o valor do input for válido, caso contrário false. Se o input for inválido, exibe uma mensagem de erro padrão do navegador.
Assinatura	reportValidity() => Promise<boolean>
Parâmetros	---

select

Descrição	Seleciona todo o texto do controle nativo, conforme HTMLInputElement.select().
Assinatura	select() => Promise<void>
Parâmetros	---

setCustomValidity

Descrição	Define uma mensagem de validação customizada para o input. Se a mensagem for uma string vazia, o erro customizado é limpo.
Assinatura	setCustomValidity(message: string) => Promise<void>
Parâmetros	message: - Mensagem de erro customizada ou string vazia para limpar

setRangeText

Descrição	Substitui um intervalo de texto usando a API nativa do input.
Assinatura	setRangeText(replacement: string, start?: number, end?: number, selectionMode?: SelectionMode) => Promise<void>
Parâmetros	replacement: start: end: selectionMode:

setSelectionRange

Descrição	Define o intervalo selecionado no controle nativo.
Assinatura	setSelectionRange(start: number, end: number, direction?: "forward" | "backward" | "none") => Promise<void>
Parâmetros	start: end: direction:

showPicker

Descrição	Abre o picker nativo quando o navegador e o tipo do input oferecem essa API.
Assinatura	showPicker() => Promise<void>
Parâmetros	---

stepDown

Descrição	Decrementa o valor numérico pelo step nativo.
Assinatura	stepDown(n?: number) => Promise<void>
Parâmetros	n:

stepUp

Descrição	Incrementa o valor numérico pelo step nativo.
Assinatura	stepUp(n?: number) => Promise<void>
Parâmetros	n:

validate Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.

Descrição	Executa a regra customizada e retorna se o campo está válido. Se o validator for assíncrono, aguarda a resposta e ignora resultados antigos quando uma execução posterior já começou.
Assinatura	validate() => Promise<boolean>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"action-button"	Botão interno reexportado do br-button da ação.
"action"	Botão de ação lateral.
"container"	Contêiner visual principal do input.
"feedback"	Slot de feedback.
"group"	Grupo que contém ícone, input, botão e ajuda.
"help-text"	Texto de ajuda ou slot de ajuda.
"icon"	Contêiner do slot de ícone.
"input"	Elemento input nativo.
"label"	Rótulo do input.

Validação

Para o contrato compartilhado pelos controles, consulte o guia de formulários. Esta seção mostra apenas o comportamento específico de br-input.

Restrições nativas

Use primeiro os atributos HTML disponíveis para o tipo do campo: required, pattern, min, max, step, minlength e maxlength.

<form id="cadastro">
  <br-input name="email" type="email" label="E-mail" required maxlength="120"></br-input>
  <button type="submit">Salvar</button>
</form>

Consulte a validade com checkValidity() ou getValidationState(). Use reportValidity() quando também precisar apresentar a mensagem ao usuário.

Regra personalizada

Use validator para uma regra síncrona ou assíncrona. Passe a função como propriedade JavaScript; ela recebe o valor atual e deve retornar uma mensagem para invalidar o campo ou null para aceitá-lo.

const cpf = document.querySelector('br-input#cpf');

cpf.validator = (value) =>
  value.replace(/\D/g, '').length === 11 ? null : 'Informe um CPF com 11 dígitos.';

const valid = await cpf.validate();

Nos frameworks, use o binding de propriedade correspondente:

// React
<BrInput label="CPF" validator={validateCpf} />

<!-- Angular -->
<br-input label="CPF" [validator]="validateCpf"></br-input>

<!-- Vue -->
<br-input label="CPF" :validator="validateCpf"></br-input>

O atributo textual validator="nomeDaFuncao" existe para compatibilidade com funções globais, mas o binding de função é mais explícito e seguro. Nunca monte esse atributo com conteúdo fornecido pelo usuário.

Momento da validação

O componente executa validator ao confirmar uma alteração com change ou quando a aplicação chama validate(). Ele não valida a cada tecla. Atribuições programáticas a value e o reset do formulário não emitem eventos de interação; chame validate() quando precisar validar imediatamente o novo valor.

Durante uma validação assíncrona, o campo recebe aria-busy="true" e mostra um indicador. Use o slot validation-loading para substituir esse conteúdo. Se duas validações se sobrepuserem, somente o resultado mais recente é aplicado.

O evento brInputValidationChange informa o ciclo da validação:

1. início: { validating: true, valid: null, message: null };
2. conclusão: { validating: false, valid, message }.

Uma Promise rejeitada invalida o campo com uma mensagem genérica. Trate o erro dentro do validator quando a aplicação precisar mostrar uma orientação específica.

Mensagens e envio

Sem conteúdo no slot feedback, o componente apresenta a mensagem com br-message. Preencha o slot quando precisar controlar a marcação da mensagem; não renderize uma segunda mensagem para o mesmo erro.

setCustomValidity() mantém uma mensagem externa separada do resultado de validator e tem precedência enquanto não for limpa com uma string vazia.

Antes de enviar dados que dependem de validação assíncrona, aguarde o componente:

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  if (!(await input.validate()) || !form.checkValidity()) return;

  form.submit();
});

Acessibilidade

Forneça sempre um label visível ou uma relação <label for>. O nome acessível deve conter o texto visual. Erros devem ter texto associado por aria-describedby/aria-errormessage; o componente sincroniza aria-invalid quando a validade é apresentada.

O foco é delegado ao <input> interno e focus() no host deve colocar o usuário no campo. Use readonly para leitura sem edição e disabled quando o controle não puder receber foco nem participar do formulário. Não use tabindex positivo.

Eventos nativos

Elemento HTML de referência

br-input representa o <input> do type informado e mantém um <input> dentro do Shadow DOM.

Como ouvir os eventos

const input = document.querySelector('br-input');
input.addEventListener('input', () => console.log(input.value));
input.addEventListener('change', () => console.log(input.value));

Eventos nativos suportados

Evento	Quando ocorre	Bubbles	Composed	Cancelable	Host	Observações
beforeinput	antes da edição	Sim	Sim	Sim, conforme a edição	Sim	O navegador ajusta o alvo externo para o host.
change	no commit ou blur	Sim	Sim	Não	Sim	Evento sintético emitido uma vez.
focus / blur	entrada/saída de foco	Não	Sim	Não	Sim	Para delegação, use focusin/focusout.
focusin / focusout	entrada/saída com bubbling	Sim	Sim	Não	Sim	Funciona em ancestral.
input	a cada edição	Sim	Sim	Não	Sim	InputEvent sintético após sincronizar value.

Eventos não suportados ou ainda não caracterizados

Composição, clipboard e seleção têm propagação caracterizada com eventos construídos em Chromium; gatilhos reais e os outros engines permanecem pendentes. Escrita em value, inicialização e reset não emitem eventos de interação.

Eventos customizados

valueChange é alias depreciado. Prefira input/change; não existe brInput nem brChange.

Valor, frameworks e acessibilidade

Leia event.target.value, validade pelos métodos públicos e dados por FormData. HTML usa addEventListener; React usa ref quando necessário; Angular e Vue usam seus adaptadores de formulário. Teclado, edição e foco pertencem ao input interno e são expostos pelo host.

Evidência de teste

src/shared/contracts/platform-contract.e2e.tsx cobre ordem, flags, target, currentTarget, caminho, delegação, reset, FormData, validade, múltiplas instâncias e reinserção em Chromium headless.

Atributos nativos

O host FACE aceita name, form, required, disabled, readonly e autofocus. type, autocomplete, placeholder, min, max, minlength, maxlength, multiple, pattern e step são encaminhados ao <input> interno quando aplicáveis ao tipo.

form e autofocus não são props Stencil: a associação e o foco seguem a plataforma. Os métodos select(), setRangeText(), setSelectionRange(), stepUp(), stepDown() e showPicker() encaminham as operações equivalentes ao input nativo. A disponibilidade e os erros dessas operações dependem do type e do navegador, como em HTMLInputElement.

Documentações relacionadas

Consulte o guia geral de dados remotos para integrar validações assíncronas, controlar concorrência e manter o transporte sob responsabilidade da aplicação.

Também são relacionados:

• Textarea, para validação remota de texto em áreas maiores;
• Select, para busca remota e atualização assíncrona de opções;
• Formulários, para integração com a Constraint Validation API.

Dependências

Usado por

• br-datetime-input
• br-select-input
• br-slider

Depende de

• br-icon
• br-button
• br-message
• br-loading

Gráfico

Migração de <br-input> (1.x → 2.x)

O input mantém a maior parte das propriedades de formulário. A migração principal é substituir estados visuais antigos pela propriedade semântica state e mover ícones para a composição atual.

Propriedades

API 1.x	API 2.x	Ação na migração
icon, iconSign, iconSubmit	slots/composição de ícone	Não dependa dos dados de ícone da 1.x; declare o ícone na composição atual.
inline	inline	Mantenha; is-inline é alias legado.
isHighlight	highlight	Use o nome canônico atual.
ispassword	type="password"	Use o tipo nativo.
label, placeholder, disabled, density, id, name, value, mask	mesmos nomes	Mantenha e revise o formato camelCase para atributos kebab-case.
success, danger, info, warning	state	Converta para o estado semântico correspondente.

O campo continua emitindo eventos nativos input e change. Use as APIs de validação e feedbackState da versão atual quando precisar mostrar mensagens.

Exemplo

1.x:

<br-input ispassword is-highlight label="Senha" icon="lock"></br-input>

2.x:

<br-input type="password" highlight label="Senha" state="info">
  <i slot="start" class="fas fa-lock" aria-hidden="true"></i>
</br-input>