Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(DateRangePicker): add XDSDateRangePicker component (#184) (#2201)

Andrey Goderd257a13ea9af
diff --git a/apps/storybook/stories/DateRangePicker.stories.tsx b/apps/storybook/stories/DateRangePicker.stories.tsx
new file mode 100644
index 0000000000..282ac0ba50
--- /dev/null
+++ b/apps/storybook/stories/DateRangePicker.stories.tsx
@@ -0,0 +1,289 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {useState} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSDateRangePicker} from '@xds/core/DateRangePicker';
+import type {XDSDateRange} from '@xds/core/DateRangePicker';
+import type {ISODateString} from '@xds/core/Calendar';
+
+function daysAgo(n: number): ISODateString {
+ const d = new Date();
+ d.setDate(d.getDate() - n);
+ return d.toISOString().slice(0, 10) as ISODateString;
+}
+
+function today(): ISODateString {
+ return new Date().toISOString().slice(0, 10) as ISODateString;
+}
+
+function startOfMonth(): ISODateString {
+ const d = new Date();
+ d.setDate(1);
+ return d.toISOString().slice(0, 10) as ISODateString;
+}
+
+const defaultPresets = [
+ {label: 'Last 1 day', getRange: () => ({start: daysAgo(1), end: today()})},
+ {label: 'Last 3 days', getRange: () => ({start: daysAgo(3), end: today()})},
+ {label: 'Last 7 days', getRange: () => ({start: daysAgo(7), end: today()})},
+ {
+ label: 'Last 14 days',
+ getRange: () => ({start: daysAgo(14), end: today()}),
+ },
+ {
+ label: 'Last 30 days',
+ getRange: () => ({start: daysAgo(30), end: today()}),
+ },
+ {
+ label: 'This month',
+ getRange: () => ({start: startOfMonth(), end: today()}),
+ },
+];
+
+const meta: Meta<typeof XDSDateRangePicker> = {
+ title: 'Core/Inputs/DateRangePicker',
+ component: XDSDateRangePicker,
+ tags: ['autodocs'],
+ argTypes: {
+ label: {control: 'text', description: 'Label text (required)'},
+ isLabelHidden: {
+ control: 'boolean',
+ description: 'Visually hide the label',
+ },
+ placeholder: {control: 'text', description: 'Placeholder text'},
+ description: {control: 'text', description: 'Description text'},
+ isOptional: {control: 'boolean', description: 'Show optional indicator'},
+ isRequired: {control: 'boolean', description: 'Mark as required'},
+ isDisabled: {control: 'boolean', description: 'Disable the picker'},
+ size: {
+ control: 'radio',
+ options: ['sm', 'md'],
+ description: 'Trigger size',
+ },
+ hasClear: {control: 'boolean', description: 'Show clear button'},
+ numberOfMonths: {
+ control: 'radio',
+ options: [1, 2],
+ description: 'Calendar months',
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSDateRangePicker>;
+
+export const Default: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSDateRange | null>(null);
+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Date range',
+ },
+};
+
+export const WithValue: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSDateRange | null>({
+ start: '2026-03-10' as ISODateString,
+ end: '2026-03-20' as ISODateString,
+ });
+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Report period',
+ },
+};
+
+export const WithPresets: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSDateRange | null>(null);
+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Date range',
+ presets: defaultPresets,
+ },
+};
+
+export const WithPresetsAndValue: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSDateRange | null>({
+ start: daysAgo(7),
+ end: today(),
+ });
+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Analytics period',
+ presets: defaultPresets,
+ },
+};
+
+export const WithDescription: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSDateRange | null>(null);
+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Coverage period',
+ description: 'Select the start and end dates for the report',
+ },
+};
+
+export const WithMinMax: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSDateRange | null>(null);
+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Booking dates',
+ min: '2026-03-01' as ISODateString,
+ max: '2026-06-30' as ISODateString,
+ description: 'Available: Mar 1 – Jun 30, 2026',
+ },
+};
+
+export const Optional: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSDateRange | null>(null);
+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Filter by date',
+ isOptional: true,
+ },
+};
+
+export const Required: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSDateRange | null>(null);
+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Coverage period',
+ isRequired: true,
+ },
+};
+
+export const Disabled: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSDateRange | null>({
+ start: '2026-03-10' as ISODateString,
+ end: '2026-03-20' as ISODateString,
+ });
+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Locked range',
+ isDisabled: true,
+ },
+};
+
+export const SmallSize: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSDateRange | null>(null);
+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Date range',
+ size: 'sm',
+ },
+};
+
+export const SingleMonth: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSDateRange | null>(null);
+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Date range',
+ numberOfMonths: 1,
+ },
+};
+
+export const WithErrorStatus: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSDateRange | null>(null);
+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Date range',
+ status: {type: 'error', message: 'Please select a date range'},
+ },
+};
+
+export const WithWarningStatus: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSDateRange | null>({
+ start: '2026-03-01' as ISODateString,
+ end: '2026-06-30' as ISODateString,
+ });
+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Date range',
+ status: {type: 'warning', message: 'Range exceeds 90 days'},
+ },
+};
+
+export const NoClear: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSDateRange | null>({
+ start: '2026-03-10' as ISODateString,
+ end: '2026-03-20' as ISODateString,
+ });
+ return <XDSDateRangePicker {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Required range',
+ hasClear: false,
+ },
+};
+
+export const AllVariations: Story = {
+ render: () => {
+ const [v1, setV1] = useState<XDSDateRange | null>(null);
+ const [v2, setV2] = useState<XDSDateRange | null>({
+ start: '2026-03-10' as ISODateString,
+ end: '2026-03-20' as ISODateString,
+ });
+ const [v3, setV3] = useState<XDSDateRange | null>(null);
+ const [v4, setV4] = useState<XDSDateRange | null>({
+ start: '2026-03-10' as ISODateString,
+ end: '2026-03-20' as ISODateString,
+ });
+ const [v5, setV5] = useState<XDSDateRange | null>(null);
+
+ return (
+ <div
+ style={{
+ display: 'flex',
+ flexDirection: 'column',
+ gap: '16px',
+ maxWidth: '340px',
+ }}>
+ <XDSDateRangePicker label="Default" value={v1} onChange={setV1} />
+ <XDSDateRangePicker label="With value" value={v2} onChange={setV2} />
+ <XDSDateRangePicker
+ label="With presets"
+ value={v3}
+ onChange={setV3}
+ presets={defaultPresets}
+ />
+ <XDSDateRangePicker
+ label="Disabled"
+ isDisabled
+ value={v4}
+ onChange={setV4}
+ />
+ <XDSDateRangePicker
+ label="With error"
+ value={v5}
+ onChange={setV5}
+ status={{type: 'error', message: 'Date range is required'}}
+ />
+ </div>
+ );
+ },
+};
diff --git a/packages/cli/templates/blocks/components/DateRangePicker/DateRangePickerShowcase.doc.mjs b/packages/cli/templates/blocks/components/DateRangePicker/DateRangePickerShowcase.doc.mjs
new file mode 100644
index 0000000000..5e58ef0529
--- /dev/null
+++ b/packages/cli/templates/blocks/components/DateRangePicker/DateRangePickerShowcase.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'DateRangePicker',
+ name: 'DateRangePicker',
+ description:
+ 'A date range picker with a button trigger and dual-month calendar popover with preset ranges.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 1,
+ componentsUsed: ['DateRangePicker', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/DateRangePicker/DateRangePickerShowcase.tsx b/packages/cli/templates/blocks/components/DateRangePicker/DateRangePickerShowcase.tsx
new file mode 100644
index 0000000000..99bc23d2a3
--- /dev/null
+++ b/packages/cli/templates/blocks/components/DateRangePicker/DateRangePickerShowcase.tsx
@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {XDSDateRangePicker} from '@xds/core/DateRangePicker';
+import type {XDSDateRange} from '@xds/core/DateRangePicker';
+import type {ISODateString} from '@xds/core/Calendar';
+import {XDSStack} from '@xds/core/Layout';
+
+function daysAgo(n: number): ISODateString {
+ const d = new Date();
+ d.setDate(d.getDate() - n);
+ return d.toISOString().slice(0, 10) as ISODateString;
+}
+
+function today(): ISODateString {
+ return new Date().toISOString().slice(0, 10) as ISODateString;
+}
+
+const presets = [
+ {label: 'Last 7 days', getRange: () => ({start: daysAgo(7), end: today()})},
+ {label: 'Last 30 days', getRange: () => ({start: daysAgo(30), end: today()})},
+];
+
+export default function DateRangePickerShowcase() {
+ const [range, setRange] = useState<XDSDateRange | null>(null);
+
+ return (
+ <XDSStack direction="vertical" width="100%" style={{maxWidth: 400}}>
+ <XDSDateRangePicker
+ label="Date range"
+ value={range}
+ onChange={setRange}
+ presets={presets}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/core/package.json b/packages/core/package.json
index d79d2c464c..7fdd2e588a 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -199,6 +199,12 @@
"import": "./dist/DateInput/index.mjs",
"require": "./dist/DateInput/index.js"
},
+ "./DateRangePicker": {
+ "source": "./src/DateRangePicker/index.ts",
+ "types": "./dist/DateRangePicker/index.d.ts",
+ "import": "./dist/DateRangePicker/index.mjs",
+ "require": "./dist/DateRangePicker/index.js"
+ },
"./DateTimePicker": {
"source": "./src/DateTimePicker/index.ts",
"types": "./dist/DateTimePicker/index.d.ts",
diff --git a/packages/core/src/DateRangePicker/DateRangePicker.doc.mjs b/packages/core/src/DateRangePicker/DateRangePicker.doc.mjs
new file mode 100644
index 0000000000..662d359528
--- /dev/null
+++ b/packages/core/src/DateRangePicker/DateRangePicker.doc.mjs
@@ -0,0 +1,90 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'DateRangePicker',
+ keywords: ["daterangepicker","daterange","range","calendar","filter","analytics","period","schedule"],
+ props: [
+ { name: 'label', type: 'string', description: 'Label text.', required: true },
+ { name: 'isLabelHidden', type: 'boolean', description: 'Visually hide the label.', default: 'false' },
+ { name: 'description', type: 'string', description: 'Helper text displayed below the label.' },
+ { name: 'isOptional', type: 'boolean', description: 'Show an "(optional)" indicator.', default: 'false' },
+ { name: 'isRequired', type: 'boolean', description: 'Mark the field as required.', default: 'false' },
+ { name: 'isDisabled', type: 'boolean', description: 'Disable the trigger and picker.', default: 'false' },
+ { name: 'value', type: 'XDSDateRange | null', description: 'Selected date range ({start, end} in ISO format), or null.', required: true },
+ { name: 'onChange', type: '(value: XDSDateRange | null) => void', description: 'Callback when the range changes. Called with null on clear.', required: true },
+ { name: 'changeAction', type: '(value: XDSDateRange | null) => void | Promise<void>', description: 'Async action fired after onChange. Drives optimistic UI updates via useTransition.' },
+ { name: 'isLoading', type: 'boolean', description: 'Whether the input is in a loading state. Disables interaction and shows a spinner.', default: 'false' },
+ { name: 'min', type: 'ISODateString', description: 'Minimum selectable date.' },
+ { name: 'max', type: 'ISODateString', description: 'Maximum selectable date.' },
+ { name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: 'Custom constraint functions to disable specific dates.' },
+ { name: 'presets', type: 'Array<XDSDateRangePreset>', description: 'Preset ranges shown as quick-select options beside the calendar.' },
+ { name: 'hasClear', type: 'boolean', description: 'Shows a clear button when a range is selected.', default: 'true' },
+ { name: 'placeholder', type: 'string', description: 'Placeholder text when no range is selected.', default: "'Select date range'" },
+ { name: 'size', type: "'sm' | 'md'", description: 'Size of the trigger.', default: "'md'" },
+ { name: 'status', type: 'XDSInputStatus', description: 'Status indicator for error, warning, or success states.' },
+ { name: 'labelTooltip', type: 'string', description: 'Tooltip text via info icon at label end.' },
+ { name: 'numberOfMonths', type: '1 | 2', description: 'Number of months in the calendar.', default: '2' },
+ { name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization.' },
+ ],
+ theming: {
+ targets: [
+ { className: 'xds-date-range-picker', visualProps: ['size', 'status'] },
+ ],
+ },
+ usage: {
+ description: 'DateRangePicker lets users select a start and end date from a dual-month calendar popover. Use it for filtering data by time period, report generation, analytics dashboards, and booking flows.',
+ bestPractices: [
+ { guidance: true, description: 'Use presets for common ranges like "Last 7 days" to speed up selection.' },
+ { guidance: true, description: 'Use min/max to constrain selectable dates to valid ranges.' },
+ { guidance: true, description: 'Keep hasClear enabled (default) so users can reset the filter.' },
+ { guidance: true, description: 'Provide clear labels and descriptions so users understand what the range controls.' },
+ { guidance: false, description: 'Use DateRangePicker when only a single date is needed — use DateInput instead.' },
+ { guidance: false, description: 'Hide the label without surrounding context that makes the purpose obvious.' },
+ ],
+ anatomy: [
+ { name: 'Label', required: true, description: 'Text above the trigger describing what date range is expected.' },
+ { name: 'Trigger button', required: true, description: 'A button showing the formatted range or placeholder. Clicking opens the popover.' },
+ { name: 'Calendar icon', required: true, description: 'A trailing icon that also opens the popover.' },
+ { name: 'Calendar popover', required: true, description: 'A dual-month calendar grid with range selection and hover preview.' },
+ { name: 'Preset sidebar', required: false, description: 'A list of preset range options beside the calendar.' },
+ { name: 'Clear button', required: false, description: 'A × button that resets the range to null.' },
+ { name: 'Status message', required: false, description: 'An error, warning, or success message below the trigger.' },
+ ],
+ },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'date range picker with dual-month calendar popover and preset ranges',
+ usage: {
+ description: 'DateRangePicker lets users select start+end dates from a dual-month calendar. Use for filtering, reports, analytics, and booking.',
+ bestPractices: [
+ { guidance: true, description: 'Use presets for common ranges. Use min/max for constraints.' },
+ { guidance: true, description: 'Keep hasClear enabled. Provide clear labels.' },
+ { guidance: false, description: 'Use for single dates (use DateInput). Hide label without context.' },
+ ],
+ },
+ propDescriptions: {
+ label: 'label text',
+ isLabelHidden: 'visually hide label',
+ description: 'helper text below label',
+ isOptional: 'show "(optional)" indicator',
+ isRequired: 'mark field required',
+ isDisabled: 'disable trigger+picker',
+ value: 'selected range {start, end} or null',
+ onChange: 'callback on range change; null on clear',
+ min: 'min selectable date',
+ max: 'max selectable date',
+ dateConstraints: 'custom constraint fns to disable dates',
+ presets: 'preset ranges as quick-select options',
+ hasClear: 'clear button when range is set (default true)',
+ placeholder: 'placeholder when empty',
+ size: 'trigger size',
+ status: 'error/warning/success status',
+ labelTooltip: 'tooltip via info icon at label end',
+ numberOfMonths: 'months in calendar (default 2)',
+ xstyle: 'StyleX styles for layout',
+ },
+};
diff --git a/packages/core/src/DateRangePicker/XDSDateRangePicker.test.tsx b/packages/core/src/DateRangePicker/XDSDateRangePicker.test.tsx
new file mode 100644
index 0000000000..623ceba000
--- /dev/null
+++ b/packages/core/src/DateRangePicker/XDSDateRangePicker.test.tsx
@@ -0,0 +1,317 @@
+/**
+ * @file XDSDateRangePicker.test.tsx
+ * @input Uses vitest, @testing-library/react, XDSDateRangePicker component
+ * @output Unit tests for XDSDateRangePicker component behavior
+ * @position Testing; validates XDSDateRangePicker.tsx implementation
+ *
+ * SYNC: When XDSDateRangePicker.tsx changes, update tests to match new behavior
+ */
+
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {XDSDateRangePicker} from './XDSDateRangePicker';
+import type {XDSDateRange} from './XDSDateRangePicker';
+import type {ISODateString} from '../Calendar';
+
+describe('XDSDateRangePicker', () => {
+ it('renders with label', () => {
+ render(
+ <XDSDateRangePicker
+ label="Date range"
+ value={null}
+ onChange={() => {}}
+ />,
+ );
+ expect(screen.getByText('Date range')).toBeInTheDocument();
+ });
+
+ it('renders placeholder when value is null', () => {
+ render(
+ <XDSDateRangePicker label="Range" value={null} onChange={() => {}} />,
+ );
+ expect(screen.getByText('Select date range')).toBeInTheDocument();
+ });
+
+ it('renders custom placeholder', () => {
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ value={null}
+ onChange={() => {}}
+ placeholder="Pick dates"
+ />,
+ );
+ expect(screen.getByText('Pick dates')).toBeInTheDocument();
+ });
+
+ it('displays formatted range when value is set', () => {
+ const range: XDSDateRange = {
+ start: '2026-03-15' as ISODateString,
+ end: '2026-03-22' as ISODateString,
+ };
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ value={range}
+ onChange={() => {}}
+ hasClear={false}
+ />,
+ );
+ const trigger = screen.getByRole('button', {name: /Range:/});
+ expect(trigger.textContent).toMatch(/Mar/);
+ expect(trigger.textContent).toMatch(/15/);
+ expect(trigger.textContent).toMatch(/22/);
+ });
+
+ it('forwards ref to trigger button', () => {
+ const ref = vi.fn();
+ render(
+ <XDSDateRangePicker
+ ref={ref}
+ label="Range"
+ value={null}
+ onChange={() => {}}
+ />,
+ );
+ expect(ref).toHaveBeenCalledWith(expect.any(HTMLButtonElement));
+ });
+
+ it('visually hides label when isLabelHidden is true', () => {
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ isLabelHidden
+ value={null}
+ onChange={() => {}}
+ />,
+ );
+ expect(screen.getByText('Range')).toBeInTheDocument();
+ });
+
+ it('sets aria-required when isRequired is true', () => {
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ isRequired
+ value={null}
+ onChange={() => {}}
+ />,
+ );
+ const trigger = screen.getByRole('button', {name: /Range/});
+ expect(trigger).toHaveAttribute('aria-required', 'true');
+ });
+
+ it('does not set aria-required when isRequired is false', () => {
+ render(
+ <XDSDateRangePicker label="Range" value={null} onChange={() => {}} />,
+ );
+ const trigger = screen.getByRole('button', {name: /Range/});
+ expect(trigger).not.toHaveAttribute('aria-required');
+ });
+
+ it('disables trigger when isDisabled is true', () => {
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ isDisabled
+ value={null}
+ onChange={() => {}}
+ />,
+ );
+ const trigger = screen.getByRole('button', {name: /Range/});
+ expect(trigger).toBeDisabled();
+ });
+
+ it('is not disabled by default', () => {
+ render(
+ <XDSDateRangePicker label="Range" value={null} onChange={() => {}} />,
+ );
+ const trigger = screen.getByRole('button', {name: /Range/});
+ expect(trigger).not.toBeDisabled();
+ });
+
+ it('trigger has aria-haspopup="dialog"', () => {
+ render(
+ <XDSDateRangePicker label="Range" value={null} onChange={() => {}} />,
+ );
+ const trigger = screen.getByRole('button', {name: /Range/});
+ expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+ });
+
+ it('trigger has aria-expanded=false by default', () => {
+ render(
+ <XDSDateRangePicker label="Range" value={null} onChange={() => {}} />,
+ );
+ const trigger = screen.getByRole('button', {name: /Range/});
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('renders status icon for error status', () => {
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ value={null}
+ onChange={() => {}}
+ status={{type: 'error', message: 'Required'}}
+ />,
+ );
+ const trigger = screen.getByRole('button', {name: /Range/});
+ expect(trigger).toHaveAttribute('aria-invalid', 'true');
+ });
+
+ it('does not set aria-invalid for warning status', () => {
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ value={null}
+ onChange={() => {}}
+ status={{type: 'warning', message: 'Watch out'}}
+ />,
+ );
+ const trigger = screen.getByRole('button', {name: /Range/});
+ expect(trigger).not.toHaveAttribute('aria-invalid');
+ });
+
+ it('renders description', () => {
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ description="Pick a date range"
+ value={null}
+ onChange={() => {}}
+ />,
+ );
+ expect(screen.getByText('Pick a date range')).toBeInTheDocument();
+ });
+
+ it('links status message via aria-describedby', () => {
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ value={null}
+ onChange={() => {}}
+ status={{type: 'error', message: 'Please select dates'}}
+ />,
+ );
+ const trigger = screen.getByRole('button', {name: /Range/});
+ const describedBy = trigger.getAttribute('aria-describedby')!;
+ const ids = describedBy.split(' ');
+ const found = ids.some(id => {
+ const el = document.getElementById(id);
+ return el?.textContent?.includes('Please select dates');
+ });
+ expect(found).toBe(true);
+ });
+
+ it('calendar icon button is present', () => {
+ render(
+ <XDSDateRangePicker label="Range" value={null} onChange={() => {}} />,
+ );
+ expect(
+ screen.getByRole('button', {name: 'Open calendar'}),
+ ).toBeInTheDocument();
+ });
+
+ it('calendar icon button is disabled when isDisabled', () => {
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ isDisabled
+ value={null}
+ onChange={() => {}}
+ />,
+ );
+ expect(screen.getByRole('button', {name: 'Open calendar'})).toBeDisabled();
+ });
+
+ describe('hasClear', () => {
+ it('shows clear button when hasClear is true and value exists', () => {
+ const range: XDSDateRange = {
+ start: '2026-03-15' as ISODateString,
+ end: '2026-03-22' as ISODateString,
+ };
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ value={range}
+ onChange={() => {}}
+ hasClear
+ />,
+ );
+ expect(
+ screen.getByRole('button', {name: 'Clear Range'}),
+ ).toBeInTheDocument();
+ });
+
+ it('does not show clear button when value is null', () => {
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ value={null}
+ onChange={() => {}}
+ hasClear
+ />,
+ );
+ expect(
+ screen.queryByRole('button', {name: 'Clear Range'}),
+ ).not.toBeInTheDocument();
+ });
+
+ it('does not show clear button when hasClear is false', () => {
+ const range: XDSDateRange = {
+ start: '2026-03-15' as ISODateString,
+ end: '2026-03-22' as ISODateString,
+ };
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ value={range}
+ onChange={() => {}}
+ hasClear={false}
+ />,
+ );
+ expect(
+ screen.queryByRole('button', {name: 'Clear Range'}),
+ ).not.toBeInTheDocument();
+ });
+
+ it('does not show clear button when disabled', () => {
+ const range: XDSDateRange = {
+ start: '2026-03-15' as ISODateString,
+ end: '2026-03-22' as ISODateString,
+ };
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ value={range}
+ onChange={() => {}}
+ hasClear
+ isDisabled
+ />,
+ );
+ expect(
+ screen.queryByRole('button', {name: 'Clear Range'}),
+ ).not.toBeInTheDocument();
+ });
+
+ it('calls onChange with null when clear is clicked', () => {
+ const onChange = vi.fn();
+ const range: XDSDateRange = {
+ start: '2026-03-15' as ISODateString,
+ end: '2026-03-22' as ISODateString,
+ };
+ render(
+ <XDSDateRangePicker
+ label="Range"
+ value={range}
+ onChange={onChange}
+ hasClear
+ />,
+ );
+ fireEvent.click(screen.getByRole('button', {name: 'Clear Range'}));
+ expect(onChange).toHaveBeenCalledWith(null);
+ });
+ });
+});
diff --git a/packages/core/src/DateRangePicker/XDSDateRangePicker.tsx b/packages/core/src/DateRangePicker/XDSDateRangePicker.tsx
new file mode 100644
index 0000000000..96c0a8ebd4
--- /dev/null
+++ b/packages/core/src/DateRangePicker/XDSDateRangePicker.tsx
@@ -0,0 +1,596 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file XDSDateRangePicker.tsx
+ * @input Uses React, XDSField, XDSCalendar (range mode), useXDSPopover
+ * @output Exports XDSDateRangePicker component, XDSDateRangePickerProps
+ * @position Core implementation; consumed by index.ts, tested by XDSDateRangePicker.test.tsx
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/DateRangePicker/DateRangePicker.doc.mjs (props table, features, implementation notes)
+ * - /packages/core/src/DateRangePicker/XDSDateRangePicker.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/DateRangePicker/index.ts (exports if types change)
+ * - /apps/storybook/stories/DateRangePicker.stories.tsx (storybook stories)
+ * - /packages/cli/templates/blocks/components/DateRangePicker/ (showcase blocks)
+ */
+
+import {useId, useCallback, useMemo, useOptimistic, useTransition} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {XDSIconName} from '../Icon';
+import {
+ colorVars,
+ sizeVars,
+ radiusVars,
+ spacingVars,
+ typographyVars,
+ typeScaleVars,
+ borderVars,
+} from '../theme/tokens.stylex';
+import {
+ XDSField,
+ type XDSInputStatus,
+ type XDSInputStatusType,
+ inputWrapperStyles,
+ inputStatusBorderStyles,
+ inputStatusHoverShadowStyles,
+ inputStatusFocusWithinStyles,
+} from '../Field';
+import {XDSIcon} from '../Icon';
+import {XDSSpinner} from '../Spinner';
+import {XDSCalendar, type ISODateString, type DateRange} from '../Calendar';
+import {useXDSPopover} from '../Popover';
+import {xdsClassName, mergeProps} from '../utils';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import type {XDSBaseProps} from '../XDSBaseProps';
+
+export type {DateRange as XDSDateRange} from '../Calendar';
+
+export interface XDSDateRangePreset {
+ label: string;
+ getRange: () => DateRange;
+}
+
+export type XDSDateRangePickerSize = 'sm' | 'md';
+
+export type {
+ XDSInputStatus as XDSDateRangePickerStatus,
+ XDSInputStatusType as XDSDateRangePickerStatusType,
+} from '../Field';
+
+const styles = stylex.create({
+ trigger: {
+ display: 'block',
+ flex: 1,
+ minWidth: 0,
+ borderWidth: 0,
+ borderStyle: 'none',
+ padding: 0,
+ fontFamily: typographyVars['--font-family-body'],
+ fontSize: {
+ default: typeScaleVars['--text-body-size'],
+ '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+ },
+ lineHeight: typeScaleVars['--text-body-leading'],
+ color: colorVars['--color-text-primary'],
+ backgroundColor: 'transparent',
+ outline: 'none',
+ cursor: 'pointer',
+ textAlign: 'start',
+ whiteSpace: 'nowrap',
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ },
+ triggerPlaceholder: {
+ color: colorVars['--color-text-secondary'],
+ },
+ triggerDisabled: {
+ cursor: 'not-allowed',
+ },
+ iconButton: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ padding: 0,
+ margin: 0,
+ borderWidth: 0,
+ borderStyle: 'none',
+ backgroundColor: 'transparent',
+ cursor: 'pointer',
+ borderRadius: radiusVars['--radius-element'],
+ outline: {
+ default: 'none',
+ ':focus-visible': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,
+ },
+ outlineOffset: 1,
+ },
+ iconButtonDisabled: {
+ cursor: 'not-allowed',
+ },
+ popoverLayout: {
+ display: 'flex',
+ },
+ presetSidebar: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-1'],
+ padding: spacingVars['--spacing-3'],
+ borderRightWidth: borderVars['--border-width'],
+ borderRightStyle: 'solid',
+ borderRightColor: colorVars['--color-border-emphasized'],
+ minWidth: 140,
+ },
+ presetButton: {
+ display: 'block',
+ width: '100%',
+ padding: `${spacingVars['--spacing-1']} ${spacingVars['--spacing-2']}`,
+ margin: 0,
+ borderWidth: 0,
+ borderStyle: 'none',
+ borderRadius: radiusVars['--radius-element'],
+ backgroundColor: {
+ default: 'transparent',
+ ':hover': {
+ '@media (hover: hover)': colorVars['--color-overlay-hover'],
+ },
+ },
+ fontFamily: typographyVars['--font-family-body'],
+ fontSize: typeScaleVars['--text-body-size'],
+ lineHeight: typeScaleVars['--text-body-leading'],
+ color: colorVars['--color-text-primary'],
+ cursor: 'pointer',
+ textAlign: 'start',
+ outline: {
+ default: 'none',
+ ':focus-visible': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,
+ },
+ },
+ presetButtonActive: {
+ backgroundColor: colorVars['--color-accent-muted'],
+ color: colorVars['--color-accent'],
+ },
+});
+
+const sizeStyles = stylex.create({
+ sm: {
+ height: sizeVars['--size-element-sm'],
+ minWidth: 180,
+ },
+ md: {
+ height: sizeVars['--size-element-md'],
+ minWidth: 180,
+ },
+});
+
+const shortDateFormatter = new Intl.DateTimeFormat(undefined, {
+ month: 'short',
+ day: 'numeric',
+});
+
+const shortDateWithYearFormatter = new Intl.DateTimeFormat(undefined, {
+ month: 'short',
+ day: 'numeric',
+ year: 'numeric',
+});
+
+function parseISO(iso: ISODateString): Date {
+ const [year, month, day] = iso.split('-').map(Number);
+ return new Date(year, month - 1, day);
+}
+
+function formatRangeDisplay(range: DateRange | null): string {
+ if (!range) return '';
+ const startDate = parseISO(range.start);
+ const endDate = parseISO(range.end);
+ const currentYear = new Date().getFullYear();
+ const sameYear =
+ startDate.getFullYear() === endDate.getFullYear() &&
+ startDate.getFullYear() === currentYear;
+
+ const fmt = sameYear ? shortDateFormatter : shortDateWithYearFormatter;
+ return `${fmt.format(startDate)} – ${fmt.format(endDate)}`;
+}
+
+function isRangeEqual(a: DateRange | null, b: DateRange | null): boolean {
+ if (a === b) return true;
+ if (!a || !b) return false;
+ return a.start === b.start && a.end === b.end;
+}
+
+export interface XDSDateRangePickerProps extends Omit<
+ XDSBaseProps,
+ 'onChange' | 'defaultValue'
+> {
+ /** Ref forwarded to the trigger button */
+ ref?: React.Ref<HTMLButtonElement>;
+
+ /**
+ * Label text for the input (required for accessibility).
+ */
+ label: string;
+
+ /**
+ * Whether to visually hide the label (still accessible to screen readers).
+ * @default false
+ */
+ isLabelHidden?: boolean;
+
+ /**
+ * Description text displayed between the label and input.
+ */
+ description?: string;
+
+ /**
+ * Whether the field is optional. Mutually exclusive with isRequired.
+ * @default false
+ */
+ isOptional?: boolean;
+
+ /**
+ * Whether the field is required. Mutually exclusive with isOptional.
+ * @default false
+ */
+ isRequired?: boolean;
+
+ /**
+ * Whether the input is disabled.
+ * @default false
+ */
+ isDisabled?: boolean;
+
+ /**
+ * The selected date range, or null if no range is selected.
+ */
+ value: DateRange | null;
+
+ /**
+ * Callback fired when the date range changes.
+ * Called with null when the range is cleared.
+ */
+ onChange: (value: DateRange | null) => void;
+
+ /**
+ * Async action on change. Fires after onChange.
+ */
+ changeAction?: (value: DateRange | null) => void | Promise<void>;
+
+ /**
+ * Whether the input is in a loading state.
+ * @default false
+ */
+ isLoading?: boolean;
+
+ /**
+ * Minimum selectable date in ISO format.
+ */
+ min?: ISODateString;
+
+ /**
+ * Maximum selectable date in ISO format.
+ */
+ max?: ISODateString;
+
+ /**
+ * Custom date constraint functions.
+ * A date is disabled if ANY function returns false.
+ */
+ dateConstraints?: ReadonlyArray<(date: Date) => boolean>;
+
+ /**
+ * Preset date ranges shown as quick-select options beside the calendar.
+ */
+ presets?: ReadonlyArray<XDSDateRangePreset>;
+
+ /**
+ * Whether to show a clear button when a range is selected.
+ * @default true
+ */
+ hasClear?: boolean;
+
+ /**
+ * Placeholder text shown when no range is selected.
+ * @default "Select date range"
+ */
+ placeholder?: string;
+
+ /**
+ * The size of the trigger.
+ * @default 'md'
+ */
+ size?: XDSDateRangePickerSize;
+
+ /**
+ * Status indicator for the input.
+ */
+ status?: XDSInputStatus;
+
+ /**
+ * Tooltip text to display in an info icon at the end of the label.
+ */
+ labelTooltip?: string;
+
+ /**
+ * Number of months to display in the calendar.
+ * @default 2
+ */
+ numberOfMonths?: 1 | 2;
+
+ /**
+ * Style overrides.
+ */
+ xstyle?: StyleXStyles;
+}
+
+/**
+ * A date range picker with a button trigger that opens a popover
+ * containing a dual-month calendar and optional preset ranges.
+ *
+ * @example
+ * ```
+ * <XDSDateRangePicker
+ * label="Date range"
+ * value={range}
+ * onChange={setRange}
+ * presets={[
+ * { label: "Last 7 days", getRange: () => ({start: "...", end: "..."}) },
+ * ]}
+ * />
+ * ```
+ */
+export function XDSDateRangePicker({
+ label,
+ isLabelHidden = false,
+ description,
+ isOptional = false,
+ isRequired = false,
+ isDisabled = false,
+ value,
+ onChange,
+ changeAction,
+ isLoading = false,
+ min,
+ max,
+ dateConstraints,
+ presets,
+ hasClear = true,
+ placeholder = 'Select date range',
+ size = 'md',
+ status,
+ labelTooltip,
+ numberOfMonths = 2,
+ xstyle,
+ className,
+ style,
+ ref,
+ ...rest
+}: XDSDateRangePickerProps) {
+ const id = useId();
+ const descriptionID = useId();
+ const statusMessageID = useId();
+
+ const [, startTransition] = useTransition();
+ const [optimisticValue, setOptimisticValue] = useOptimistic(value);
+ const isBusy = isLoading || optimisticValue !== value;
+ const isEffectivelyDisabled = isDisabled || isBusy;
+
+ const statusIconMap: Record<XDSInputStatusType, XDSIconName> = {
+ warning: 'warning',
+ error: 'error',
+ success: 'success',
+ };
+
+ const statusIconColorMap: Record<
+ XDSInputStatusType,
+ 'warning' | 'negative' | 'positive'
+ > = {
+ warning: 'warning',
+ error: 'negative',
+ success: 'positive',
+ };
+
+ const ariaDescribedBy =
+ [
+ description ? descriptionID : null,
+ status?.message ? statusMessageID : null,
+ ]
+ .filter(Boolean)
+ .join(' ') || undefined;
+
+ const displayValue = useMemo(
+ () => formatRangeDisplay(optimisticValue),
+ [optimisticValue],
+ );
+
+ const popover = useXDSPopover({
+ dialogLabel: 'Choose date range',
+ closeButtonLabel: 'Close calendar',
+ });
+
+ const fireChange = useCallback(
+ (newValue: DateRange | null) => {
+ if (isBusy) return;
+ onChange(newValue);
+ if (changeAction) {
+ startTransition(async () => {
+ setOptimisticValue(newValue);
+ await changeAction(newValue);
+ });
+ }
+ },
+ [isBusy, onChange, changeAction, startTransition, setOptimisticValue],
+ );
+
+ const handleToggle = useCallback(() => {
+ if (!isEffectivelyDisabled) {
+ if (popover.isOpen) {
+ popover.hide();
+ } else {
+ popover.show();
+ }
+ }
+ }, [isEffectivelyDisabled, popover]);
+
+ const handleRangeSelect = useCallback(
+ (range: DateRange) => {
+ fireChange(range);
+ popover.hide();
+ },
+ [fireChange, popover],
+ );
+
+ const handlePresetClick = useCallback(
+ (preset: XDSDateRangePreset) => {
+ fireChange(preset.getRange());
+ popover.hide();
+ },
+ [fireChange, popover],
+ );
+
+ const handleClear = useCallback(
+ (e: React.MouseEvent) => {
+ e.stopPropagation();
+ fireChange(null);
+ },
+ [fireChange],
+ );
+
+ const triggerAriaLabel = value
+ ? `${label}: ${displayValue}`
+ : `${label}: ${placeholder}`;
+
+ return (
+ <XDSField
+ label={label}
+ isLabelHidden={isLabelHidden}
+ description={description}
+ inputID={id}
+ descriptionID={description ? descriptionID : undefined}
+ isOptional={isOptional}
+ isRequired={isRequired}
+ isDisabled={isEffectivelyDisabled}
+ status={
+ status
+ ? {
+ type: status.type,
+ message: status.message,
+ messageID: status.message ? statusMessageID : undefined,
+ }
+ : undefined
+ }
+ labelTooltip={labelTooltip}>
+ <div
+ ref={popover.triggerRef}
+ {...rest}
+ {...mergeProps(
+ xdsClassName('date-range-picker', {
+ size,
+ status: status?.type ?? null,
+ }),
+ stylex.props(
+ inputWrapperStyles.base,
+ sizeStyles[size],
+ isEffectivelyDisabled && inputWrapperStyles.disabled,
+ status && inputStatusBorderStyles[status.type],
+ status && inputStatusHoverShadowStyles[status.type],
+ status && inputStatusFocusWithinStyles[status.type],
+ xstyle,
+ ),
+ className,
+ style,
+ )}>
+ <button
+ ref={ref}
+ id={id}
+ type="button"
+ onClick={handleToggle}
+ disabled={isEffectivelyDisabled}
+ aria-label={triggerAriaLabel}
+ aria-describedby={ariaDescribedBy}
+ aria-required={isRequired === true ? 'true' : undefined}
+ aria-invalid={status?.type === 'error' ? 'true' : undefined}
+ aria-busy={isBusy || undefined}
+ aria-expanded={popover.isOpen}
+ aria-haspopup="dialog"
+ aria-controls={popover.isOpen ? popover.id : undefined}
+ {...stylex.props(
+ styles.trigger,
+ !displayValue && styles.triggerPlaceholder,
+ isEffectivelyDisabled && styles.triggerDisabled,
+ )}>
+ {displayValue || placeholder}
+ </button>
+ {hasClear && value !== null && !isEffectivelyDisabled && (
+ <button
+ type="button"
+ onClick={handleClear}
+ aria-label={`Clear ${label}`}
+ {...stylex.props(styles.iconButton)}>
+ <XDSIcon icon="close" size="sm" color="secondary" />
+ </button>
+ )}
+ <button
+ type="button"
+ onClick={handleToggle}
+ disabled={isEffectivelyDisabled}
+ aria-label={popover.isOpen ? 'Close calendar' : 'Open calendar'}
+ tabIndex={-1}
+ {...stylex.props(
+ styles.iconButton,
+ isEffectivelyDisabled && styles.iconButtonDisabled,
+ )}>
+ <XDSIcon icon="calendar" size="sm" color="secondary" />
+ </button>
+ {isBusy && <XDSSpinner size="sm" />}
+ {status && (
+ <XDSIcon
+ icon={statusIconMap[status.type]}
+ size="md"
+ color={statusIconColorMap[status.type]}
+ />
+ )}
+ </div>
+ {popover.render(
+ <div {...stylex.props(styles.popoverLayout)}>
+ {presets && presets.length > 0 && (
+ <div
+ role="listbox"
+ aria-label="Preset date ranges"
+ {...stylex.props(styles.presetSidebar)}>
+ {presets.map((preset, i) => {
+ const presetRange = preset.getRange();
+ const isActive = isRangeEqual(value, presetRange);
+ return (
+ <button
+ key={i}
+ type="button"
+ role="option"
+ aria-selected={isActive}
+ onClick={() => handlePresetClick(preset)}
+ {...stylex.props(
+ styles.presetButton,
+ isActive && styles.presetButtonActive,
+ )}>
+ {preset.label}
+ </button>
+ );
+ })}
+ </div>
+ )}
+ <XDSCalendar
+ mode="range"
+ value={value ?? undefined}
+ onChange={handleRangeSelect}
+ min={min}
+ max={max}
+ dateConstraints={dateConstraints}
+ numberOfMonths={numberOfMonths}
+ />
+ </div>,
+ {placement: 'below', alignment: 'start'},
+ )}
+ </XDSField>
+ );
+}
+
+XDSDateRangePicker.displayName = 'XDSDateRangePicker';
diff --git a/packages/core/src/DateRangePicker/index.ts b/packages/core/src/DateRangePicker/index.ts
new file mode 100644
index 0000000000..ba558c8f57
--- /dev/null
+++ b/packages/core/src/DateRangePicker/index.ts
@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input DateRangePicker component exports
+ * @output Re-exports XDSDateRangePicker and types
+ * @position Package entry point for DateRangePicker
+ */
+
+export {XDSDateRangePicker} from './XDSDateRangePicker';
+export type {
+ XDSDateRangePickerProps,
+ XDSDateRangePickerSize,
+ XDSDateRangePickerStatus,
+ XDSDateRangePickerStatusType,
+ XDSDateRange,
+ XDSDateRangePreset,
+} from './XDSDateRangePicker';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 7fba07b500..ca156a1cc5 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -52,6 +52,7 @@ export * from './Stack';
export * from './Switch';
export * from './DateInput';
export * from './DateTimePicker';
+export * from './DateRangePicker';
export * from './Field';
export * from './FormLayout';
export * from './Grid';