XDS — Design System

Calendar@xds/core · XDSCalendar v0.0.13

Usage

Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.

ts
import {XDSCalendar} from '@xds/core/Calendar'

Best practices

Guidance	Practices
Do	Set min and max dates to limit selection to a valid window — like only future dates for a booking or the current quarter for a report.
Do	Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.
Do	Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.
Do	Show two months side by side when the user frequently selects dates that span a month boundary.
Don't	Use a calendar for dates far in the past or future like a birth date — a text input is faster for open-ended entry.
Don't	Disable large blocks of dates without context — the user should understand why dates are unavailable.

Examples

Common configurations, variations, and states.

Calendar — ConstraintsLimit which dates can be selected using min/max bounds and custom rules like weekdays only. Use for scheduling UIs where certain dates are unavailable.

tsx
'use client';
import {useState} from 'react';
import {XDSCalendar, type ISODateString} from '@xds/core/Calendar';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
const isWeekday = (date: Date) => {
  const day = date.getDay();
  return day !== 0 && day !== 6;
};
export default function CalendarConstraints() {
  const [value, setValue] = useState<ISODateString | undefined>(undefined);
  return (
    <XDSStack direction="vertical" gap={4} hAlign="center">
      <XDSText type="supporting" color="secondary">
        Jan 10 – Mar 20, weekdays only
      </XDSText>
      <XDSCalendar
        mode="single"
        min={'2026-01-10' as ISODateString}
        max={'2026-03-20' as ISODateString}
        dateConstraints={[isWeekday]}
        value={value}
        onChange={val => setValue(val)}
        focusDate={'2026-01-01' as ISODateString}
      />
    </XDSStack>
  );
}

Calendar — RangePick a start and end date with the range highlighted between them. Use for booking dates, time-off requests, or report filters.

tsx
'use client';
import {useState} from 'react';
import {XDSCalendar, type DateRange} from '@xds/core/Calendar';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function CalendarRangeWithValue() {
  const [value, setValue] = useState<DateRange>({
    start: '2026-01-10',
    end: '2026-01-20',
  });
  return (
    <XDSStack direction="vertical" gap={4} hAlign="center">
      <XDSText type="supporting" color="secondary">
        {value.start && value.end
          ? `${value.start} → ${value.end}`
          : 'Pick a start and end date'}
      </XDSText>
      <XDSCalendar
        mode="range"
        value={value}
        onChange={range => setValue(range)}
        focusDate="2026-01-01"
      />
    </XDSStack>
  );
}

Calendar — SinglePick one date from a month grid. Use for appointment dates, due dates, or any field that needs a single date.

tsx
'use client';
import {useState} from 'react';
import {XDSCalendar, type ISODateString} from '@xds/core/Calendar';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function CalendarSingle() {
  const [value, setValue] = useState<ISODateString>('2026-01-15');
  return (
    <XDSStack direction="vertical" gap={4} hAlign="center">
      <XDSText type="supporting" color="secondary">
        {value ? `Selected: ${value}` : 'Pick a date'}
      </XDSText>
      <XDSCalendar
        mode="single"
        value={value}
        onChange={val => setValue(val)}
        focusDate="2026-01-01"
      />
    </XDSStack>
  );
}

Calendar — Two MonthsTwo months side by side for selecting ranges that span a month boundary. Use in booking or travel UIs where check-in and check-out often fall in different months.

tsx
'use client';
import {useState} from 'react';
import {XDSCalendar, type DateRange} from '@xds/core/Calendar';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function CalendarTwoMonths() {
  const [value, setValue] = useState<DateRange>({
    start: '2026-01-25',
    end: '2026-02-05',
  });
  return (
    <XDSStack direction="vertical" gap={4} hAlign="center">
      <XDSText type="supporting" color="secondary">
        {value.start && value.end
          ? `${value.start} → ${value.end}`
          : 'Pick a date range'}
      </XDSText>
      <XDSCalendar
        mode="range"
        numberOfMonths={2}
        value={value}
        onChange={range => setValue(range)}
        focusDate="2026-01-01"
      />
    </XDSStack>
  );
}

Showcase source

