DatePicker

A cross-platform date picker with an input field that opens a single- or dual-month calendar dropdown for date or range selection.

Installation

npm install @xsolla/xui-date-picker

Imports

import {
  DatePicker,
  Calendar,
  DualCalendar,
  CalendarHeader,
  CalendarGrid,
  CalendarChips,
  formatDate,
} from '@xsolla/xui-date-picker';
import type {
  DatePickerProps,
  DateRangeType,
  CalendarProps,
  DualCalendarProps,
  CalendarChipOption,
  CalendarChipsProps,
  CalendarGridProps,
  CalendarHeaderProps,
  CalendarLocaleType,
} from '@xsolla/xui-date-picker';

Calendar, DualCalendar and friends are re-exported from @xsolla/xui-calendar. For standalone calendar usage, depend on @xsolla/xui-calendar directly.

Quick start

const [date, setDate] = useState<Date | null>(null);

<DatePicker
  selectedDate={date}
  onChange={(d) => setDate(d as Date | null)}
  placeholder="Select a date"
/>;

API Reference

<DatePicker>

| Prop | Type | Default | Description | | --- | --- | --- | --- | | variant | 'single' \| 'dual' | 'single' | Single-month or dual-month calendar; 'dual' forces range mode. | | selectedDate | Date \| null | — | Selected date for single mode. | | startDate | Date \| null | — | Range start date. | | endDate | Date \| null | — | Range end date. | | selectsRange | boolean | false | Enable range selection. | | onChange | (date: Date \| DateRangeType) => void | — | Fired when the date or range changes. | | placeholder | string | 'MM/DD/YYYY' | Placeholder for the input. | | size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | Input size. | | disabled | boolean | false | Disable the input. | | backgroundColor | string | — | Custom background colour for the input. | | dropdownPosition | 'left' \| 'right' | 'left' | Align the calendar dropdown to the left or right edge of the input. | | locale | CalendarLocaleType | 'enUS' | date-fns locale identifier. | | firstDayOfWeek | number | — | First day of the week (0 = Sunday … 6 = Saturday). | | initialMonth | Date | — | Month shown on first render. | | month | Date | — | Controlled month. | | minDate | Date \| null | — | Minimum selectable date. | | maxDate | Date \| null | — | Maximum selectable date. | | chips | CalendarChipOption[] | — | Preset range chips above the calendar. | | activeChip | string \| null | — | Currently active chip value. | | onChipSelect | (value: string \| null) => void | — | Fired when a chip is selected. | | topContent | (api: { close: () => void }) => ReactNode | — | Custom content above the calendar. | | bottomContent | (api: { close: () => void }) => ReactNode | — | Custom content below the calendar. | | contextMenuMaxHeight | number | — | Max height for the month/year context menus. | | testID | string | — | Test identifier. |

DatePicker extends CalendarProps (excluding onChange).

Inherits ThemeOverrideProps (themeMode, themeProductContext).

<Calendar>

Re-exported from @xsolla/xui-calendar. Standalone single-month calendar.

<DualCalendar>

Re-exported from @xsolla/xui-calendar. Two-month calendar for range selection.

<CalendarHeader>

Re-exported from @xsolla/xui-calendar. Month/year header with navigation controls.

<CalendarGrid>

Re-exported from @xsolla/xui-calendar. Day grid; takes currentMonth and selection props.

<CalendarChips>

Re-exported from @xsolla/xui-calendar. Preset chips bar (e.g. "Last 7 days", "This month").

Utilities

| Export | Type | Description | | --- | --- | --- | | formatDate | (date: Date, formatStr: string, locale?: CalendarLocaleType) => string | Format a date with a date-fns locale identifier. |

Types

type DateRangeType = [Date | null, Date | null];

Examples

Range selection

const [start, setStart] = useState<Date | null>(null);
const [end, setEnd] = useState<Date | null>(null);

<DatePicker
  selectsRange
  startDate={start}
  endDate={end}
  onChange={(range) => {
    const [s, e] = range as DateRangeType;
    setStart(s);
    setEnd(e);
  }}
/>;

Dual calendar

const [start, setStart] = useState<Date | null>(null);
const [end, setEnd] = useState<Date | null>(null);

<DatePicker
  variant="dual"
  dropdownPosition="right"
  startDate={start}
  endDate={end}
  onChange={(range) => {
    const [s, e] = range as DateRangeType;
    setStart(s);
    setEnd(e);
  }}
/>;

Preset chips

const chips: CalendarChipOption[] = [
  { label: 'Today', value: 'today', days: 0 },
  { label: 'Last 7 days', value: 'last7', days: 7 },
  { label: 'Last 30 days', value: 'last30', days: 30 },
];

const [activeChip, setActiveChip] = useState<string | null>(null);
const [date, setDate] = useState<Date | null>(null);

<DatePicker
  chips={chips}
  activeChip={activeChip}
  onChipSelect={setActiveChip}
  selectedDate={date}
  onChange={(d) => setDate(d as Date | null)}
/>;

Sizes

<DatePicker size="xs" placeholder="Extra small" />
<DatePicker size="sm" placeholder="Small" />
<DatePicker size="md" placeholder="Medium" />
<DatePicker size="lg" placeholder="Large" />
<DatePicker size="xl" placeholder="Extra large" />

Min/max date

const [date, setDate] = useState<Date | null>(null);

<DatePicker
  selectedDate={date}
  onChange={(d) => setDate(d as Date | null)}
  minDate={new Date(2024, 0, 1)}
  maxDate={new Date(2024, 11, 31)}
/>;

Accessibility

• The input is keyboard accessible; the calendar opens on focus.
• Calendar dates are navigable via keyboard; selected dates are announced to screen readers.
• Focus is restored to the input when the calendar closes.
• Dates outside minDate/maxDate are disabled.