Pular para o conteúdo
Formulário

Calendar

/componentes/calendar.mdmarkdown cru, para quem lê com agent em vez de olho

Data única

março 2026

Com limites

março 2026

Intervalo

março 2026
Importar
import { Calendar } from '@rivocode/ui'

Quando usar

O mês cru, para quem quer o calendário na própria tela.

O motor é a react-day-picker: nenhuma folha de estilo dela é importada, e todo o desenho vem dos nossos tokens. O locale padrão é pt-BR.

O cabeçalho abre o seletor de mês e de ano (captionLayout="dropdown" é o padrão), então pular para uma data distante não pede dezenas de cliques na seta. Os anos do seletor respeitam min e max.

Em largura de celular mostra um mês só, mesmo quando pedem mais, e o dia ganha 44px de alvo. Na tela mais estreita que isso, abaixo de uns 360px, o dia encolhe junto com a tela para as sete colunas caberem sem rolar para o lado: a 320px cada dia fica com uns 38px, ainda acima dos 24 da WCAG 2.5.8.

A raiz tem a largura da grade (w-fit), e não a da coluna onde ela mora. As células têm largura fixa e as setas de mês correm nas pontas da raiz: com a raiz esticada numa coluna larga, a grade ficava à esquerda e a seta de próximo sobrava lá na outra ponta. Para centralizar, className="mx-auto"; para esticar de propósito, className="w-full" vence o w-fit.

Valor

O dia escolhido entra por value e sai por onValueChange, como em todo seletor do catálogo e como no @rivocode/ui-native. O valor pode ser Date ou texto aaaa-mm-dd, e a peça responde no formato que recebeu: quem passa texto recebe texto, e a mesma chamada compila nos dois pacotes.

const [vencimento, setVencimento] = useState<string | null>(null)

<Calendar
  value={vencimento}
  onValueChange={setVencimento}
  min="2026-09-01"
  max="2026-12-31"
/>

Sem estado próprio, defaultValue dá o dia inicial e o calendário guarda a escolha sozinho, nos mesmos dois formatos e respondendo no mesmo formato, como o DatePicker:

<Calendar defaultValue="2026-09-25" onValueChange={(dia) => console.log(dia)} />

O texto é lido como dia do calendário, e não como instante: "2026-09-25" é 25 de setembro em qualquer fuso. O new Date("2026-09-25") do JavaScript lê meia-noite em UTC, que em Brasília ainda é dia 24.

min e max são inclusivos e aceitam os mesmos dois formatos. Os dias de fora ficam desabilitados, e a navegação para no mês de cada ponta. Tocar de novo no dia escolhido não desmarca.

Data única é sempre value e onValueChange, sem mode. Várias datas soltas e intervalo vão pelo mode do react-day-picker, "multiple" ou "range", com selected e onSelect; ali o min e o max aceitam também um número, que é a quantidade mínima e máxima de dias da escolha.

<Calendar mode="range" selected={periodo} onSelect={setPeriodo} min="2026-01-01" />

A troca de mês anima: o mês novo entra pelo lado para onde a pessoa andou, em 200ms, e com "reduzir movimento" ligado a troca é instantânea. animate={false} desliga.

Quando não usar

Num formulário, a data é DatePicker: ele aceita digitação, valida, mostra o motivo do erro e só abre o calendário quando a pessoa pede. O Calendar solto ocupa um mês inteiro de tela para uma resposta que cabe num campo.

Período de filtro é DateRangePicker, com o Aplicar no rodapé. E agenda com compromissos, hora e duração é EventCalendar: o Calendar responde "que dia?", e não "o que acontece nele".

No React Native

Traduz: o @rivocode/ui-native exporta Calendar - mês desenhado à mão; value, onValueChange, min e max em ISO aaaa-mm-dd, que o web também aceita; exibição dd/mm/aaaa; o mês novo entra por fade; classNames com os nomes do DayPicker do web; disabled, modifiers e modifiersClassNames com os nomes e as formas do web ({ dayOfWeek }, { from, to }, { before }, { after }, lista, função), com o dia em Date ou aaaa-mm-dd, e o dia marcado ganha um ponto embaixo do número e o nome da marca na fala; month e onMonthChange controlam o mês, em aaaa-mm-dd. A API não é a mesma do web (no nativo tudo é controlado), e a tabela de paridade diz o que muda peça a peça.

API

PropTipo
animate0.4.0

Anima a troca de mês.

boolean
aria-label0.4.0

O `aria-label` do elemento que contém a peça.

string
aria-labelledby0.4.0

O `aria-labelledby` do elemento que contém a peça.

