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

Design System

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

Validação e Acessibilidade

• Validação: Utilize a propriedade state="danger" para indicar um campo inválido e forneça o motivo no slot feedback utilizando o <br-message>. O gerenciamento da regra de validação é de responsabilidade da aplicação ou framework consumidor.
• Acessibilidade: Este componente respeita a navegação por teclado e automaticamente sinaliza erros para leitores de tela quando state="danger" é ativado. Se o campo não possuir rótulo visual (label), use a propriedade aria-label.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

HTML

Controles

JS

CSS

Console

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Formatar código

Resetar código para o estado inicial

Copiar para a área de transferência

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).
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	br-input-${inputId++}

density

Atributo	density
Descrição	Ajusta a densidade, alterando o espaçamento interno para um visual mais compacto ou mais expandido.
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	Máscara aplicada ao valor digitado (use # para marcar posições numéricas).
Tipo	string
Valor padrão	---

max

Atributo	max
Descrição	Define o valor máximo para campos de entrada numéricos.
Tipo	number
Valor padrão	---

maxlength

Atributo	maxlength
Descrição	Define o comprimento máximo do valor do campo de entrada.
Tipo	number
Valor padrão	---

min

Atributo	min
Descrição	Define o valor mínimo para campos de entrada numéricos.
Tipo	number
Valor padrão	---

minlength

Atributo	minlength
Descrição	Define o comprimento mínimo do valor do campo de entrada.
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	Define o padrão de entrada para validação.
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
Tipo	"danger" | "info" | "success" | "warning"
Valor padrão	---

step

Atributo	step
Descrição	Define o valor do passo para campos de entrada numéricos.
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

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

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.

Dependências

Usado por

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

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">
  <br-icon slot="start" icon-name="lock"></br-icon>
</br-input>

Validação

Para o contrato geral e a matriz de componentes, consulte o guia de formulários. Esta seção documenta o contrato específico do br-input.

O br-input participa da Constraint Validation API e de formulários HTML. Use as constraints nativas (required, pattern, min, max, step, minlength e maxlength) sempre que elas forem suficientes.

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

Para regras de domínio, use validator. A propriedade recebe uma função JavaScript. Em HTML puro, propriedades de função não podem ser declaradas diretamente como atributo; em frameworks, use o property binding do framework:

type InputValidator = (value: string) => string | null | Promise<string | null>;
// A prop também aceita `string` para nome de função global ou expressão legada restrita.
type InputValidatorProp = InputValidator | string;

Retorne uma mensagem para invalidar o campo e null (ou uma string vazia) para validá-lo.

Uso como prop em frameworks

O ponto importante é passar a função como propriedade, e não como texto:

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

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

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

// Vanilla Web Components
const input = document.querySelector('br-input');
input.validator = validateCpf;

No Angular, Vue e React, validateCpf deve ser uma função existente no escopo do componente:

const validateCpf = (value: string) => (value.replace(/\D/g, '').length === 11 ? null : 'Informe um CPF válido.');

Também é possível usar HTML sem property binding apontando o atributo para uma função global:

<br-input validator="validateCpfGlobal"></br-input>
<script>
  window.validateCpfGlobal = (value) => (value.replace(/\D/g, '').length === 11 ? null : 'Informe um CPF válido.');
</script>

Esse formato depende de uma função em window e não deve receber código vindo de usuário. A expressão inline legada é limitada a comparações simples e não executa JavaScript arbitrário. Para aplicações com framework, o binding de função é a opção recomendada.

Quando a validação acontece

O validator é executado:

• automaticamente quando o valor confirmado dispara change — normalmente ao sair do campo ou confirmar a edição;
• explicitamente quando a aplicação chama await input.validate().

Ele não é executado a cada tecla. Escritas programáticas em value apenas invalidam o resultado anterior; chame validate() quando quiser validar o novo valor. O reset do formulário também descarta validações pendentes.

Validação síncrona

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

cpf.validator = (value) => {
  if (value.trim() === '') return 'Informe o CPF.';
  return isCpfValid(value) ? null : 'CPF inválido. Verifique os dígitos.';
};

// Opcional: valida sem esperar um novo blur/change.
const valid = await cpf.validate();
console.log(valid); // true ou false

Sem um slot feedback, uma mensagem retornada pelo validator é renderizada automaticamente como br-message. Com um slot feedback, o conteúdo fornecido pela aplicação continua sendo usado:

<br-input id="cpf" label="CPF">
  <br-message slot="feedback" state="danger"></br-message>
</br-input>

Validação assíncrona

O validator pode consultar o servidor. Enquanto a Promise estiver pendente, o campo recebe aria-busy="true" e exibe um br-loading pequeno.

const username = document.querySelector('br-input#username') as HTMLBrInputElement;

username.validator = async (value) => {
  if (value.length < 3) return 'Use pelo menos 3 caracteres.';

  const response = await fetch(`/api/users/available?name=${encodeURIComponent(value)}`);
  if (!response.ok) throw new Error('Falha ao consultar disponibilidade');

  const { available } = await response.json();
  return available ? null : 'Este nome de usuário já está em uso.';
};

username.addEventListener('brInputValidationChange', (event) => {
  const { validating, valid, message } = event.detail;
  console.log({ validating, valid, message });
});

Para substituir o indicador padrão, use o slot validation-loading:

<br-input id="username" label="Nome de usuário">
  <span slot="validation-loading" role="status">Consultando disponibilidade…</span>
</br-input>

O componente considera somente o resultado da validação mais recente. Assim, uma resposta antiga não sobrescreve o resultado de uma edição ou validação posterior.

Evento brInputValidationChange

O evento é emitido duas vezes por execução do validator:

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

input.addEventListener('brInputValidationChange', (event) => {
  const { validating, valid, message } = event.detail;

  if (validating) {
    submitButton.disabled = true;
  } else {
    submitButton.disabled = false;
    if (!valid) console.warn(message);
  }
});

Uma Promise rejeitada produz a mensagem genérica Não foi possível validar o campo. e torna a validação inválida. Trate o erro no validator quando precisar exibir uma mensagem específica.

Mensagens externas e formulários

setCustomValidity() e a mensagem do validator são mantidos separadamente. A mensagem definida pela aplicação continua tendo precedência na validade nativa:

await input.setCustomValidity('O serviço está temporariamente indisponível.');
const valid = await input.validate(); // false, mesmo se o validator retornar null

Para limpar a mensagem externa, use await input.setCustomValidity(''). Para submeter um formulário depois de uma validação assíncrona, valide antes de chamar requestSubmit():

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const valid = await input.validate();
  if (!valid || !form.checkValidity()) return;

  // Envie os dados somente depois que a regra assíncrona terminar.
  form.submit();
});

