# Calendar

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

E a única peça do catalogo com fundacao de fora, a `react-day-picker`, e ela
entra só como motor: nenhuma folha de estilo dela e importada, todo o desenho vem
dos nossos tokens. O locale padrão e `pt-BR`.

Em largura de celular mostra um mes só, mesmo quando pedem mais, e o dia ganha
44px de alvo.

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.

## No React Native

Traduz: o `@rivocode/ui-native` exporta `Calendar` - mês desenhado à mão; valor ISO `aaaa-mm-dd`, exibição `dd/mm/aaaa`; o mês novo entra por fade. A API não é a mesma do web (no nativo tudo é controlado), e a [tabela de paridade](/react-native) diz o que muda peça a peça.

## Importação

```tsx
import { Calendar } from '@rivocode/ui'
```

## Exemplos

### Data única

```tsx
import { Calendar } from '@rivocode/ui'

export function SingleDate() {
  return <Calendar mode="single" selected={new Date(2026, 2, 3)} month={new Date(2026, 2, 1)} />
}
```

### Intervalo

```tsx
import { Calendar } from '@rivocode/ui'

export function DateRange() {
  return (
    <Calendar
      mode="range"
      selected={{ from: new Date(2026, 2, 3), to: new Date(2026, 2, 12) }}
      month={new Date(2026, 2, 1)}
    />
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `animate` | `boolean` |  | 0.4.0 | Animate navigating between months. |
| `aria-label` | `string` |  | 0.4.0 | The aria-label attribute to add to the container element. |
| `aria-labelledby` | `string` |  | 0.4.0 | The aria-labelledby attribute to add to the container element. |
| `autoFocus` | `boolean` |  | 0.4.0 | When a selection mode is set, DayPicker will focus the first selected day (if set) or today's date (if not disabled). |
| `broadcastCalendar` | `boolean` |  | 0.4.0 | Display the weeks in the month following the broadcast calendar. |
| `captionLayout` | `"dropdown" \| "dropdown-months" \| "dropdown-years" \| "label"` |  | 0.4.0 | Show dropdowns to navigate between months or years. |
| `classNames` | `Partial<ClassNames>` |  | 0.4.0 | Change the class names used by DayPicker. |
| `components` | `Partial<CustomComponents>` |  | 0.4.0 | Change the components used for rendering the calendar elements. |
| `dateLib` | `Partial<DateLib>` |  | 0.4.0 | Replace the default date library with a custom one. |
| `defaultMonth` | `Date` |  | 0.4.0 | The initial month to show in the calendar. |
| `dir` | `string` |  | 0.4.0 | The text direction of the calendar. |
| `disabled` | `Matcher[] \| Matcher` |  | 0.4.0 | Apply the `disabled` modifier to the matching days. |
| `disableNavigation` | `boolean` |  | 0.4.0 | Disable the navigation between months. |
| `endMonth` | `Date` |  | 0.4.0 | The latest month to end the month navigation. |
| `firstWeekContainsDate` | `1 \| 4` |  | 0.4.0 | The day of January that is always in the first week of the year. |
| `fixedWeeks` | `boolean` |  | 0.4.0 | Display always 6 weeks per each month, regardless of the month’s number of weeks. |
| `footer` | `ReactNode` |  | 0.4.0 | Add a footer to the calendar, acting as a live region. |
| `formatters` | `Partial<Formatters>` |  | 0.4.0 | Formatters used to format dates to strings. |
| `hidden` | `Matcher[] \| Matcher` |  | 0.4.0 | Apply the `hidden` modifier to the matching days. |
| `hideNavigation` | `boolean` |  | 0.4.0 | Hide the navigation buttons. |
| `hideWeekdays` | `boolean` |  | 0.4.0 | Hide the row displaying the weekday row header. |
| `ISOWeek` | `boolean` |  | 0.4.0 | Use ISO week dates instead of the locale setting. |
| `labels` | `Partial<Labels>` |  | 0.4.0 | Labels creators to override the defaults. |
| `lang` | `string` |  | 0.4.0 | Add the language tag to the container element. |
| `locale` | `Partial<DayPickerLocale>` |  | 0.4.0 | The locale object used to localize dates. |
| `mode` | `"multiple" \| "range" \| "single"` |  | 0.4.0 | Enable the selection of a single day, multiple days, or a range of days. |
| `modifiers` | `Record<string, Matcher[] \| Matcher \| undefined>` |  | 0.4.0 | Add modifiers to the matching days. |
| `modifiersClassNames` | `ModifiersClassNames` |  | 0.4.0 | Change the class name for the day matching the `modifiers`. |
| `modifiersStyles` | `ModifiersStyles` |  | 0.4.0 | Change the class name for the day matching the modifiers. |
| `month` | `Date` |  | 0.4.0 | The month displayed in the calendar. |
| `navLayout` | `"after" \| "around"` |  | 0.4.0 | Adjust the positioning of the navigation buttons. |
| `nonce` | `string` |  | 0.4.0 | A cryptographic nonce ("number used once") which can be used by Content Security Policy for the inline `style` attributes. |
| `noonSafe` | `boolean` |  | 0.4.0 | Keep calendar math at noon in the configured timeZone to avoid historical second-level offsets drifting dates across midnight. |
| `numberOfMonths` | `number` |  | 0.4.0 | The number of displayed months. |
| `numerals` | `Numerals` |  | 0.4.0 | The numeral system to use when formatting dates. |
| `onDayBlur` | `DayEventHandler<FocusEvent<Element, Element>>` |  | 0.4.0 | Event handler when a day is blurred. |
| `onDayClick` | `DayEventHandler<MouseEvent<Element, MouseEvent>>` |  | 0.4.0 | Event handler when a day is clicked. |
| `onDayFocus` | `DayEventHandler<FocusEvent<Element, Element>>` |  | 0.4.0 | Event handler when a day is focused. |
| `onDayKeyDown` | `DayEventHandler<KeyboardEvent<Element>>` |  | 0.4.0 | Event handler when a key is pressed on a day. |
| `onDayMouseEnter` | `DayEventHandler<MouseEvent<Element, MouseEvent>>` |  | 0.4.0 | Event handler when the mouse enters a day. |
| `onDayMouseLeave` | `DayEventHandler<MouseEvent<Element, MouseEvent>>` |  | 0.4.0 | Event handler when the mouse leaves a day. |
| `onMonthChange` | `MonthChangeEventHandler` |  | 0.4.0 | Event fired when the user navigates between months. |
| `onNextClick` | `MonthChangeEventHandler` |  | 0.4.0 | Event handler when the next month button is clicked. |
| `onPrevClick` | `MonthChangeEventHandler` |  | 0.4.0 | Event handler when the previous month button is clicked. |
| `pagedNavigation` | `boolean` |  | 0.4.0 | Paginate the month navigation displaying the `numberOfMonths` at a time. |
| `required` | `boolean` |  | 0.4.0 | Whether the selection is required. |
| `reverseMonths` | `boolean` |  | 0.4.0 | Render the months in reversed order (when numberOfMonths is set) to display the most recent month first. |
| `reverseYears` | `boolean` |  | 0.4.0 | Reverse the order of years in the dropdown when using `captionLayout="dropdown"` or `captionLayout="dropdown-years"`. |
| `role` | `"application" \| "dialog"` |  | 0.4.0 | The role attribute to add to the container element. |
| `showOutsideDays` | `boolean` |  | 0.4.0 | Show the outside days (days falling in the next or the previous month). |
| `showWeekNumber` | `boolean` |  | 0.4.0 | Show the week numbers column. |
| `startMonth` | `Date` |  | 0.4.0 | The earliest month to start the month navigation. |
| `styles` | `Partial<Styles>` |  | 0.4.0 | Change the inline styles of the HTML elements. |
| `timeZone` | `string` |  | 0.4.0 | The time zone (IANA or UTC offset) to use in the calendar (experimental). |
| `title` | `string` |  | 0.4.0 | Add a `title` attribute to the container element. |
| `today` | `Date` |  | 0.4.0 | The today’s date. |
| `useAdditionalDayOfYearTokens` | `boolean` |  | 0.4.0 | Enable `YY` and `YYYY` for day of year tokens when formatting or parsing dates. |
| `useAdditionalWeekYearTokens` | `boolean` |  | 0.4.0 | Enable `DD` and `DDDD` for week year tokens when formatting or parsing dates. |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | 0.4.0 | The index of the first day of the week (0 - Sunday). |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Partes

O componente se monta com as peças abaixo. Todas vêm de `@rivocode/ui`.

### CalendarPanel

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.

```tsx
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 que o leitor de
tela anuncia no celular, onde o painel vira folha e perde o campo ao lado que
dava o contexto.

| Prop | Tipo | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `onOpenChange` | `(isOpen: boolean) => void` | sim | 0.4.0 |  |
| `open` | `boolean` | sim | 0.4.0 |  |
| `title` | `string` | sim | 0.4.0 | Titulo lido no celular, onde o painel vira folha e perde o contexto. |
| `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | sim | 0.4.0 | O elemento que abre. |
| `align` | `"end" \| "start"` |  | 0.4.0 |  |
| `footer` | `ReactNode` |  | 0.4.0 |  |

## Ver também

- [Autocomplete](/componentes/autocomplete.md)
- [Checkbox](/componentes/checkbox.md)
- [CheckboxGroup](/componentes/checkbox-group.md)
- [ColorPicker](/componentes/color-picker.md)
- [Combobox](/componentes/combobox.md)
- [DatePicker](/componentes/date-picker.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)