Input
Permite inserir ou editar um valor de texto breve em uma única linha.
- Capturar um dado breve de uma única linha: receber texto ou números que não precisam de mais de uma linha para serem exibidos. Ex.: "Nome do produto", "E-mail".
- Buscar dentro de uma listagem ou catálogo: filtrar resultados a partir de um termo digitado, com Input.Search. Ex.: "Buscar produtos", "Buscar pedidos".
- Inserir dados sensíveis: receber senhas ou outra informação que deve ficar oculta enquanto é digitada, com Input.Password. Ex.: "Senha de acesso".
- Mostrar o estado de validação de um valor: reforçar visualmente que um dado inserido está correto, tem um erro ou precisa de atenção, por meio de appearance.
- Inserir texto de várias linhas: descrever algo com mais de uma linha de extensão, como uma descrição ou um comentário. Nesse caso, usar Textarea.
- Escolher um valor de uma lista fechada de opções: selecionar entre alternativas predefinidas em vez de digitar livremente. Nesse caso, usar Select.
- Mostrar o campo com a etiqueta e a mensagem de ajuda integradas: o Input não inclui label nem helpText próprios. Nesse caso, usar Form Field, que compõe o Input junto com sua etiqueta e seu texto de ajuda ou erro.
Com ícone no início
Password
- Container: caixa do campo que reflete a aparência e o estado (fundo e borda).
- Field: área editável onde o valor é digitado ou editado.
- Placeholder: texto de exemplo que sugere o formato ou tipo de valor esperado, visível somente enquanto o campo está vazio; desaparece ao começar a digitar, por isso não deve ser a única orientação para preenchê-lo.
- Icon: ícone opcional, posicionado antes ou depois do campo por meio de append e appendPosition. No Input.Search já vem incorporado (uma lupa) e não é configurável.
- Toggle button (somente no Input.Password): alterna a visibilidade do valor inserido entre oculto e visível. Só aparece quando o campo tem conteúdo; com o campo vazio, não é renderizado.
Text: recebe texto ou números livres, com ou sem validação. É o uso geral do componente. Ex.: "Nome do produto", "CEP".
Search: campo de busca com um ícone de lupa incorporado; não precisa de um Label separado porque o ícone já comunica sua função. Ex.: "Buscar pedidos".
Password: oculta o valor enquanto é digitado e oferece um controle para alternar sua visibilidade. Ex.: "Senha de acesso".
Neutral: aparência padrão, sem validação em curso.
Success: confirma que o valor inserido é válido. Ex.: um código de verificação aceito.
Warning: alerta sobre um valor que vale revisar, sem bloquear o envio do formulário. Ex.: um tamanho de pacote fora do habitual.
Danger: indica um erro de validação. Ex.: um campo obrigatório que ficou vazio ao enviar o formulário.
AI generative: aplica a borda em degradê da Nimbus em campos usados em contextos de inteligência artificial (Lumi). Ex.: um campo de prompt para gerar conteúdo com IA.
aiGenerated: destaca que o valor atual do campo foi gerado por IA, com um anel de foco próprio. É independente de appearance e pode ser combinado com qualquer um de seus valores.
O Input aparece dentro de formulários, junto com seu Label e, quando necessário, um texto de ajuda ou de erro compostos por meio do Form Field. É comum encontrá-lo agrupado com outros campos relacionados, como os de um endereço de entrega.
Endereço
Número
Complemento
Preço de venda
Acompanhar o campo com um ícone no início quando ele reforça o tipo de dado esperado, como o símbolo de moeda em um preço.
Preço de venda
Evitar usar o ícone para repetir uma informação que já está no label ou no placeholder.
CEP
Bairro
Agrupar na mesma linha os campos que fazem parte de um mesmo dado, como os de um endereço.
CEP
Bairro
Evitar empilhar em linhas separadas campos que têm relação direta e poderiam ser agrupados.
CEP
Dimensionar o campo de acordo com o tamanho esperado do valor, como um mais estreito para um CEP.
CEP
Evitar campos desnecessariamente largos para valores de poucos caracteres.
- Navegação por teclado: ao renderizar um <input> nativo, recebe o foco com Tab e permite edição direta pelo teclado.
- Foco visível: a Nimbus aplica um anel de foco próprio ao focar o campo; não suprimir o outline ao personalizar estilos.
- Etiqueta associada: o Input não inclui label próprio; para que o campo seja acessível, associá-lo sempre a um Label ou compô-lo com Form Field, que já gerencia a associação entre etiqueta, campo e mensagem de ajuda.
- Estado desabilitado: usar a prop disabled, sem simulá-lo com cor ou opacidade; o <input disabled> comunica o estado inativo às tecnologias assistivas.
- Não depender da cor: o significado das aparências success, warning e danger deve ser reforçado com um texto de ajuda ou de erro, não apenas com a cor da borda, já que algumas pessoas usuárias podem ter dificuldade para distinguir cores.
- Senha visível sob controle da pessoa usuária: o botão para alternar a visibilidade do Input.Password permite confirmar o valor inserido antes de enviá-lo, sem obrigar a exibi-lo de forma permanente.
Placeholder: sentence case, sem ponto final; é adicionado somente quando traz um exemplo ou formato concreto que a label não consegue dar — usá-lo por padrão faz com que as pessoas usuárias aprendam a ignorá-lo.
Placeholder de acordo com o tipo de dado: se o campo tem um formato específico (data, código, SKU), sempre incluir um exemplo — "Ex.: DD/MM/AAAA". Se é texto livre sem estrutura definida, não inventar um exemplo.
Prefix / Suffix: unidade de medida, símbolo ou contexto curto que condiciona o dado, sem espaços extras nem pontuação — "$" · "kg" · "%" · "@dominio.com".
| Variante | Regra de conteúdo |
|---|---|
Text (padrão) | Campo de texto livre de uma linha, sempre acompanhado de Label. O placeholder é opcional: só quando adiciona um exemplo ou formato que a label não pode dar. |
Search | Não exige label — o ícone de lupa cumpre essa função. O placeholder é a orientação: descreve o que pode ser buscado. Fórmula: verbo "Buscar" + objeto, sem artigo — "Buscar produtos" · "Buscar clientes" · "Buscar por nome ou SKU". |
Password | O placeholder não agrega valor nesse campo — repetiria a label sem trazer um formato adicional, por isso normalmente é omitido. A label nomeia o dado, nunca o mecanismo — "Senha", não "Digite sua senha". O help text pode listar os requisitos antes de a pessoa criar a senha — "Mínimo 8 caracteres, uma letra maiúscula e um número." O erro não revela qual parte do formato falhou, por segurança — "A senha não atende aos requisitos.", não "Falta uma letra maiúscula." |
| Caso | O que fazer |
|---|---|
Input.Search sem placeholder | Incluir sempre um placeholder — sem ele, o campo não tem orientação sobre o que pode ser buscado. |
Input.Password com vários requisitos | O help text os lista antes de criar a senha. O erro não especifica qual requisito falhou, por segurança — "A senha não atende aos requisitos.", não "Falta uma letra maiúscula." |
Campo obrigatório | Nunca usar o placeholder para indicar isso (ex.: "Campo obrigatório"); resolver a obrigatoriedade com o asterisco ou a convenção do Form Field. |
Instalar o componente via terminal.
npm install @nimbus-ds/componentsimport React from "react";
import { Input } from "@nimbus-ds/components";
const Example: React.FC = () => <Input placeholder="Nombre del producto" />;
export default Example;Propriedades adicionais são repassadas ao elemento <input>. Consultar a documentação do elemento input para ver a lista de atributos aceitos.
- Form Field — Para compor o Input junto com sua etiqueta e sua mensagem de ajuda ou erro.
- Textarea — Para inserir texto com mais de uma linha.
- Select — Para escolher um valor entre opções predefinidas.
- Label — Para associar uma etiqueta acessível ao campo.
Input
| Name | Type | Default | Description |
|---|---|---|---|
appearance | 'ai-generative' | 'neutral' | Change the visual style of the input. |
aiGenerated | boolean | Highlights the field to indicate its value was generated by AI. Applies AI gradient border, white background and an AI focus ring. | |
disabled | boolean | Disables the input, disallowing user interaction. | |
appendPosition | 'end' | 'start' | Sent icon display position |
append | React.ReactNode | SVG icon to be displayed on input. | |
data-testid | string | This is an attribute used to identify a DOM node for testing purposes. |
Input.Password
| Name | Type | Default | Description |
|---|---|---|---|
appearance | 'ai-generative' | 'neutral' | Change the visual style of the input. |
disabled | boolean | Disables the input, disallowing user interaction. | |
aiGenerated | boolean | Highlights the field to indicate its value was generated by AI. Applies AI gradient border, white background and an AI focus ring. |
Input.Search
| Name | Type | Default | Description |
|---|---|---|---|
appearance | 'ai-generative' | 'neutral' | Change the visual style of the input. |
disabled | boolean | Disables the input, disallowing user interaction. | |
aiGenerated | boolean | Highlights the field to indicate its value was generated by AI. Applies AI gradient border, white background and an AI focus ring. |
Input.Skeleton
| Name | Type | Default | 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.