> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/calendar.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# Calendar

Browse and select dates, with optional schedule content.


## Basic usage

Set the initial selection with `defaultValue`; selecting a date calls `onChange`.


**October** 2026

MonthYear

Today

MonMTueTWedWThuTFriFSatSSunS

28

29

30

Oct 1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

Nov 1

2

3

4

5

6

7

8

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/calendar/basic.tsx"
import { Calendar } from '@ifhover/leaf-ui';

export function CalendarBasic() {
  return <Calendar defaultValue={new Date(2026, 9, 4)} />;
}
```

Expand code


## Examples

### Compact calendar

Set `fullscreen={false}` for a compact calendar. This example excludes weekends with `disabledDate`; click the title to switch to the month view.


**October** 2026

MonMTueTWedWThuTFriFSatSSunS

28

29

30

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

1

2

3

4

5

6

7

8

compact.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/calendar/compact.tsx"
import { Calendar } from '@ifhover/leaf-ui';

export function CalendarCompact() {
  return (
    <Calendar
      fullscreen={false}
      defaultValue={new Date(2026, 9, 6)}
      disabledDate={(date) => date.getDay() === 0 || date.getDay() === 6}
    />
  );
}
```

Expand code

### Choose a month

`mode="month"` selects a month and returns a local `Date` for its first day. In this mode, `disabledDate` also receives the first day of the month.


**2026**

JanFebMarAprMayJunJulAugSepOctNovDec

month.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/calendar/month.tsx"
import { Calendar } from '@ifhover/leaf-ui';

export function CalendarMonth() {
  return <Calendar fullscreen={false} mode="month" defaultValue={new Date(2026, 9, 1)} />;
}
```

Expand code

### Controlled selection and displayed month

[](#)
`value` controls selection, while `visibleDate` controls the displayed month. Paging or clicking Today changes the displayed month without selecting a date; `onVisibleChange` returns the first day of the new month. The example uses `headerExtra` to return to the selected month.


**October** 2026

View selected month

MonthYear

Today

MonMTueTWedWThuTFriFSatSSunS

28

29

30

Oct 1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

Nov 1

2

3

4

5

6

7

8

Selected date: 2026-10-15

controlled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/calendar/controlled.tsx"
import { Button, Calendar, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

function formatDate(date: Date) {
  return [date.getFullYear(), date.getMonth() + 1, date.getDate()]
    .map((part, index) => (index === 0 ? String(part) : String(part).padStart(2, '0')))
    .join('-');
}

export function CalendarControlled() {
  const [value, setValue] = useState(new Date(2026, 9, 15));
  const [visibleDate, setVisibleDate] = useState(new Date(2026, 9, 1));

  return (
    <Flex direction="column" gap="md">
      <Calendar
        value={value}
        onChange={setValue}
        visibleDate={visibleDate}
        onVisibleChange={setVisibleDate}
        headerExtra={
          <Button size="sm" onClick={() => setVisibleDate(value)}>
            View selected month
          </Button>
        }
      />
      <Text tone="muted" role="status">
        Selected date: {formatDate(value)}
      </Text>
    </Flex>
  );
}
```

Expand code

### Schedule content

Use `cellRender` for text, icons or Tags. Content is placed inside the date button, so do not nest links, buttons or other interactive elements; provide schedule actions outside the calendar.


**October** 2026

MonthYear

Today

MonMTueTWedWThuTFriFSatSSunS

28

29

30

Oct 1

2

3

4

5

6

7

8Review

9

10

11

12

13

14

15Release

16

17

18

19

20

21

22Sync

23

24

25

26

27

28

29

30

31

Nov 1

2

3

4

5

6

7

8

schedule.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/calendar/schedule.tsx"
import { Calendar, Tag } from '@ifhover/leaf-ui';

const events: Record<string, string> = {
  '2026-10-8': 'Review',
  '2026-10-15': 'Release',
  '2026-10-22': 'Sync',
};

export function CalendarSchedule() {
  return (
    <Calendar
      defaultValue={new Date(2026, 9, 4)}
      cellRender={(date) => {
        const event = events[`${date.getFullYear()}-${date.getMonth() + 1}-${date.getDate()}`];
        return event ? <Tag>{event}</Tag> : null;
      }}
    />
  );
}
```

Expand code

Dates use local `Date` values; `minDate` / `maxDate` include their boundary days. For SSR, provide the same initial date on the server and client; see [server-side rendering](https://ifhover.github.io/leaf-ui/en/guide/ssr.md). Calendar does not provide native form submission or reset behavior; use [DatePicker](https://ifhover.github.io/leaf-ui/en/components/date-picker.md) for those features.


## API

### Calendar API

Configuration for the selected date, visible month and selectable date range.

| Property          | Type                        | Default  | Description                                                                            |
| ----------------- | --------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `value`           | `Date`                      | —        | Controlled selected date, independent of visibleDate.                                  |
| `defaultValue`    | `Date`                      | —        | Initial selected date for uncontrolled usage.                                          |
| `onChange`        | `(date: Date) => void`      | —        | Called on selection; month mode returns the first day of the selected month.           |
| `mode`            | `'date' \| 'month'`         | `'date'` | Select dates or months                                                                 |
| `fullscreen`      | `boolean`                   | `true`   | Full calendar layout                                                                   |
| `minDate`         | `Date`                      | —        | Date bounds                                                                            |
| `maxDate`         | `Date`                      | —        | Date bounds                                                                            |
| `disabledDate`    | `(date: Date) => boolean`   | —        | Disable specific dates                                                                 |
| `visibleDate`     | `Date`                      | —        | Controlled visible month, not the selected date.                                       |
| `onVisibleChange` | `(date: Date) => void`      | —        | Return the first day when the visible month changes, without selecting a date.         |
| `showToday`       | `boolean`                   | `true`   | Show navigation to today; changes the visible month without selecting a date.          |
| `cellRender`      | `(date: Date) => ReactNode` | —        | Customize cell contents inside the selection button; do not nest interactive controls. |
| `headerExtra`     | `ReactNode`                 | —        | Additional header content                                                              |
