# Mini Calendar

The month picker at the top of the calendar sidebar.

Live example, interactive at https://calendarcn.xyz/docs/components/mini-calendar. Its source:

```tsx title="src/examples/mini-calendar-demo.tsx"
"use client";

import * as React from "react";
import { addDays, format, startOfWeek } from "date-fns";

import { MiniCalendar } from "@/components/mini-calendar";

/** Days in the highlighted week */
const DAYS_PER_WEEK = 7;

/** The week that contains `date`, Sunday first */
function getWeekDays(date: Date): Date[] {
  const start = startOfWeek(date);
  return Array.from({ length: DAYS_PER_WEEK }, (_, index) =>
    addDays(start, index),
  );
}

export function MiniCalendarDemo() {
  // Picked day, shown as the week around it. `null` until the first pick,
  // so the server and the browser render the same markup
  const [picked, setPicked] = React.useState<Date | null>(null);
  const visibleDays = React.useMemo(
    () => (picked ? getWeekDays(picked) : undefined),
    [picked],
  );

  return (
    <div className="flex h-full flex-col items-center justify-center gap-3">
      <div className="w-60 rounded-lg bg-sidebar py-2 shadow-xs ring-1 ring-black/5 dark:ring-white/10">
        <MiniCalendar
          currentDate={picked ?? undefined}
          visibleDays={visibleDays}
          onDateSelect={setPicked}
        />
      </div>
      <p className="text-sm text-muted-foreground tabular-nums">
        {picked
          ? `Week of ${format(visibleDays?.[0] ?? picked, "MMM d")}`
          : "Pick a day"}
      </p>
    </div>
  );
}
```

Mini Calendar is the small month at the top of the [Calendar Sidebar](/docs/components/calendar-sidebar), modeled on Notion Calendar's: week numbers down the side (`showWeekNumber={false}` hides them; [Calendar Sidebar](/docs/components/calendar-sidebar) shows them while the provider's week numbers are on), today in red, and the days the calendar shows highlighted as one band. Browse months with the up and down arrows; away from today's month, the month's name shows with a button back to today.

It's built on [React DayPicker](https://daypicker.dev) directly, with its own styles, so it looks the same whatever your shadcn/ui `Calendar` and `Button` look like.

## Installation

```bash
npx shadcn add @calendarcn/mini-calendar
```

Or install it by hand:

1. Install the items it builds on: `@calendarcn/calendar-core`
2. Install the dependencies: `npm install date-fns lucide-react react-day-picker@^9`
3. Add the shadcn/ui components it uses: `npx shadcn add tooltip`
4. Copy these files into your project, keeping the paths under your components, hooks and lib folders:
   - [`components/mini-calendar.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/mini-calendar.tsx)

## Usage

```tsx
import { MiniCalendar } from "@/components/mini-calendar";

export function DatePicker() {
  const [date, setDate] = React.useState<Date>();

  return <MiniCalendar currentDate={date} onDateSelect={setDate} />;
}
```

To follow a calendar, pass the days it shows as `visibleDays`: they're highlighted, and the mini calendar shows the month of the last one, so a week that crosses into a new month shows the new month. Calendar Sidebar does this from `useCalendar()`:

```tsx
const { view, currentDate, visibleDays, weekStartsOn, goToDate } =
  useCalendar();

<MiniCalendar
  currentDate={currentDate}
  visibleDays={view === "month" || view === "agenda" ? [] : visibleDays}
  weekStartsOn={weekStartsOn}
  onDateSelect={goToDate}
/>;
```

When `currentDate` or `visibleDays` change, the mini calendar goes back to their month, even after the arrows browsed away.

## Features

- Today is marked in your theme's primary color. The page renders with no today marked, then marks it in the browser, so server and client markup match.
- "Go back to today" shows once you browse to another month. It shows today's month and calls `onDateSelect` with today.
- Every day is a click target from edge to edge, with no gaps between days. Arrow keys move between days; the focused day gets a ring.
- Six weeks always show, so the height never changes between months.

## API Reference

### MiniCalendar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `currentDate` | `Date` | – | Day the calendar is on. Picks the month shown when there are no `visibleDays` (month view, agenda). |
| `visibleDays` | `Date[]` | – | Days the calendar shows. They're highlighted, and the month of the last one is shown. |
| `onDateSelect` | `(date: Date) => void` | – | Called with the day picked, or with today from "Go back to today". |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `0` | First day of the week, 0 (Sunday) to 6. |
| `className` | `string` | – | Classes for the calendar's root. |
