Textarea

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-textarea é o controle oficial do GovBR-DS para entrada de dados textuais em múltiplas linhas, projetado para capturar textos longos, justificativas, descrições ou observações em formulários.

Para que serve

• Entrada de texto extenso: Permite que a pessoa usuária digite parágrafos de texto livre com quebra de linha e rolagem vertical.
• Contador regressivo de caracteres: Exibe a quantidade de caracteres restantes em tempo real com base no limite máximo (maxlength), alertando visualmente quando o limite é atingido.
• Integração com formulários: É associado nativamente a formulários HTML (formAssociated), sincronizando valor, estado de validação e foco acessível.
• Redimensionamento controlado: Oferece opções de redimensionamento vertical, horizontal ou fixo.

Quando utilizar

• Utilize quando:
  • A entrada esperada tiver mais de uma frase ou exigir formatação multilinha (comentários, manifestações, relatórios, justificativas).
  • Houver restrição estrita de caracteres com necessidade de feedback quantitativo dinâmico.
• Evite e prefira outro componente quando:
  • O dado for curto e couber em uma única linha (como nomes, e-mails, títulos, documentos): prefira br-input.
  • For necessário um editor rico WYSIWYG com formatação em negrito, tabelas e links.

Estrutura e Slots

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

• default: Slot para instruções adicionais ou textos de ajuda.
• feedback: Slot para mensagens de validação contextual (como br-message).
• validation-loading: Slot para indicador de carregamento durante validações assíncronas.

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ãoDesabilitadoAltura automática

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

ariaLabel

Atributo	aria-label
Descrição	Texto alternativo para acessibilidade quando não há label visível. Fornece um rótulo para tecnologias assistivas sem exibir visualmente.
Tipo	string
Valor padrão	---

autoGrow

Atributo	auto-grow
Descrição	Ajusta automaticamente a altura ao conteúdo sem exibir rolagem vertical. Quando ativo, o componente controla a dimensão vertical; resize="vertical" e resize="both" passam a se comportar como none, enquanto resize="horizontal" continua disponível.
Tipo	boolean
Valor padrão	false

cols

Atributo	cols
Descrição	Número de colunas (caracteres) visíveis no textarea. Define a largura do componente em relação ao número de caracteres por linha. Deve ser um inteiro positivo; valores inválidos são ignorados.
Tipo	number
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()

density

Atributo	density
Descrição	Ajusta a densidade do componente, podendo ser 'small', 'medium' ou 'large'. Valores inválidos usam medium.
Tipo	"large" | "medium" | "small"
Valor padrão	'medium'

disabled

Atributo	disabled
Descrição	Indica se o textarea está desabilitado. Quando verdadeiro, o usuário não pode interagir com o campo.
Tipo	boolean
Valor padrão	false

feedbackState

Atributo	feedback-state
Descrição	Estado de feedback canônico. Quando informado, tem precedência sobre state; valores inválidos não aplicam estado.
Tipo	"danger" | "success" | "warning"
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	---

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

maxlength

Atributo	maxlength
Descrição	Número máximo de caracteres permitidos no textarea. Se definido como 0, não há limite. Deve ser um inteiro não negativo; valores inválidos usam 0.
Tipo	number
Valor padrão	0

minlength

Atributo	minlength
Descrição	Número mínimo de caracteres necessário para o valor ser válido. Deve ser um inteiro não negativo; valores inválidos usam 0.
Tipo	number
Valor padrão	0

name

Atributo	name
Descrição	Nome do campo para identificação no formulário. Necessário para participação correta no envio de formulários e integração com frameworks.
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	Impede edição sem remover o campo do envio do formulá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

resize

Atributo	resize
Descrição	Define os eixos que a pessoa usuária pode redimensionar manualmente. Quando omitida, preserva o comportamento nativo atual do navegador. Valores inválidos são ignorados.
Tipo	"both" | "horizontal" | "none" | "vertical"
Valor padrão	---

rows

Atributo	rows
Descrição	Número de linhas visíveis no textarea. Define a altura do componente em relação ao número de linhas de texto exibidas. Deve ser um inteiro positivo; valores inválidos são ignorados.
Tipo	number
Valor padrão	---

showCounter

Atributo	show-counter
Descrição	Mostra o contador com a quantidade máxima de caracteres.
Tipo	boolean
Valor padrão	false

state

Atributo	state
Descrição	Define o estado visual do componente, podendo ser 'danger', 'success' ou 'warning'. Valores inválidos não aplicam estado.
Tipo	"danger" | "success" | "warning"
Valor padrão	---

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

Atributo	validator
Descrição	Regra síncrona ou assíncrona executada no change ou por validate(). Pode consultar um serviço remoto; o componente controla apenas loading, validade e a precedência do resultado mais recente.
Exemplo de uso	const textarea = document.querySelector('br-textarea'); textarea.validator = (value) => value.trim().length >= 20 ? null : 'Informe pelo menos 20 caracteres';
Tipo	((value: string) => string | Promise<string>) | string
Valor padrão	---

value

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

wrap