tsx
'use client';
import {useState} from 'react';
import {XDSCalendar} from '@xds/core/Calendar';
import type {ISODateString} from '@xds/core/Calendar';
export default function CalendarShowcase() {
  const [value, setValue] = useState<ISODateString | undefined>('2026-04-15');
  return <XDSCalendar mode="single" value={value} onChange={setValue} />;
}

Usage

Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.

import {XDSCalendar} from '@xds/core/Calendar'

Best practices

Guidance	Practices
Do	Set min and max dates to limit selection to a valid window — like only future dates for a booking or the current quarter for a report.
Do	Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.
Do	Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.
Do	Show two months side by side when the user frequently selects dates that span a month boundary.
Don't	Use a calendar for dates far in the past or future like a birth date — a text input is faster for open-ended entry.
Don't	Disable large blocks of dates without context — the user should understand why dates are unavailable.

tsx

'use client'; import {useState} from 'react'; import {XDSCalendar, type ISODateString} from '@xds/core/Calendar'; import {XDSStack} from '@xds/core/Layout'; import {XDSText} from '@xds/core/Text'; const isWeekday = (date: Date) => { const day = date.getDay(); return day !== 0 && day !== 6; }; export default function CalendarConstraints() { const [value, setValue] = useState<ISODateString | undefined>(undefined); return ( <XDSStack direction="vertical" gap={4} hAlign="center"> <XDSText type="supporting" color="secondary"> Jan 10 – Mar 20, weekdays only </XDSText> <XDSCalendar mode="single" min={'2026-01-10' as ISODateString} max={'2026-03-20' as ISODateString} dateConstraints={[isWeekday]} value={value} onChange={val => setValue(val)} focusDate={'2026-01-01' as ISODateString} /> </XDSStack> ); }

tsx

'use client'; import {useState} from 'react'; import {XDSCalendar, type DateRange} from '@xds/core/Calendar'; import {XDSStack} from '@xds/core/Layout'; import {XDSText} from '@xds/core/Text'; export default function CalendarRangeWithValue() { const [value, setValue] = useState<DateRange>({ start: '2026-01-10', end: '2026-01-20', }); return ( <XDSStack direction="vertical" gap={4} hAlign="center"> <XDSText type="supporting" color="secondary"> {value.start && value.end ? `${value.start} → ${value.end}` : 'Pick a start and end date'} </XDSText> <XDSCalendar mode="range" value={value} onChange={range => setValue(range)} focusDate="2026-01-01" /> </XDSStack> ); }

tsx

'use client'; import {useState} from 'react'; import {XDSCalendar, type ISODateString} from '@xds/core/Calendar'; import {XDSStack} from '@xds/core/Layout'; import {XDSText} from '@xds/core/Text'; export default function CalendarSingle() { const [value, setValue] = useState<ISODateString>('2026-01-15'); return ( <XDSStack direction="vertical" gap={4} hAlign="center"> <XDSText type="supporting" color="secondary"> {value ? `Selected: ${value}` : 'Pick a date'} </XDSText> <XDSCalendar mode="single" value={value} onChange={val => setValue(val)} focusDate="2026-01-01" /> </XDSStack> ); }

tsx

'use client'; import {useState} from 'react'; import {XDSCalendar, type DateRange} from '@xds/core/Calendar'; import {XDSStack} from '@xds/core/Layout'; import {XDSText} from '@xds/core/Text'; export default function CalendarTwoMonths() { const [value, setValue] = useState<DateRange>({ start: '2026-01-25', end: '2026-02-05', }); return ( <XDSStack direction="vertical" gap={4} hAlign="center"> <XDSText type="supporting" color="secondary"> {value.start && value.end ? `${value.start} → ${value.end}` : 'Pick a date range'} </XDSText> <XDSCalendar mode="range" numberOfMonths={2} value={value} onChange={range => setValue(range)} focusDate="2026-01-01" /> </XDSStack> ); }

tsx

'use client'; import {useState} from 'react'; import {XDSCalendar} from '@xds/core/Calendar'; import type {ISODateString} from '@xds/core/Calendar'; export default function CalendarShowcase() { const [value, setValue] = useState<ISODateString | undefined>('2026-04-15'); return <XDSCalendar mode="single" value={value} onChange={setValue} />; }