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

Design System

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

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

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

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

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.
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'.
Tipo	"danger" | "success" | "warning"
Valor padrão	---

validator

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

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"	Indicador exibido durante validação assíncrona.

Eventos

Evento	Descrição	Depreciação	Propagação
brTextareaValidationChange	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

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

Dependências

Depende de

• br-message
• br-loading

Gráfico

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/platform-contract.e2e.tsx cobre interação real, ordem, flags, retargeting, caminho e delegação em Chromium headless.

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.