Textarea

2.7.0

Permite inserir e editar texto ou conteúdo extenso em um campo de múltiplas linhas.

Ver no Figma

Quando usar

Inserir descrições ou notas: conteúdo estendido que abrange várias linhas, como a descrição de um produto, nota de envio ou comentário de pedido. Ex.: "Adicionar descrição do produto", "Deixar instruções especiais de entrega".
Coletar feedback ou comentários: campos que esperam respostas mais desenvolvidas do comerciante, não rótulos simples.
Editar textos mais extensos: quando o conteúdo pode ocupar múltiplas linhas e requer espaço suficiente para visualizar o escrito enquanto se edita.

Quando não usar

Texto que cabe em uma única linha: para nomes, títulos curtos ou valores simples, usar Input. O Textarea ocupa mais espaço e é desnecessário se o conteúdo é breve.
Exibir o campo com sua etiqueta e mensagem de ajuda integradas: o Textarea não inclui label nem helpText próprios. Em vez disso, usar Form Field, que compõe o Textarea junto com sua etiqueta e seu texto de ajuda ou erro.

Anatomia

Container: caixa de entrada que contém o texto, com borda e fundo, que reflete o estado de validação do campo por meio de mudanças de cor.
Field: área editável onde o valor é digitado ou editado.
Placeholder: texto de referência exibido quando o campo está vazio; desaparece quando o usuário começa a digitar.
Resize Handle: pequeno ícone ou alvo no canto que permite aos usuários alterar a altura ou largura da caixa.
Scrollbar: aparece automaticamente na borda quando o texto inserido excede a altura visível do contêiner.

Variantes

Aparência

Neutral: estado padrão do campo; usar quando não há validação ativa.

Success: indica que o conteúdo inserido é válido.

Warning: avisa sobre conteúdo que requer revisão ou ação, sem bloquear a entrada.

Danger: indica um erro de validação; impede continuar até que o conteúdo seja corrigido.

Transparent: estilo sem borda visível, útil em contextos de conteúdo editável integrado dentro de cartões ou áreas de leitura.

AI generative: aplica a borda degradada da Nimbus para campos usados em contextos de IA (Lumi).

AI generated: indica que o valor atual do campo foi gerado por IA, com seu próprio anel de foco. É independente de appearance e pode ser combinado com qualquer um de seus valores.

Linhas e crescimento

2 linhas: altura padrão; equilíbrio entre visibilidade e compacidade em formulários.

4 linhas: maior espaço para conteúdo extenso; usar quando se espera descrição mais desenvolvida.

Autogrow: o campo cresce automaticamente conforme se adiciona conteúdo, até um máximo definido; proporciona uma experiência de escrita fluida sem scroll interno.

Redimensionamento

Resize habilitado: o usuário pode ajustar o tamanho do campo arrastando o canto inferior direito; útil quando o conteúdo é imprevisível.

Resize desabilitado: tamanho fixo; mantém a coerência do layout quando múltiplos campos compartilham o mesmo espaço.

Estados

Aplicação

O Textarea é utilizado em formulários para coletar conteúdo extenso, como descrições de produtos, instruções especiais de envio ou respostas a pesquisas. Funciona de forma similar em desktop e mobile, mantendo sua capacidade de adaptar-se ao conteúdo ou ao espaço disponível. Quando o campo precisa de etiqueta e mensagem de ajuda ou erro compostas junto ao controle, ele é utilizado por meio de Form Field.

Descrição do produto

Do and Don'ts

Instruções especiais

Acompanhar o Textarea com um label claro que descreva o conteúdo esperado.

Utilizar o Textarea sem contexto de label ou sem explicação clara do tipo de conteúdo requerido.

Descrição

Complete este campo

Validar o conteúdo e comunicar o resultado com a aparência correta (success, warning, danger) acompanhada de uma mensagem de texto.

Descrição

Depender apenas da cor para comunicar erros; sempre acompanhar com uma mensagem de texto.

Notas internas

Fornecer um placeholder descritivo que guie sobre o formato ou extensão esperada do conteúdo.

Notas internas

Deixar o placeholder vazio ou genérico; o usuário pode perder contexto do tipo de informação solicitada.

Acessibilidade

Associar label ao campo: vincular sempre o label ao Textarea por meio do atributo htmlFor do label e do id do campo, ou compô-lo com Form Field, que já gerencia a associação entre etiqueta, campo e mensagem de ajuda. Os usuários de leitores de tela entendem qual dado é solicitado.
Validação acessível: quando há erro, comunicar a mensagem não apenas com cor, mas também com texto; os usuários com dificuldade na percepção da cor recebem a informação igualmente.
Placeholder como ajuda, não como label: o placeholder desaparece ao escrever e não substitui o label; usar apenas como dica adicional sobre o formato esperado.
Indicar limites de caracteres: se o campo tem restrição, mostrar um contador ou aviso acessível (ex.: "0 de 300 caracteres") para que o usuário saiba quando se aproxima do limite.

Implementação

Instale o componente via terminal.

npm install @nimbus-ds/components

import React from "react";
import { Textarea } from "@nimbus-ds/components";

const Example: React.FC = () => (
  <Textarea
    appearance="neutral"
    id="id"
    lines={2}
    placeholder="Placeholder text"
  />
);

export default Example;

Props

As propriedades adicionais são passadas ao elemento <textarea>. Consulte a documentação do elemento textarea para ver a lista de atributos aceitos.

Componentes relacionados

Input — Para inserir texto que cabe em uma única linha.
Form Field — Para compor o Textarea junto com sua etiqueta e sua mensagem de ajuda ou erro.

Textarea

Name	Type	Default	Description
appearance	'ai-generative' 'danger' 'neutral' 'success' 'transparent' 'warning'	'neutral'	Change the visual style of the textarea.
aiGenerated	boolean		Highlights the field to indicate its value was generated by AI. Applies AI gradient border, white background and an AI focus ring.
lines	number	'2'	Number of lines to be rendered for the user to input text
autoGrow	boolean	'false'	Controls intrinsic sizing behavior of the field. When true, the textarea will grow with content up to the maxLines limit (if provided) and then scroll.
maxLines	number		Caps the textarea visual height to the given number of lines. When used together with autoGrow=true, the textarea will grow with content up to this limit and then scroll.
minLines	number		Sets the minimum height of the textarea to the given number of lines. The textarea will never shrink below this height, even when empty.
id*	string		ID of the textarea
resize	boolean	'true'	Enable/disable textarea resize functionality

Textarea.Skeleton

Name	Type	Description
width	string	Width of the skeleton. Useful when the skeleton is inside an inline element with no width of its own.
className	string
data-testid	string	This is an attribute used to identify a DOM node for testing purposes.

Ajude-nos a melhorar a documentação

Encontrou um problema ou tem uma sugestão? Conte para a gente.

Compartilhe seu feedback