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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/calendar.md.

Calendar

Browse and select dates, with optional schedule content.

Basic usage

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

October 2026
basic.tsx
import { Calendar } from '@ifhover/leaf-ui';

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

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.

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}
    />
  );
}

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
month.tsx
import { Calendar } from '@ifhover/leaf-ui';

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

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
Selected date: 2026-10-15
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>
  );
}

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
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;
      }}
    />
  );
}

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. Calendar does not provide native form submission or reset behavior; use DatePicker for those features.

API

Calendar API

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

PropertyTypeDefaultDescription
valueDate—Controlled selected date, independent of visibleDate.
defaultValueDate—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
fullscreenbooleantrueFull calendar layout
minDateDate—Date bounds
maxDateDate—Date bounds
disabledDate(date: Date) => boolean—Disable specific dates
visibleDateDate—Controlled visible month, not the selected date.
onVisibleChange(date: Date) => void—Return the first day when the visible month changes, without selecting a date.
showTodaybooleantrueShow 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.
headerExtraReactNode—Additional header content