Input

Overview

Input é um <input> HTML nativo estilizado com tokens semânticos do KDS. Aceita qualquer type válido — text, email, password, number, search, tel, url, file — e adapta o teclado mobile quando aplicável (ex: email mostra @ no teclado iOS).

Estados visuais não são controlados por className: focus vem do browser (focus-visible), erro vem de aria-invalid (atributo ARIA), disabled do prop nativo. Esse desacoplamento permite que FormControl (@kalvner/kds/forms/form) ligue tudo automaticamente quando o input está dentro de um FormField.

Anatomy

<Input
  type="text"
  ├─ [data-slot="input"]
  └─ [aria-invalid] (set by FormControl quando há erro)
/>

Input é um único elemento — não é compound. Ícones laterais e botões de limpar são composições externas (wrapper relative + absolute), não props do próprio Input. Esse padrão simplifica a API e mantém o componente substituível.

Usage

import { Input } from "@kalvner/kds/forms/input";
import { Label } from "@kalvner/kds/forms/label";

export function EmailField() {
  return (
    <div className="grid gap-2">
      <Label htmlFor="email">Email</Label>
      <Input id="email" type="email" placeholder="voce@exemplo.com" />
    </div>
  );
}

Props

Variants

States

Composition

When to use

• Qualquer entrada de uma linha — nome, e-mail, busca, slug, número.
• Em formulários, em filtros, em campos de busca em headers.
• Quando o valor cabe naturalmente em uma linha. Para textos longos (mais de ~80 caracteres ou múltiplas frases), use Textarea.

When not to use

• Para textos multi-linha — Textarea.
• Para escolha entre opções — Select, RadioGroup, ou Combobox.
• Para alternar uma flag — Switch ou Checkbox.
• Para upload com preview e drag-and-drop, considere uma composição custom além do type="file" nativo.

Best practices

• Sempre pareie com Label. Mesmo quando o desenho usa placeholder como label flutuante, mantenha um <Label> visível. Placeholder some quando o usuário começa a digitar — sem Label, ele esquece o que estava preenchendo.
• Mensagem de erro abaixo do input, nunca dentro. Substituir o placeholder por mensagem de erro confunde — o usuário precisa do contexto do que digitou.
• Use inputMode quando o type não cobre o teclado ideal. Ex: <Input type="text" inputMode="numeric" pattern="[0-9]*" /> para CEP, código de verificação.
• Evite reservar layout só com altura. O Input já tem altura fixa (h-9), o que evita CLS. Mensagens de erro devem aparecer em slots reservados via grid gap-2 no FormItem — ver [[ui/layout/cumulative-layout-shift]].

Accessibility

Related

• Label — Label canônico, par obrigatório.
• Form — wrappers que ligam ARIA automaticamente.
• Textarea — entrada multi-linha.
• Select — quando a entrada é uma escolha de lista.