string
autoFocus0.4.0

Com um modo de escolha, o foco vai para o primeiro dia escolhido, se houver, ou para hoje, se não estiver desabilitado.

boolean
broadcastCalendar0.4.0

Mostra as semanas do mês pelo calendário de transmissão.

boolean
captionLayout0.4.0

Mostra listas para trocar de mês ou de ano.

"dropdown""dropdown-months""dropdown-years""label"
classNames0.4.0

Troca os nomes de classe usados pelo DayPicker.

Partial<ClassNames>
components0.4.0

Troca os componentes que desenham as partes do calendário.

Partial<CustomComponents>
dateLib0.4.0

Troca a biblioteca de datas padrão por outra.

Partial<DateLib>
defaultMonth0.4.0

O mês que o calendário mostra ao abrir.

Date
defaultValue

O dia inicial, quando o calendario controla o proprio estado.

Date | string
dir0.4.0

A direção do texto do calendário.

string
disabled0.4.0

Aplica o modificador `disabled` aos dias que batem.

Matcher[] | Matcher
disableNavigation0.4.0

Desliga a troca de mês.

boolean
firstWeekContainsDate0.4.0

O dia de janeiro que sempre cai na primeira semana do ano.

1 | 4
fixedWeeks0.4.0

Mostra sempre 6 semanas por mês, qualquer que seja o número de semanas do mês.

boolean
footer0.4.0

Põe um rodapé no calendário, que funciona como região viva.

ReactNode
formatters0.4.0

As funções que transformam datas em texto.

Partial<Formatters>
hidden0.4.0

Aplica o modificador `hidden` aos dias que batem.

Matcher[] | Matcher
hideNavigation0.4.0

Esconde os botões de navegação.

boolean
hideWeekdays0.4.0

Esconde a linha com os nomes dos dias da semana.

boolean
ISOWeek0.4.0

Usa as semanas ISO no lugar das do idioma.

boolean
labels0.4.0

As funções que escrevem os rótulos, no lugar das padrão.

Partial<Labels>
lang0.4.0

Põe a etiqueta de idioma no elemento que contém a peça.

string
locale0.4.0

O objeto de idioma usado para as datas.

Partial<DayPickerLocale>
max

O ultimo dia que pode ser escolhido, inclusive, em `Date` ou `aaaa-mm-dd`.

stringDatenumber
min

O primeiro dia que pode ser escolhido, inclusive, em `Date` ou `aaaa-mm-dd`.

stringDatenumber
mode0.4.0

Liga a escolha de um dia, de vários dias ou de um período.

"multiple" | "range"
modifiers0.4.0

Aplica modificadores aos dias que batem.

Record<string, Matcher[] | Matcher | undefined>
modifiersClassNames0.4.0

Troca o nome de classe do dia que bate com os `modifiers`.

ModifiersClassNames
modifiersStyles0.4.0

Troca o nome de classe do dia que bate com os modificadores.

ModifiersStyles
month0.4.0

O mês mostrado no calendário.

Date
navLayout0.4.0

Ajusta a posição dos botões de navegação.

"after" | "around"
nonce0.4.0

Um nonce criptográfico ("número usado uma vez") que a Content Security Policy usa para os atributos `style` em linha.

string
noonSafe0.4.0

Faz as contas do calendário ao meio-dia do fuso configurado, para diferenças históricas de segundos não empurrarem a data para o outro lado da meia-noite.

boolean
numberOfMonths0.4.0

Quantos meses aparecem.

number
numerals0.4.0

O sistema de numeração usado nas datas.

Numerals
onDayBlur0.4.0

Chamado quando um dia perde o foco.

DayEventHandler<FocusEvent<Element, Element>>
onDayClick0.4.0

Chamado quando um dia é clicado.

DayEventHandler<MouseEvent<Element, MouseEvent>>
onDayFocus0.4.0

Chamado quando um dia recebe o foco.

DayEventHandler<FocusEvent<Element, Element>>
onDayKeyDown0.4.0

Chamado quando uma tecla é apertada sobre um dia.

DayEventHandler<KeyboardEvent<Element>>
onDayMouseEnter0.4.0

Chamado quando o mouse entra num dia.

DayEventHandler<MouseEvent<Element, MouseEvent>>
onDayMouseLeave0.4.0

Chamado quando o mouse sai de um dia.

DayEventHandler<MouseEvent<Element, MouseEvent>>
onMonthChange0.4.0

Chamado quando a pessoa passa de um mês para outro.

MonthChangeEventHandler
onNextClick0.4.0

