Input

O componente Input é um campo de entrada fundamental que permite aos usuários inserir dados textuais em formulários. Suporta diversos tipos de entrada, validação, estados visuais e elementos decorativos como ícones e símbolos de moeda.

Importação

import { Input } from '@useblu/ocean-react';

Importação específica (recomendado para tree-shaking)

import { Input } from '@useblu/ocean-react/Input';

Importação de tipos TypeScript

import type { InputProps } from '@useblu/ocean-react';

// Uso em componente customizado
const MyComponent: React.FC<InputProps> = (props) => {
  return <Input {...props} />;
};

Playground Interativo

Explore o componente Input no playground interativo do Storybook:

🚀 Abrir no Storybook

Documentação Completa

Para documentação técnica detalhada, exemplos de uso e API completa, consulte o Storybook do Input.

No Storybook você encontrará:

• ✅ Controles interativos para testar todas as props
• ✅ API gerada automaticamente com tipagem completa
• ✅ Exemplos visuais de todas as variantes e estados
• ✅ Playground para experimentação rápida

Uso básico

<Input
  label="Nome Completo"
  placeholder="João Silva"
  helperText="Primeiro e último nome"
/>

Estados

O Input possui diferentes estados visuais para comunicar status e interações:

Estados básicos

🚀 Abrir no Storybook

• Normal: Estado padrão do input
• Error: Indica validação com falha ou entrada inválida
• Disabled: Campo desabilitado para interação

Tipos de Input

O Input suporta diferentes tipos de entrada para otimizar a experiência do usuário:

🚀 Abrir no Storybook

Guia de uso dos tipos

• text: Para textos gerais (nome, título, etc.)
• email: Para endereços de email com validação nativa
• password: Para senhas com caracteres ocultos
• number: Para valores numéricos

Input com Ícones

Adicione ícones para melhor identificação visual e orientação do usuário:

🚀 Abrir no Storybook

Posicionamento de ícones

• left: Ícone à esquerda (mais comum)
• right: Ícone à direita (menos comum)

Input de Moeda

Para valores monetários, use adornos com símbolos ou códigos de moeda:

🚀 Abrir no Storybook

Convenções de moeda

• Símbolos à esquerda: R$, $, € (mais intuitivo)
• Códigos à direita: BRL, USD, EUR (contexto internacional)
• Ícones: Para representações visuais genéricas

Input com Tooltip

Use tooltips para fornecer informações contextuais complementares:

🚀 Abrir no Storybook

Exemplo de Formulário

Veja como combinar inputs em um formulário completo:

🚀 Abrir no Storybook

API

Props

Prop	Tipo	Padrão	Descrição
type	'text' | 'email' | 'number' | 'password' | 'search' | 'tel' | 'url'	'text'	Tipo do input que define comportamento
label	string	-	Rótulo do campo
placeholder	string	-	Texto de exemplo quando vazio
helperText	string	-	Texto de ajuda abaixo do campo
error	boolean	false	Define estado de erro
disabled	boolean	false	Desabilita o campo
required	boolean	false	Marca como obrigatório
defaultValue	string	-	Valor inicial do campo
value	string	-	Valor controlado
tooltipMessage	string	-	Mensagem do tooltip
adornment	React.ReactElement	-	Ícone ou texto decorativo
position	'left' | 'right'	'left'	Posição do adornment
name	string	-	Nome do campo no formulário
id	string	-	ID único do elemento
className	string	-	Classes CSS adicionais
onChange	(event: ChangeEvent<HTMLInputElement>) => void	-	Callback de mudança de valor

Eventos

• onChange: Disparado quando o valor do input é alterado
• onFocus: Disparado quando o input recebe foco
• onBlur: Disparado quando o input perde foco
• onKeyDown: Disparado ao pressionar uma tecla

Acessibilidade

• ✅ Navegação por teclado: Suporte completo com Tab e teclas de navegação
• ✅ Labels apropriados: Associação correta entre label e input
• ✅ Estados de foco: Indicação visual clara do foco
• ✅ Textos de ajuda: Associados corretamente com aria-describedby
• ✅ Mensagens de erro: Comunicadas via screen readers
• ✅ Validação nativa: Aproveita validação HTML5 quando apropriado

Navegação por teclado

Tecla	Função
Tab	Move foco para/do input
Shift + Tab	Move foco para elemento anterior
Teclas de texto	Inserem caracteres no campo
Backspace	Remove caractere anterior
Delete	Remove caractere seguinte

Melhores práticas

✅ Faça

• Use labels descritivos que indiquem claramente o conteúdo esperado
• Forneça placeholders informativos que demonstrem o formato esperado
• Implemente validação clara com mensagens de erro úteis
• Use o tipo correto para cada contexto (email, tel, password, etc.)
• Agrupe campos relacionados logicamente em formulários
• Use helperText para orientações importantes
• Implemente estados de loading para operações assíncronas

❌ Não faça

• Não use placeholder como label - sempre forneça um label real
• Não omita validação em campos obrigatórios
• Não use tipos incorretos (ex: text para email)
• Não ignore estados de erro - sempre forneça feedback claro
• Não sobrecarregue tooltips com informações essenciais
• Não desabilite campos sem explicar o motivo
• Não implemente validação confusa ou contraditória

Casos especiais

🚀 Abrir no Storybook

Tratamento de casos específicos

• Campos preenchidos: Mantenha estado visual adequado
• Validação em tempo real: Use debouncing para melhor performance
• Campos longos: Considere responsividade e quebra de linha
• Campos obrigatórios com erro: Combine required + error para feedback claro

CSS Classes

O componente gera as seguintes classes CSS:

Classe	Descrição
.ods-input	Classe base aplicada ao elemento input
.ods-input--filled	Aplicado quando o input tem valor
.ods-input--disabled	Aplicado quando o input está desabilitado
.ods-input--error	Aplicado quando o input está em estado de erro
.ods-input--left	Aplicado quando position é 'left'
.ods-input--disabled--text	Aplicado quando desabilitado com texto
.ods-input--adornment	Aplicado quando há adornment
.ods-input__adornment	Container do elemento adornment
.ods-input__adornment--placeholder	Aplicado ao adornment quando input vazio

Links relacionados

• TextArea - Para textos multilinha
• Select - Para seleção de opções
• Checkbox - Para seleções múltiplas
• Radio - Para seleção única
• Storybook - Input - Documentação técnica completa