Pular para o conteúdo
Formulário

DateRangePicker

/componentes/date-range-picker.mdmarkdown cru, para quem lê com agent em vez de olho

Período

Vazio

Em Date

Com atalhos de período

Importar
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

PropTipo
confirm0.5.0

Rodape com Limpar e Aplicar.

boolean
defaultValue0.4.0

O intervalo inicial, quando o componente controla o proprio estado.

DateRangeIsoDateRangenull
disabledDays0.4.0

Dias que nao podem ser escolhidos.

Matcher[] | Matcher
labels

Os 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.0

O objeto de idioma usado para as datas.

Partial<DayPickerLocale>
max

O ultimo dia aceito, inclusive, em `Date` ou `aaaa-mm-dd`.

string | Date
min

O primeiro dia aceito, inclusive, em `Date` ou `aaaa-mm-dd`.

string | Date
numberOfMonths0.4.0

Quantos meses o calendario mostra lado a lado.

number
onValueChange0.4.0

Chamado com o intervalo fechado nas duas pontas, ou com `null` quando a escolha esvazia.

((range: DateRange | null) => void) | ((range: IsoDateRange | null) => void)
placeholder0.4.0

Texto do gatilho quando nao ha intervalo.

string
presets

Atalhos de periodo ao lado do calendario, numa coluna na mesa e em fichas acima do mes no celular.

boolean | DateRangePreset[]
readOnly

Mostra o periodo sem deixar mudar: o gatilho fica com a borda tracejada, continua focavel e nao abre o calendario.

boolean
showOutsideDays

Mostra os dias de fora (os que caem no mês anterior ou no seguinte).

boolean
size0.4.0

Tamanho do gatilho, o mesmo vocabulario do Input.

"lg""md""sm"
value0.4.0

O 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.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.