Atributo	wrap
Descrição	Encaminha a política nativa de quebra de linha ao <textarea> interno. Quando omitida, o navegador usa o comportamento nativo soft. Valores inválidos são ignorados.
Tipo	"hard" | "soft"
Valor padrão	---

Slots

Nome	Descrição
"default"	Slot para texto adicional ou instruções a serem exibidos junto ao textarea.
"feedback"	Mensagem de validação, normalmente um br-message.
"validation-loading" Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Indicador exibido durante validação assíncrona.

Eventos

Evento	Descrição	Depreciação	Propagação
brTextareaValidationChange Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Informa o início e o resultado do validator; o detail contém validating, valid e message.	---	true
valueChange Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Valor atualizado do textarea	Use o evento nativo input e leia event.target.value.	true

Métodos

checkValidity

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

select

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

setCustomValidity

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

setRangeText

Descrição	Substitui um intervalo de texto usando a API nativa do textarea.
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:

setValue

Descrição	Define um novo valor para o textarea.
Assinatura	setValue(newValue: string) => Promise<void>
Parâmetros	newValue: - O novo valor a ser definido.

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

Descrição	Executa o validator customizado e retorna se o textarea está válido.
Assinatura	validate() => Promise<boolean>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"container"	Contêiner visual principal.
"counter-text"	Texto do contador.
"counter"	Contêiner do contador.
"feedback"	Contêiner da mensagem de validação.
"helper"	Contêiner do conteúdo auxiliar do slot default.
"label"	Rótulo do textarea.
"textarea"	Elemento textarea nativo.

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

br-textarea usa required, readonly, minlength e maxlength como constraints nativas. O valor é enviado por name e pode ser consultado com getValidationState().

Para regras de domínio, passe validator como propriedade JavaScript. Ele recebe o valor textual e pode retornar uma mensagem, null para sucesso ou uma Promise:

const textarea = document.querySelector('br-textarea');
textarea.validator = (value) => value.trim().length >= 10
  ? null
  : 'Informe pelo menos 10 caracteres.';

const valid = await textarea.validate();

Em React, Angular e Vue, use property binding (validator={fn}, [validator]="fn" ou :validator="fn"). Não use validator="..." para passar uma função nesses frameworks. A validação automática ocorre no change, nunca a cada tecla.

Durante uma validação assíncrona, o campo expõe aria-busy="true" e aceita o slot validation-loading. O resultado pode ser acompanhado por brTextareaValidationChange; mensagens podem ser fornecidas pelo slot feedback ou pelo br-message padrão.

Para uma regra adicional, chame setCustomValidity() com a mensagem em erro e uma string vazia ao corrigir. reportValidity() apresenta o erro sem emitir eventos de edição; reset e restauração retornam ao valor inicial silenciosamente.

Acessibilidade

Use um label visível e associe a mensagem de erro por aria-describedby ou aria-errormessage. O host mantém aria-invalid coerente com a validade mostrada e delega foco para o <textarea> interno.

O texto de ajuda deve explicar como corrigir o campo. Não dependa somente de cor ou placeholder para transmitir obrigatoriedade ou erro.

Eventos nativos

Elemento HTML de referência

br-textarea representa <textarea> e mantém esse elemento dentro do Shadow DOM.

Como ouvir os eventos

const textarea = document.querySelector('br-textarea');
textarea.addEventListener('input', () => console.log(textarea.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	Preservado pelo navegador.
change	no commit ou blur	Sim	Sim	Não	Sim	Uma ocorrência.
input	a cada edição	Sim	Sim	Não	Sim	Sintético após sincronizar value.
foco e focusin/focusout	mudança de foco	conforme o tipo	Sim	Não	Sim	Delegação usa os eventos com bubbling.

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 externa e reset são silenciosos.

Eventos customizados

valueChange é alias depreciado. Prefira input/change.

Valor, frameworks e acessibilidade

Leia event.target.value; validade e FormData pertencem ao host. HTML, React, Angular e Vue recebem os eventos padrão. O foco delegado e a edição multilinha preservam a semântica do <textarea>.

Evidência de teste

src/shared/contracts/platform-contract.e2e.tsx cobre interação real, ordem, flags, retargeting, caminho e delegação em Chromium headless.

Atributos nativos

O host FACE aceita name, form, required, disabled, readonly e autofocus. placeholder, minlength, maxlength, rows, cols e wrap são encaminhados ao <textarea> interno.

form e autofocus seguem o contrato nativo do host. Os métodos select(), setRangeText() e setSelectionRange() encaminham a seleção ao <textarea> interno. autoGrow ajusta a altura a partir do conteúdo renderizado e resize controla os eixos disponíveis para redimensionamento manual. Quando autoGrow está ativo, a dimensão vertical é controlada pelo componente. dirname não faz parte da API atual.

Documentações relacionadas

Consulte o guia geral de dados remotos para validar o conteúdo de forma assíncrona sem acoplar o componente ao transporte HTTP.

Também são relacionados:

• Input, que possui o mesmo contrato de validator para valores textuais;
• Select, para validação e busca remota de opções;
• Formulários, para integração com a Constraint Validation API.

Dependências

Depende de

• br-message
• br-loading

Gráfico