---
title: "Calendar"
description: "A dependency-free monthly date grid. It uses a table with weekday headers, roving tabindex and full keyboard navigation; the KotenProvider locale decides the week start and the Intl names."
kind: component
id: C-063
registry: "date-picker"
docs: "https://koten.codehive.com.co/components/calendar"
markdown: "https://koten.codehive.com.co/md/components/calendar.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/date-picker.json"
language: en
---

# Calendar · 暦

> Component C-063 in the Koten UI catalog.

A dependency-free monthly date grid. It uses a table with weekday headers, roving tabindex and full keyboard navigation; the KotenProvider locale decides the week start and the Intl names.

> Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031).

## Install

Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project.

```bash
# Node
npx shadcn@latest add https://koten.codehive.com.co/r/date-picker.json

# Bun
bunx shadcn@latest add https://koten.codehive.com.co/r/date-picker.json
```

## Files

- `@/components/ui/date-picker.tsx`
- `@/lib/koten/cn.ts`
- `@/lib/koten/format.ts`
- `@/lib/koten/intl.ts`
- `@/lib/koten/labels.ts`
- `@/lib/koten/provider.tsx`

## Requirements

- **provider** — KotenProvider: useKoten supplies labels.previous/next and the locale; useKotenFormatters builds the month, weekdays and each date's accessible name with Intl.

## Examples

### Single selection

October 2026 as the initial month, with min and max; the date is announced with Intl.

```tsx
const [selected, setSelected] = useState<Date | null>(new Date(2026, 9, 21));

<Calendar
  selected={selected}
  onSelect={setSelected}
  defaultMonth={new Date(2026, 9, 1)}
  min={new Date(2026, 9, 1)}
  max={new Date(2026, 11, 31)}
/>
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `selected` | `Date \| null` | `—` | Selected date in single mode; marked with aria-pressed. |
| `onSelect` | `(date: Date) => void` | `—` | Called on click or when Enter/Space is pressed on the focused day. |
| `rangeStart / rangeEnd` | `Date \| null` | `—` | Range endpoints; days in between use bg-selection. |
| `month` | `Date` | `—` | Controls the visible month; without it, the component keeps its own state. |
| `defaultMonth` | `Date` | `valor u hoy` | Initial month when there is no value or month; defaults to the selected date or today. |
| `onMonthChange` | `(month: Date) => void` | `—` | Notifies month changes when navigating with arrows or PageUp/PageDown. |
| `min / max` | `Date` | `—` | Disable days outside the range and limit focus movement. |
| `autoFocus` | `boolean` | `false` | Focuses the selected day or today on mount; useful inside a panel. |
| `className` | `string` | `—` | Container classes; the base width is 17.5rem. |

## Accessibility

- The grid is a table with weekday headers and a full accessible name on every date.
- Roving tabindex: only the focused day has tabindex=0, so the grid is a single tab stop.
- Arrows, Home/End, PageUp/PageDown, Enter and Space are supported; aria-pressed marks selection and aria-current="date" marks today.
- The KotenProvider locale decides the week start and the month and weekday names.

## Sources

- Catalog page: https://koten.codehive.com.co/components/calendar
- Markdown: https://koten.codehive.com.co/md/components/calendar.md
- Repository: https://github.com/codehive-colombia/koten