DateRangePicker
Período
Vazio
Em Date
Com atalhos de período
import { DateRangePicker } from '@rivocode/ui'Quando usar
Período, para filtro de relatório e de listagem.
Aqui não há digitação, e essa é a diferença de propósito para o DatePicker:
máscara de intervalo pede duas datas num campo só, e o custo de acertar teclado,
colagem e ordem invertida não se paga.
O rodapé com Aplicar vem ligado por padrão, ao contrário do DatePicker, e a
diferença é de propósito: período pede dois cliques. O primeiro já fecha um
período de um dia e o segundo estica até o fim, então sem confirm o
onValueChange sairia duas vezes, e um filtro de listagem recarregaria duas
vezes.
Valor
value e defaultValue aceitam pontas em Date ou em texto aaaa-mm-dd, e o
onValueChange responde no formato que recebeu. O contrato é um só nos dois
formatos, e é o do @rivocode/ui-native: só sai intervalo fechado, com
from e to obrigatórios (DateRange em Date, IsoDateRange em texto), e
null quando a escolha esvazia. O período pela metade fica no rascunho do
calendário até ganhar a segunda ponta, e nunca chega a quem chama.
const [periodo, setPeriodo] = useState<IsoDateRange | null>(null)
<DateRangePicker
value={periodo}
onValueChange={setPeriodo}
min="2026-01-01"
max="2026-12-31"
/>
Com Date, o vazio que entra é undefined, porque null no value é o que
escolhe o formato em texto. Guarde DateRange | null e passe o vazio adiante
como undefined:
const [periodo, setPeriodo] = useState<DateRange | null>(null)
<DateRangePicker value={periodo ?? undefined} onValueChange={setPeriodo} />
min e max são inclusivos: desabilitam os dias de fora e param a navegação no
mês de cada ponta, que é o que um filtro de período precisa para ficar dentro
dos exercícios abertos. showOutsideDays e locale atravessam para o
calendário, como no DatePicker.
O segundo período estende, e não recomeça
Com um intervalo inteiro na tela, o próximo dia clicado mexe numa das pontas do que já existe, em vez de começar de novo. A regra é de posição, e não de ordem: dia antes do começo puxa o começo para trás, e qualquer dia depois dele vira o novo fim — inclusive um dia que está no meio da faixa, que assim encurta o período em vez de abrir um período novo a partir dali. É a única regra que não joga trabalho fora: o calendário não tem como saber qual das duas pontas a pessoa quis mexer, e adivinhar errado apagaria uma data que ela acabou de escolher.
Para trocar de período em vez de esticar o atual há duas portas, e é bom saber
das duas antes de precisar. Limpar zera a escolha e fecha o painel — e
ele não limpa só o rascunho: confirma o vazio, chamando onValueChange com
null sem esperar pelo Aplicar, nos dois formatos, então um filtro ligado nele
recarrega vazio e reabrir o painel é um clique a mais. A outra porta não fecha nada:
clicar exatamente sobre uma das duas pontas transforma o intervalo num período
de um dia só ali, e o clique seguinte já estende a partir desse dia.
Com confirm={false} não há rodapé, e portanto não há Limpar: aí a ponta é o
único caminho, e clicar de novo no período de um dia só é o que esvazia, com o
mesmo null.
Atalhos de período
Filtro de listagem quase sempre começa por "Últimos 30 dias" ou "Este mês", e
clicar trinta dias no calendário para chegar lá é trabalho de máquina. Com
presets, os atalhos prontos em pt-BR aparecem numa coluna à esquerda do
calendário na mesa, e em fichas acima do mês no celular: hoje, ontem, últimos
7 e 30 dias, este mês (do dia 1 até hoje) e mês passado (do primeiro ao
último dia).
<DateRangePicker presets value={periodo} onValueChange={setPeriodo} />
Um clique no atalho fecha o período e responde uma vez só, sem esperar o
Aplicar, e o painel fecha. O atalho que casa com o período escolhido fica
marcado (aria-pressed), e o que sai de min ou max fica desligado. Os
prontos são RANGE_PRESETS, e uma lista própria troca por outros: cada
atalho tem label e range, que recebe o dia de hoje e devolve as duas
pontas em aaaa-mm-dd.
const ATALHOS: DateRangePreset[] = [
...RANGE_PRESETS.slice(0, 4),
{ label: "Trimestre", range: () => ({ from: "2026-07-01", to: "2026-09-30" }) },
]
<DateRangePicker presets={ATALHOS} value={periodo} onValueChange={setPeriodo} />
Travado
Dentro de <Field invalid>, o gatilho ganha a borda de perigo e o
aria-invalid, como os outros campos de data; dentro de <Field disabled>,
fica desligado. Com readOnly, o gatilho mostra o período com a borda
tracejada da casa, continua alcançável pelo Tab para ser lido, e não abre o
calendário.
Quando não usar
Para uma data só (vencimento, nascimento, agendamento), use DatePicker: ele
aceita digitação e não pede o segundo clique nem o Aplicar que o período exige.
Hora do dia é TimeField, e a agenda com eventos e choque de horário é
EventCalendar.
No React Native
Traduz, com um desenho só: um mês, numa folha de baixo, com a faixa pintada na própria grade. Os dois meses lado a lado do web não cabem (390px partidos ao meio dão 27px de célula, e o alvo de toque mínimo é 44), e dois DatePicker em sequência, que era o que esta tabela mandava fazer até agora, perdem justamente o que faz a peça existir: as duas pontas na mesma grade, com os dias do meio pintados. A validação de fim-antes-do-começo deixou de ser sua: tocar 20 e depois 5 devolve 5 a 20, porque a peça ordena as duas pontas em vez de descartar o primeiro toque, e o Aplicar fica desligado enquanto falta a segunda. Por isso o tipo mudou: o DateRange daqui tem from e to obrigatórios, os dois como ISO aaaa-mm-dd, e o vazio é null - o mesmo IsoDateRange que o web aceita e devolve quando recebe o valor em texto, e o mesmo contrato do web nos dois formatos: o onValueChange só recebe intervalo fechado, e null no Limpar. O intervalo pela metade não sai de nenhum dos dois pacotes: quem quiser acompanhar lê o resumo que a própria folha escreve acima do mês. Sem confirm: a folha sempre confirma, porque o toque fora dela é o gesto de desistir e não pode valer como aplicar.
presets vem com o nome e os atalhos do web (RANGE_PRESETS, o mesmo código nos dois pacotes), em fichas acima do mês: um toque aplica e fecha a folha.
API
| Prop | Tipo |
|---|---|
confirm0.5.0Rodape com Limpar e Aplicar. | boolean |
defaultValue0.4.0O intervalo inicial, quando o componente controla o proprio estado. | DateRangeIsoDateRangenull |
disabledDays0.4.0Dias que nao podem ser escolhidos. | Matcher[] | Matcher |
labelsOs textos da peca, para trocar o idioma: `title` e o titulo do painel, `clear` e `apply` os dois botoes do rodape do `confirm`, e `presets` o nome do grupo de atalhos. | Partial<DateRangePickerLabels> |
locale0.4.0O objeto de idioma usado para as datas. | Partial<DayPickerLocale> |
maxO ultimo dia aceito, inclusive, em `Date` ou `aaaa-mm-dd`. | string | Date |
minO primeiro dia aceito, inclusive, em `Date` ou `aaaa-mm-dd`. | string | Date |
numberOfMonths0.4.0Quantos meses o calendario mostra lado a lado. | number |
onValueChange0.4.0Chamado com o intervalo fechado nas duas pontas, ou com `null` quando a escolha esvazia. | ((range: DateRange | null) => void) | ((range: IsoDateRange | null) => void) |
placeholder0.4.0Texto do gatilho quando nao ha intervalo. | string |
presetsAtalhos de periodo ao lado do calendario, numa coluna na mesa e em fichas acima do mes no celular. | boolean | DateRangePreset[] |
readOnlyMostra o periodo sem deixar mudar: o gatilho fica com a borda tracejada, continua focavel e nao abre o calendario. | boolean |
showOutsideDaysMostra os dias de fora (os que caem no mês anterior ou no seguinte). | boolean |
size0.4.0Tamanho do gatilho, o mesmo vocabulario do Input. | "lg""md""sm" |
value0.4.0O intervalo escolhido, quando quem usa controla o estado. | DateRangeIsoDateRangenull |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.