Calendar
Data única
| D | S | T | Q | Q | S | S |
|---|---|---|---|---|---|---|
Com limites
| D | S | T | Q | Q | S | S |
|---|---|---|---|---|---|---|
Intervalo
| D | S | T | Q | Q | S | S |
|---|---|---|---|---|---|---|
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
| Prop | Tipo |
|---|---|
animate0.4.0Anima a troca de mês. | boolean |
aria-label0.4.0O `aria-label` do elemento que contém a peça. | string |
aria-labelledby0.4.0O `aria-labelledby` do elemento que contém a peça. | string |
autoFocus0.4.0Com 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.0Mostra as semanas do mês pelo calendário de transmissão. | boolean |
captionLayout0.4.0Mostra listas para trocar de mês ou de ano. | "dropdown""dropdown-months""dropdown-years""label" |
classNames0.4.0Troca os nomes de classe usados pelo DayPicker. | Partial<ClassNames> |
components0.4.0Troca os componentes que desenham as partes do calendário. | Partial<CustomComponents> |
dateLib0.4.0Troca a biblioteca de datas padrão por outra. | Partial<DateLib> |
defaultMonth0.4.0O mês que o calendário mostra ao abrir. | Date |
defaultValueO dia inicial, quando o calendario controla o proprio estado. | Date | string |
dir0.4.0A direção do texto do calendário. | string |
disabled0.4.0Aplica o modificador `disabled` aos dias que batem. | Matcher[] | Matcher |
disableNavigation0.4.0Desliga a troca de mês. | boolean |
firstWeekContainsDate0.4.0O dia de janeiro que sempre cai na primeira semana do ano. | 1 | 4 |
fixedWeeks0.4.0Mostra sempre 6 semanas por mês, qualquer que seja o número de semanas do mês. | boolean |
footer0.4.0Põe um rodapé no calendário, que funciona como região viva. | ReactNode |
formatters0.4.0As funções que transformam datas em texto. | Partial<Formatters> |
hidden0.4.0Aplica o modificador `hidden` aos dias que batem. | Matcher[] | Matcher |
hideNavigation0.4.0Esconde os botões de navegação. | boolean |
hideWeekdays0.4.0Esconde a linha com os nomes dos dias da semana. | boolean |
ISOWeek0.4.0Usa as semanas ISO no lugar das do idioma. | boolean |
labels0.4.0As funções que escrevem os rótulos, no lugar das padrão. | Partial<Labels> |
lang0.4.0Põe a etiqueta de idioma no elemento que contém a peça. | string |
locale0.4.0O objeto de idioma usado para as datas. | Partial<DayPickerLocale> |
maxO ultimo dia que pode ser escolhido, inclusive, em `Date` ou `aaaa-mm-dd`. | stringDatenumber |
minO primeiro dia que pode ser escolhido, inclusive, em `Date` ou `aaaa-mm-dd`. | stringDatenumber |
mode0.4.0Liga a escolha de um dia, de vários dias ou de um período. | "multiple" | "range" |
modifiers0.4.0Aplica modificadores aos dias que batem. | Record<string, Matcher[] | Matcher | undefined> |
modifiersClassNames0.4.0Troca o nome de classe do dia que bate com os `modifiers`. | ModifiersClassNames |
modifiersStyles0.4.0Troca o nome de classe do dia que bate com os modificadores. | ModifiersStyles |
month0.4.0O mês mostrado no calendário. | Date |
navLayout0.4.0Ajusta a posição dos botões de navegação. | "after" | "around" |
nonce0.4.0Um nonce criptográfico ("número usado uma vez") que a Content Security Policy usa para os atributos `style` em linha. | string |
noonSafe0.4.0Faz 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.0Quantos meses aparecem. | number |
numerals0.4.0O sistema de numeração usado nas datas. | Numerals |
onDayBlur0.4.0Chamado quando um dia perde o foco. | DayEventHandler<FocusEvent<Element, Element>> |
onDayClick0.4.0Chamado quando um dia é clicado. | DayEventHandler<MouseEvent<Element, MouseEvent>> |
onDayFocus0.4.0Chamado quando um dia recebe o foco. | DayEventHandler<FocusEvent<Element, Element>> |
onDayKeyDown0.4.0Chamado quando uma tecla é apertada sobre um dia. | DayEventHandler<KeyboardEvent<Element>> |
onDayMouseEnter0.4.0Chamado quando o mouse entra num dia. | DayEventHandler<MouseEvent<Element, MouseEvent>> |
onDayMouseLeave0.4.0Chamado quando o mouse sai de um dia. | DayEventHandler<MouseEvent<Element, MouseEvent>> |
onMonthChange0.4.0Chamado quando a pessoa passa de um mês para outro. | MonthChangeEventHandler |
onNextClick0.4.0Chamado quando o botão do mês seguinte é clicado. | MonthChangeEventHandler |
onPrevClick0.4.0Chamado quando o botão do mês anterior é clicado. | MonthChangeEventHandler |
onSelectChamado a cada clique, com a escolha inteira no formato do `selected`. | OnSelectHandler<Date[]>OnSelectHandler<DateRange>OnSelectHandler<Date[] | undefined>OnSelectHandler<...> |
onValueChangeChamado com o dia tocado, no mesmo formato do `value`. | ((value: Date) => void) | ((value: string) => void) |
pagedNavigation0.4.0Navega de `numberOfMonths` em `numberOfMonths` meses por vez. | boolean |
required0.4.0Se a escolha é obrigatória. | boolean |
reverseMonths0.4.0Desenha os meses em ordem inversa (com `numberOfMonths`), o mais recente primeiro. | boolean |
reverseYears0.4.0Inverte a ordem dos anos na lista quando `captionLayout="dropdown"` ou `captionLayout="dropdown-years"`. | boolean |
role0.4.0O atributo `role` do elemento que contém a peça. | "application" | "dialog" |
selectedOs dias escolhidos: uma lista em `multiple`, um `{ from, to }` em `range`. | Date[] | DateRange |
showOutsideDays0.4.0Mostra os dias de fora (os que caem no mês anterior ou no seguinte). | boolean |
showWeekNumber0.4.0Mostra a coluna com o número da semana. | boolean |
styles0.4.0Troca os estilos em linha dos elementos HTML. | Partial<Styles> |
timeZone0.4.0O fuso horário do calendário, IANA ou diferença para o UTC (experimental). | string |
title0.4.0Põe um atributo `title` no elemento que contém a peça. | string |
today0.4.0A data de hoje. | Date |
useAdditionalDayOfYearTokens0.4.0Libera `YY` e `YYYY` como dia do ano ao formatar ou ler datas. | boolean |
useAdditionalWeekYearTokens0.4.0Libera `DD` e `DDDD` como ano da semana ao formatar ou ler datas. | boolean |
valueO dia escolhido, em `Date` ou `aaaa-mm-dd`. | Datestringnull |
weekStartsOn0.4.0O 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.mdA 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.
| Prop | Tipo | Padrão |
|---|---|---|
onOpenChangeobrigatória0.4.0 | (isOpen: boolean) => void | sem padrão |
openobrigatória0.4.0 | boolean | sem padrão |
titleobrigatória0.4.0O nome do painel. | string | sem padrão |
triggerobrigatória0.4.0O elemento que abre. | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
align0.4.0 | "end" | "start" | "start" |
footer0.4.0 | ReactNode | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.