# Calendar

> A month of days to pick a date from.

A calendar shows a month on the page to pick a day from, such as a release date when the date is the main task of the screen. In a form, use the [Date Picker](https://design.sosialoka.tech/components/date-picker/), which opens this calendar in a popover.

## When to use

- Use it inline when picking the date is the task, such as scheduling a release.
- In forms, use the Date Picker instead, so the calendar only takes space when it is open.
- For dates far in the past, such as a birth date, use the month and year pickers (`captionLayout="dropdown"` in React, `layout="month-and-year"` in Vue).

_Live preview of the React and Vue versions: https://design.sosialoka.tech/components/calendar/_

## Anatomy

1. Month heading
2. Weekdays, starting Monday
3. Selected day
4. Today

A heading with the month and year, previous and next buttons, a row of short weekday names and the days.

| Day | Style |
| --- | --- |
| Any day | 36px (`size-9`), `rounded-md` |
| Today | A `ring` |
| Selected | `bg-primary`, `text-primary-foreground` |
| Outside the month | `muted-foreground` |

It speaks English by default (en-GB): "November 2026", "Mo Tu We Th Fr Sa Su", and weeks start on Monday. For Indonesian, pass `id` from `react-day-picker/locale` in React or `locale="id-ID"` in Vue, as the example does; Flutter follows the app's locale.

## Props

| React | Vue | Flutter | Type | Default | Use |
| --- | --- | --- | --- | --- | --- |
| `mode="single"` | single by default | `ShadCalendar` | | single | Pick one day, a range or several days. |
| `selected`, `onSelect` | `v-model` | `selected`, `onChanged` | `Date` / `DateValue` / `DateTime` | none | The chosen day. |
| `locale` | `locale` | the app's `locale` | locale | English (en-GB) | Month and day names, and the first day of the week. |
| `defaultMonth` | `default-placeholder` | `initialMonth` | date | today | The month shown first. |
| `captionLayout` | `layout` | `captionLayout` | text | label | Month and year pickers instead of the heading. |

## Code

**React**
```tsx
import { useState } from "react"
import { id } from "react-day-picker/locale"
import { Calendar } from "@/components/ui/calendar"

export default function CalendarDemo() {
  const [date, setDate] = useState<Date | undefined>(new Date(2026, 10, 14))
  return <Calendar locale={id} mode="single" selected={date} onSelect={setDate} defaultMonth={date} className="rounded-lg border border-border" />
}
```

**Vue**
```vue
<script setup lang="ts">
import type { DateValue } from "@internationalized/date"
import { CalendarDate } from "@internationalized/date"
import { shallowRef } from "vue"
import { Calendar } from "@/components/ui/calendar"

const date = shallowRef<DateValue>(new CalendarDate(2026, 11, 14))
</script>

<template>
  <Calendar v-model="date" locale="id-ID" :default-placeholder="date" class="rounded-lg border border-border" />
</template>
```

**Flutter**
```dart
// ShadCalendar reads month and weekday names from the app locale: run the app with
// locale: Locale('id') and GlobalMaterialLocalizations.delegates (flutter_localizations).
import 'package:flutter/widgets.dart';
import 'package:shadcn_ui/shadcn_ui.dart';

class CalendarDemo extends StatelessWidget {
  const CalendarDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return ShadCalendar(
      selected: DateTime(2026, 11, 14),
      initialMonth: DateTime(2026, 11),
      weekStartsOn: 1,
    );
  }
}
```

## Install

**React**
```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/calendar.json
```

**Vue**
```bash
npx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/calendar.json
```

## Accessibility

- Arrow keys move between days, Page Up and Page Down between months, and Enter or Space picks the day.
- Each day button says its full date, such as "Sabtu, 14 November 2026", and whether it is today or chosen.
- The previous and next buttons are named "Ke bulan sebelumnya" and "Ke bulan berikutnya".