Use getValidationState() para consultar valid, validationMessage, willValidate e os flags de ValidityState sem depender do DOM interno.

Auditoria dos demais controles de formulário

O mesmo contrato não deve ser copiado para todos os componentes sem considerar o tipo de valor e o comportamento existente:

Componente	Situação atual	Avaliação
br-button	É associado a formulário, mas não representa um campo com valor validável.	Não precisa desse contrato.
br-checkbox / br-radio	Possuem validade nativa, estados visuais valid/invalid e slot feedback.	O slot ou o br-message padrão é referenciado por ARIA sem duplicar mensagens.
br-datetime-picker	Possui controles internos de data/hora.	Fora desta entrega; requer decisão específica para o valor estruturado.
br-input	validator, validate(), loading, evento e feedback implementados.	Atendido por #1195/#1198.
br-select	Possui validator, validate(), loading, evento feedback para string/string[].	Atendido; consulte a seção de validação do br-select.
br-slider	Possui constraints numéricas (min, max, step) e setCustomValidity().	Baixa prioridade; constraints nativas cobrem a maior parte dos casos.
br-switch	Possui validade de controle booleano.	Pode receber validator síncrono apenas se houver regra de domínio comprovada.
br-tag	Possui validade relacionada à seleção/grupo.	Deve ser avaliado junto ao componente de grupo, não como validator isolado de texto.
br-textarea	Possui validator, validate(), loading, evento e feedback para valores string.	Atendido; consulte a seção de validação do br-textarea.
br-upload	Possui validade de arquivo, tamanho e tipo.	Precisa de API própria baseada em File/FileList; não deve receber o tipo string do input.

br-upload, br-slider, br-switch, br-tag e br-datetime-picker continuam usando as constraints nativas e setCustomValidity() documentados em suas próprias seções. Eles não devem receber automaticamente o validator de texto: arquivos, intervalos e valores estruturados precisam de contratos específicos antes de uma nova API ser criada.

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