Calendar

A cross-platform React calendar component supporting single date selection, date range selection, preset date chips, and a dual (side-by-side) calendar layout.

Installation

npm install @xsolla/xui-calendar
# or
yarn add @xsolla/xui-calendar

Demo

Single Date Selection

import * as React from 'react';
import { Calendar } from '@xsolla/xui-calendar';

export default function SingleDate() {
  const [date, setDate] = React.useState<Date | null>(null);

  return (
    <Calendar
      selectedDate={date}
      onChange={(newDate) => setDate(newDate as Date)}
    />
  );
}

Date Range Selection

import * as React from 'react';
import { Calendar } from '@xsolla/xui-calendar';

export default function DateRange() {
  const [startDate, setStartDate] = React.useState<Date | null>(null);
  const [endDate, setEndDate] = React.useState<Date | null>(null);

  return (
    <Calendar
      selectsRange
      startDate={startDate}
      endDate={endDate}
      onChange={(range) => {
        const [start, end] = range as [Date | null, Date | null];
        setStartDate(start);
        setEndDate(end);
      }}
    />
  );
}

With Preset Chips

import * as React from 'react';
import { Calendar } from '@xsolla/xui-calendar';

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

export default function WithChips() {
  const [date, setDate] = React.useState<Date | null>(null);
  const [activeChip, setActiveChip] = React.useState<string | null>('last30');

  return (
    <Calendar
      selectedDate={date}
      onChange={(newDate) => setDate(newDate as Date)}
      chips={chips}
      activeChip={activeChip}
      onChipSelect={setActiveChip}
    />
  );
}

Dual Calendar (Side-by-Side)

import * as React from 'react';
import { DualCalendar } from '@xsolla/xui-calendar';

export default function DualRange() {
  const [startDate, setStartDate] = React.useState<Date | null>(null);
  const [endDate, setEndDate] = React.useState<Date | null>(null);

  return (
    <DualCalendar
      startDate={startDate}
      endDate={endDate}
      onChange={(dates) => {
        const [start, end] = dates;
        setStartDate(start);
        setEndDate(end);
      }}
    />
  );
}

Anatomy

+---------------------------------------+
|  [Custom top-content]                 |  <- topContent slot
|  [Today] [Last 7d] [Last 30d] ...    |  <- CalendarChips
|  <- [Month ▾] [Year ▾] ->            |  <- CalendarHeader
|  SU  MO  TU  WE  TH  FR  SA         |  <- CalendarGrid weekday row
|  29  30  31   1   2   3   4          |
|   5   6   7   8   9  10  11          |
|  12  13  14 [15]  16  17  18         |  <- [15] = today/selected
|  23  20  21  22  23  24  25          |
|  26  27  28  29  30   1   2          |
|  [Custom bottom-content]             |  <- bottomContent slot
+---------------------------------------+

API Reference

Calendar

| Prop | Type | Default | Description | | :--- | :--- | :------ | :---------- | | selectedDate | Date \| null | - | Selected date for single mode. | | startDate | Date \| null | - | Start date for range mode. | | endDate | Date \| null | - | End date for range mode. | | selectsRange | boolean | false | Enable date range selection. | | onChange | (date: Date \| [Date, Date]) => void | - | Date change callback. | | locale | string | "enUS" | Date-fns locale identifier. | | firstDayOfWeek | number | 0 | First day of week (0=Sun, 6=Sat). | | initialMonth | Date | - | Initial month to display. | | month | Date | - | Controlled month to display. | | minDate | Date \| null | - | Minimum selectable date. | | maxDate | Date \| null | - | Maximum selectable date. | | chips | CalendarChipOption[] | - | Preset date range chips. | | activeChip | string \| null | - | Currently active chip value. | | onChipSelect | (value: string) => void | - | Chip selection callback. | | topContent | ({ close }) => ReactNode | - | Custom content above chips. | | bottomContent | ({ close }) => ReactNode | - | Custom content below grid. | | contextMenuMaxHeight | number | - | Max height for month/year dropdowns. | | testID | string | - | Test identifier. |

DualCalendar

| Prop | Type | Default | Description | | :--- | :--- | :------ | :---------- | | startDate | Date \| null | - | Start date of selected range. | | endDate | Date \| null | - | End date of selected range. | | onChange | (dates: [Date, Date]) => void | - | Range change callback. | | locale | string | "enUS" | Date-fns locale identifier. | | firstDayOfWeek | number | 0 | First day of week (0=Sun, 6=Sat). | | initialMonth | Date | - | Initial month for left calendar. | | month | Date | - | Controlled month for left calendar. | | minDate | Date \| null | - | Minimum selectable date. | | maxDate | Date \| null | - | Maximum selectable date. | | chips | CalendarChipOption[] | - | Shared preset date range chips. | | activeChip | string \| null | - | Currently active chip value. | | onChipSelect | (value: string) => void | - | Chip selection callback. | | topContent | ({ close }) => ReactNode | - | Custom content above chips. | | bottomContent | ({ close }) => ReactNode | - | Custom content below grids. | | contextMenuMaxHeight | number | - | Max height for month/year dropdowns. | | testID | string | - | Test identifier. |

CalendarChips

| Prop | Type | Default | Description | | :--- | :--- | :------ | :---------- | | chips | CalendarChipOption[] | required | Array of chip options. | | activeChip | string \| null | - | Currently active chip value. | | onChipSelect | (value: string) => void | - | Chip selection callback. | | testID | string | - | Test identifier. |

CalendarChipOption

interface CalendarChipOption {
  label: string;
  value: string;
}

CalendarGrid

| Prop | Type | Default | Description | | :--- | :--- | :------ | :---------- | | currentMonth | Date | required | The month to render. | | locale | string | "enUS" | Date-fns locale identifier. | | firstDayOfWeek | number | 0 | First day of week. | | selectsRange | boolean | false | Enable range mode. | | minDate | Date \| null | - | Minimum selectable date. | | maxDate | Date \| null | - | Maximum selectable date. | | startDate | Date \| null | - | Range start date. | | endDate | Date \| null | - | Range end date. | | selectedDate | Date \| null | - | Selected date (single mode). | | selectingRange | Date \| null | - | Intermediate range selection. | | onDayPress | (date: Date) => void | - | Day press callback. | | testID | string | - | Test identifier. |

Platform Support

This package works on both web and React Native. All components use cross-platform primitives (Box, Text) and avoid DOM-specific APIs.

Accessibility

• Navigation buttons have aria-labels ("Previous month", "Next month")
• Month and year selectors are accessible via Select component
• Day cells support keyboard navigation
• Chip selection follows radio-group pattern (single active item)