componentes / date-picker

DatePicker

Campo que abre um Calendar para escolher um dia.

Como usar

Um botão com cara de `Input` mostra o dia escolhido e abre um `Calendar`; escolher um dia fecha. A data não é digitada (para data digitada, use um `Input` com `mask="date"`). Com `name`, o formulário recebe `yyyy-mm-dd`. O foco entra no dia ao abrir e volta ao campo no `Esc`.

preview

Data de entrega

Aniversário

DatePicker.tsx

import { DatePicker } from "vaiperui";
 
const [date, setDate] = useState<Date>();
 
<DatePicker label="Data de entrega" value={date} onValueChange={setDate} />
<DatePicker
  label="Data de entrega"
  minDate={new Date()}
  weekStartsOn={1}
  locale="pt-BR"
/>

Tamanhos

preview

tamanhos.tsx

<DatePicker size="sm" />
<DatePicker size="md" />
<DatePicker size="lg" />

Estados

preview

ajudaDetalhe extra

ajuda

erroIsto é obrigatório

erro

desabilitado

somente leitura

estados.tsx

<DatePicker label="..." helperText="..." />
<DatePicker label="..." errorMessage="..." />
<DatePicker label="..." disabled />
<DatePicker label="..." readOnly />

Limites

preview

min / max

limites.tsx

<DatePicker label="..." minDate={new Date(2026, 9, 10)} maxDate={new Date(2026, 9, 25)} />

Cores

preview

success

customColor

cores.tsx

<DatePicker variantColor="success" />
<DatePicker customColor="#ff6600" />

Props

Prop	Valores	Padrão	Descrição
value / defaultValue	Date	nenhum	Dia escolhido, controlado ou inicial
onValueChange	(date: Date) => void	nenhum	Chamado quando um dia é escolhido
label / helperText	string	nenhum	Rótulo acima do campo e texto de ajuda abaixo
errorMessage	string	nenhum	Texto de erro; só a presença dele já força o estado de erro
placeholder	string	do idioma	Texto quando nada foi escolhido (ex.: dd/mm/aaaa)
name	string	nenhum	Nome do campo no formulário
disabled / readOnly	boolean	false	Não abre o painel; readOnly ainda mostra o valor
variant	ring \| outline	ring	Estilo de foco, igual ao Input
size / radius	sm \| md \| lg / none \| sm \| md \| lg \| full	md / md	Altura do campo e arredondamento dos cantos
aria-label	string	nenhum	Nome acessível quando não há rótulo
panelLabel	string	nenhum	Nome acessível do painel aberto
minDate / maxDate	Date	nenhum	Primeiro e último dia permitidos; o resto e as setas de mês que levam para fora ficam desabilitados
locale	string	"en-US"	Idioma dos nomes de mês/dia e formato da data (BCP 47)
weekStartsOn	0 – 6	0	Primeiro dia da semana (0 = domingo)
previousMonthLabel / nextMonthLabel	string	"Previous month" / "Next month"	Nomes acessíveis dos botões de mês
variantColor / customColor / animation	primary \| success \| warning \| danger / CSS color / none \| smooth \| fast \| bounce	primary / smooth	Cor da seleção e do foco, e velocidade da transição

Acessibilidade

O gatilho é um `<button>` com `aria-haspopup="dialog"` e `aria-expanded` refletindo o estado do painel.
O `label` é ligado por `htmlFor`; sem `label`, o gatilho usa `aria-label`.
`errorMessage` define `aria-invalid` e `aria-describedby` apontando para a mensagem; sem erro, o `helperText` é ligado por `aria-describedby`.
O painel é um `role="dialog"` nomeado por `panelLabel`, renderizado em um portal no `document.body`.
`disabled` desabilita o botão; `readOnly` mantém o foco possível, mas o painel nunca abre.
Ao abrir, o foco vai para o dia selecionado (ou hoje) no `Calendar`, que segue o padrão de grade.

Teclado

Tecla	Ação
Enter / Space	Abre ou fecha o painel a partir do gatilho.
Arrow keys, Home, End, Page Up/Down	Navegam pelos dias dentro do painel aberto (veja Calendar); Enter ou Espaço em um dia o escolhe e fecha o painel.
Esc	Fecha o painel e devolve o foco ao gatilho.

Tenha em mente

O painel não prende o foco: o Tab sai dele e, como ele é renderizado no fim do `<body>`, o Tab a partir do gatilho não entra nele sozinho.
Clicar fora fecha o painel sem devolver o foco; só o Esc restaura o foco no gatilho.
A data não pode ser digitada: a única forma de definir é o calendário. Use `Input` com `mask="date"` para datas digitadas.