componentes / date-range-picker

DateRangePicker

Campo que abre um Calendar para escolher início e fim, com atalhos prontos.

Como usar

Mostra `início – fim` e abre um `Calendar` em modo intervalo; o painel fecha após o segundo clique. `onValueChange` roda duas vezes por intervalo: primeiro só com `from`, depois com `from` e `to`. `presets` adiciona uma coluna de atalhos (Hoje, Últimos 7 dias...) que define o intervalo todo; passe `true` para os padrões ou sua própria lista, a partir de `getDatePresets()`.

preview

Hospedagem

DateRangePicker.tsx

import { DateRangePicker, getDatePresets } from "vaiperui";
 
const [period, setPeriod] = useState<DateRange>({});
 
<DateRangePicker label="Hospedagem" presets value={period} onValueChange={setPeriod} />
 
// Custom list, translated labels
<DateRangePicker presets={[
  ...getDatePresets({ today: "Hoje" }).slice(0, 3),
  { label: "Q4", range: { from: new Date(2026, 9, 1), to: new Date(2026, 11, 31) } },
]} />

Atalhos

`presets` adiciona uma coluna de atalhos. `true` usa os padrões; passe uma lista para os seus.

preview

presets

sem atalhos

no presets

atalhos.tsx

<DateRangePicker presets />
<DateRangePicker presets={[{ label: "Q4", range: { from, to } }]} />

Tamanhos

preview

tamanhos.tsx

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

Estados

preview

ajudaDetalhe extra

ajuda

erroIsto é obrigatório

erro

desabilitado

somente leitura

estados.tsx

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

Props

Prop	Valores	Padrão	Descrição
value / defaultValue	{ from?: Date; to?: Date }	nenhum	Intervalo, controlado ou inicial. Sem `to`, só o início foi escolhido
onValueChange	(range: DateRange) => void	nenhum	Chamado a cada clique
presets	boolean \| { label: string; range: { from: Date; to: Date } }[]	nenhum	Coluna de atalhos; true usa getDatePresets(). Atalhos fora de minDate/maxDate ficam desabilitados
presetLabels	{ today, last7Days, last30Days, thisMonth, lastMonth }	nenhum	Traduz os atalhos padrão (presets={true})
fromName / toName	string	nenhum	Nomes dos campos de início e fim; cada um envia yyyy-mm-dd
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)
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.
O texto do gatilho aparece como `início – fim`; enquanto só o início foi escolhido, mostra `início – …`.
Os presets são `<button>`s com `aria-pressed` quando coincidem com o intervalo atual e `disabled` quando ficam fora de `minDate`/`maxDate`.
Ao abrir, o foco vai para um dia no `Calendar` de intervalo, 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 escolhe o início e depois o fim, que 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.
Passe `presetLabels` (ou seus próprios `presets`) traduzidos ao usar presets; os padrões estão em inglês. As datas não podem ser digitadas.