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 br-input captura dados de texto em linha única, como nomes, e-mails, números ou senhas.

Configure label, placeholder e o tipo em type (como text, email, password, number). Use state (success, danger, info, warning) para indicar validação.

<br-input label="E-mail" type="email" placeholder="nome@exemplo.com"></br-input>
<br-input label="Senha" type="password"></br-input>

Em formulários HTML, o componente integra-se nativamente via ElementInternals, participando do submit e da validação nativa com required.

Quando usar

• Entrada de texto curto que cabe em uma única linha (nome, CPF, e-mail, telefone).
• Campo de busca ou senha com alternância de visualização.

Quando evitar

• Textos longos ou com quebra de linha: use br-textarea.
• Escolha entre opções pré-definidas: use br-select ou br-radio.

Consulte as diretrizes de design do GovBR.

Exemplos

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

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

clearable

Atributo	clearable
Descrição	Exibe um botão para limpar o texto enquanto o campo tem valor e aceita edição. O botão fica à esquerda do botão de ação, quando houver. Ao ser acionado, limpa o valor, emite input uma única vez e brClear, e devolve o foco ao campo. Não é exibido com disabled ou readonly.
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. 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	Emitido quando o usuário aciona o botão de limpar (clearable), depois que o valor foi limpo e o evento input foi disparado.	---	true
brInputActionClick	Notifica a ativação do botão do slot action por clique ou teclado. Emitido no host com detail.originalEvent contendo o clique original. Propaga e atravessa Shadow DOM; não é cancelável nem altera o clique nativo. Não emite para o campo textual, botão de senha, inicialização ou controle desabilitado.	---	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.
"clear"	Botão de limpar exibido com clearable enquanto há texto editável.
"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();
});

Envio com Enter

Como o <input> nativo, o br-input envia o formulário ao pressionar Enter (submissão implícita). O envio segue o botão padrão do formulário, o primeiro elemento com type="submit", inclusive br-button: se ele estiver desabilitado, o formulário não é enviado. Chame event.preventDefault() no keydown para impedir o envio.

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.

brInputActionClick identifica a ativação do botão que envolve o slot action, por clique ou teclado. Não ocorre ao clicar no campo, no botão de senha ou quando o controle está desabilitado. O evento é emitido no host com bubbles: true, composed: true e cancelable: false; o detail.originalEvent contém o clique original. A emissão não cancela nem interrompe o clique nativo. Para impedir sua propagação, use event.detail.originalEvent.stopPropagation() durante o tratamento.

input.addEventListener('brInputActionClick', () => {
  console.log('Ação do campo ativada');
});

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
• br-table-bar

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 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>