Chamado quando o botão do mês seguinte é clicado.

MonthChangeEventHandler
onPrevClick0.4.0

Chamado quando o botão do mês anterior é clicado.

MonthChangeEventHandler
onSelect

Chamado a cada clique, com a escolha inteira no formato do `selected`.

OnSelectHandler<Date[]>OnSelectHandler<DateRange>OnSelectHandler<Date[] | undefined>OnSelectHandler<...>
onValueChange

Chamado com o dia tocado, no mesmo formato do `value`.

((value: Date) => void) | ((value: string) => void)
pagedNavigation0.4.0

Navega de `numberOfMonths` em `numberOfMonths` meses por vez.

boolean
required0.4.0

Se a escolha é obrigatória.

boolean
reverseMonths0.4.0

Desenha os meses em ordem inversa (com `numberOfMonths`), o mais recente primeiro.

boolean
reverseYears0.4.0

Inverte a ordem dos anos na lista quando `captionLayout="dropdown"` ou `captionLayout="dropdown-years"`.

boolean
role0.4.0

O atributo `role` do elemento que contém a peça.

"application" | "dialog"
selected

Os dias escolhidos: uma lista em `multiple`, um `{ from, to }` em `range`.

Date[] | DateRange
showOutsideDays0.4.0

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

boolean
showWeekNumber0.4.0

Mostra a coluna com o número da semana.

boolean
styles0.4.0

Troca os estilos em linha dos elementos HTML.

Partial<Styles>
timeZone0.4.0

O fuso horário do calendário, IANA ou diferença para o UTC (experimental).

string
title0.4.0

Põe um atributo `title` no elemento que contém a peça.

string
today0.4.0

A data de hoje.

Date
useAdditionalDayOfYearTokens0.4.0

Libera `YY` e `YYYY` como dia do ano ao formatar ou ler datas.

boolean
useAdditionalWeekYearTokens0.4.0

Libera `DD` e `DDDD` como ano da semana ao formatar ou ler datas.

boolean
value

O dia escolhido, em `Date` ou `aaaa-mm-dd`.

Datestringnull
weekStartsOn0.4.0

O primeiro dia da semana (0 é domingo).

0123456

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

Partes

Calendar se monta com estas peças. Todas vivem nesta página, porque separar cada uma num endereço obrigaria a abrir seis abas para montar uma tela.

CalendarPanel

/calendar-panel.md

A casca do calendário: painel ancorado na mesa, folha de baixo no celular.

O DatePicker e o DateRangePicker já a usam por dentro. Ela sai exportada para o seletor de data que a sua tela inventa (o filtro de período de um relatório, o calendário de agendamento) continuar trocando de formato do mesmo jeito que os da casa.

A troca é de formato e não de conteúdo. Calendário ancorado num campo perto do rodapé do celular abre para fora da tela ou por cima do teclado, e a pessoa precisa rolar a página com o painel aberto. A folha resolve isso sem mexer em nada do que vai dentro.

const [aberto, setAberto] = useState(false)

<CalendarPanel
  open={aberto}
  onOpenChange={setAberto}
  title="Período do relatório"
  trigger={<Button variant="secondary">Escolher período</Button>}
  footer={<Button onClick={aplicar}>Aplicar</Button>}
>
  <Calendar mode="range" selected={faixa} onSelect={setFaixa} />
</CalendarPanel>

open, onOpenChange e title são obrigatórios, e os três pelo mesmo motivo. A abertura é controlada porque quem confirma com um rodapé precisa fechar o painel no momento certo, e não no clique. O title é o nome do painel. No celular, onde o painel vira folha e perde o campo ao lado que dava o contexto, ele sai escrito no topo da folha e é o que o leitor de tela anuncia; na mesa, ao lado do campo, ele nomeia o painel só para o leitor de tela.

Quando não usar

Para escolher uma data num campo de formulário, use DatePicker, e para um período, DateRangePicker: os dois já trazem a casca, o campo digitável e a validação. O CalendarPanel é para o seletor que nenhum dos dois cobre.

Para conteúdo que não é calendário, ancorado num botão, é Popover: ele não vira folha no celular, e a troca de formato só se paga quando o conteúdo é grande como um mês inteiro.

PropTipoPadrão
onOpenChangeobrigatória0.4.0(isOpen: boolean) => voidsem padrão
openobrigatória0.4.0booleansem padrão
titleobrigatória0.4.0

O nome do painel.

stringsem padrão
triggerobrigatória0.4.0

O elemento que abre.

ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão
align0.4.0"end" | "start""start"
footer0.4.0ReactNodesem padrão

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.