---
title: "Calendar"
description: "A month grid for picking one day, with keyboard navigation and optional first and last selectable dates."
---

Use it to pick a single day when seeing the month helps: scheduling an event, choosing when a timeout ends. For a date the reader already knows, such as a birthday, a text field is faster.

Dates go in and out as `YYYY-MM-DD` strings. They sort as text, survive JSON, and carry no time zone, so the day the reader picked is the day you store.

_Live example of Calendar — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add calendar
```

Files written — React: components/ui/calendar.tsx. Vue: components/ui/calendar/Calendar.vue, components/ui/calendar/index.ts.

## Usage

React:

```tsx
import { Calendar } from "@/components/ui/calendar"
```

Vue:

```ts
import { Calendar } from "@/components/ui/calendar"
```

## Examples

### Date range

Set both `min` and `max` to limit the choice to a window. Days outside it are disabled, and the keyboard never lands on them.

_Live example of Calendar — see the page for the rendered demo._

### Locale and week start

`locale` translates the month and weekday names. The first day of the week and the labels of the two month buttons are separate props: set `weekStartsOn`, `previousLabel` and `nextLabel` to match.

_Live example of Calendar — see the page for the rendered demo._

## API reference

**`Calendar`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / v-model` | `string` | — | The chosen day as `YYYY-MM-DD`. In React, leave it undefined and pass `defaultValue` to let the calendar own it. |
| `onValueChange` | `(value: string) => void` | — | React only. Called with the chosen day; Vue emits `update:modelValue`. |
| `min` | `string` | — | The first day that can be chosen. Earlier days are disabled. |
| `max` | `string` | — | The last day that can be chosen. Later days are disabled. |
| `locale` | `string` | `"en-US"` | A BCP 47 tag for the month and weekday names. |
| `weekStartsOn` | `0 \| 1` | `0` | `0` starts the week on Sunday, `1` on Monday. |
| `previousLabel` | `string` | `"Previous month"` | Accessible name of the previous-month button. |
| `nextLabel` | `string` | `"Next month"` | Accessible name of the next-month button. |

With no value, the calendar opens on the current month once it is running in the browser; today is the reader's own date, so it is not known during server rendering.

## Accessibility

The month is a table with `role="grid"`, named by the month and year, with the full weekday name on each column heading. One day at a time is a tab stop. The arrow keys move by a day or a week, `Home` and `End` go to the ends of the week, `Page Up` and `Page Down` change month, and moving past the edge of the month turns the page. `Enter` or `Space` chooses the focused day. Today is marked with `aria-current="date"` and an outline, the chosen day with `aria-selected` and a fill, so the two differ in shape as well as colour. Say the chosen date in text near the calendar, as the example does.

Pass `locale` for the month and day names, and `previousLabel` and `nextLabel` for the two buttons. [Translating labels](/docs/translating-labels) lists every English default.

## Tokens

Calendar reads its colours, radii and motion from the `--newt-*` tokens. Override a token rather than editing the component.
