Tema
BaseField e BaseInput
BaseField dá rótulo, ajuda e erro a um campo. BaseInput é o campo de texto. Dentro de um BaseField, o campo se liga sozinho ao rótulo e às mensagens.
Formato 000/2026
Uso
- Todo campo tem rótulo visível.
hide-labelsó para filtros compactos, quando o contexto já diz o que é. - A ajuda explica o formato antes do erro acontecer.
- O erro diz o que está errado e como corrigir: "Informe o número no formato 000/2026", não "Campo inválido".
- Marque os obrigatórios com
required. Em formulários onde quase tudo é obrigatório, marque os outros comoptional. - Use
warnpara um valor aceito, mas que merece atenção.
Anatomia
- Rótulo: o texto acima do campo, vindo de
label. Leva o asterisco comrequiredou "(opcional)" comoptional. - Campo: o
BaseInput, onde a pessoa digita. - Ícone, prefixo ou sufixo: dentro do campo, vindos de
icon-start,prefixesuffix. - Mensagem: abaixo do campo. Mostra a ajuda (
helper-text), o erro (invalid-text) ou o aviso (warn-text), um de cada vez.
Estados
Informe o número no formato 000/2026
Valor 40% acima da média das obras
Tipos
Pedida para assinar o termo de recebimento.
O type diz ao navegador o que o campo guarda: ele confere o formato do e-mail e do link no envio, abre o teclado certo no celular e esconde a senha. Para um texto qualquer, deixe o padrão, text; para busca, prefira o BaseSearch.
Teclado do celular
Só números.
O inputmode troca só o teclado do celular, sem conferir o formato. Use quando o type não serve porque o campo aceita mais de um formato, como e-mail ou login de rede. Para valores em reais e medidas, use decimal, como no valor global acima.
Tamanhos
Use sm em filtros e tabelas densas e lg em telas com um só campo em destaque, como a busca da página inicial.
Erro e obrigatório no BaseInput
Todos os campos são obrigatórios.
A quantidade medida do item 4.2 passa do saldo. Informe até 892,20 m².
Saldo do item: 892,20 m².
invalid e required também valem direto no BaseInput: ele ganha a borda de erro, aria-invalid e o required nativo. Dentro de um BaseField, prefira marcar no BaseField, porque só ele mostra o asterisco e a mensagem junto do campo. Marque só no BaseInput quando outra parte da tela já diz o que falta, como no formulário em que tudo é obrigatório e os erros aparecem num resumo no alto.
Faça e não faça
| Faça | Não faça |
|---|---|
| Escreva o rótulo "Número do contrato" e mostre o formato na ajuda | Deixar só o placeholder "000/2026" no lugar do rótulo |
| Diga no erro como corrigir: "Informe o número no formato 000/2026" | Escrever "Campo inválido" |
Use type="email" no e-mail do fiscal | Usar text e conferir o formato à mão |
Estilo
| Propriedade | Token |
|---|---|
| Fundo | --tj-field-01; desabilitado e somente leitura --tj-field-disabled |
| Borda | --tj-border-strong-01, hover --tj-border-strong-02, foco --tj-border-interactive |
| Erro | --tj-support-error-text |
| Aviso | --tj-support-warning-text (borda e texto); no foco, contorno sólido de 2 px na mesma cor |
| Rótulo | --tj-text-secondary, 13 px, semibold |
| Altura | --tj-control-sm/md/lg |
Código
vue
<BaseField label="Número do contrato" helper-text="Formato 000/2026" :invalid="showError" invalid-text="Informe o número no formato 000/2026" required>
<BaseInput v-model="contractNumber" />
</BaseField>Propriedades
BaseField
| Propriedade | Tipo | Padrão | Descrição |
|---|---|---|---|
label | string | obrigatória | Rótulo |
helperText | string | — | Ajuda abaixo do campo |
invalid | boolean | false | Mostra o erro no lugar da ajuda |
invalidText | string | — | Mensagem de erro enquanto invalid: o que está errado e como corrigir |
warn | boolean | false | Mostra o aviso no lugar da ajuda |
warnText | string | — | Mensagem de aviso enquanto warn |
required | boolean | false | Marca o campo como obrigatório no rótulo |
optional | boolean | false | Marca o campo como opcional no rótulo, para formulários em que quase tudo é obrigatório |
hideLabel | boolean | false | Rótulo só para leitor de tela |
BaseInput
| Propriedade | Tipo | Padrão | Descrição |
|---|---|---|---|
type | 'search' | 'text' | 'email' | 'tel' | 'url' | 'password' | 'text' | Tipo do campo |
size | 'sm' | 'md' | 'lg' | 'md' | Altura |
placeholder | string | — | Exemplo do formato dentro do campo vazio; nunca substitui o rótulo |
disabled | boolean | false | Desabilita o campo |
readonly | boolean | false | Mostra o valor sem permitir mudança |
invalid | boolean | false | Marca o erro; dentro de um BaseField, vale também o do campo |
required | boolean | false | Obrigatório no formulário; dentro de um BaseField, vale também o do campo |
autocomplete | string | — | Ajuda o navegador a preencher o campo, como email ou off |
inputmode | 'search' | 'text' | 'email' | 'tel' | 'url' | 'numeric' | 'decimal' | — | Teclado do celular, como numeric ou decimal |
iconStart | string | — | Ícone do Bootstrap Icons dentro do campo, antes do texto |
prefix | string | — | Texto fixo antes do valor, como "R$" |
suffix | string | — | Texto fixo depois do valor, como "m²" |
v-model | string | '' | Valor |
Acessibilidade
- Não há padrão do WAI-ARIA APG para campo de texto: o
BaseInputé um<input>nativo do HTML, e o teclado é o do navegador. - O rótulo é um
<label for>ligado ao campo; clicar no rótulo foca o campo. - Ajuda, erro e aviso ficam em
aria-describedby; o leitor de tela lê a mensagem junto com o campo. - Com erro, o campo recebe
aria-invalid="true". A cor nunca é o único sinal: há ícone e texto. - O asterisco de obrigatório fica escondido do leitor de tela, que já anuncia o
required. - Prefixo e sufixo são decorativos (
aria-hidden). Coloque a unidade também no rótulo quando ela importa, por exemplo "Valor global (R$)". - Teclado:
| Tecla | O que faz |
|---|---|
| Tab / Shift + Tab | Entra no campo e sai dele. Um campo desabilitado fica fora da ordem; um somente leitura recebe foco, mas não aceita texto |
| Letras e números | Escrevem no campo |
| Enter | Envia o formulário em volta, como em qualquer campo nativo |
- Testado com axe em todos os estados.