XDS — Design System

XDSDateInput@xds/core · DateInput

Usage

DateInput lets the user type or pick a date from a calendar popover. Use it for scheduling, deadlines, booking dates, or any form field that needs a specific calendar date.

Best practices

Guidance	Practices
Do	Provide clear labels and descriptions so users understand what date is expected.
Do	Use min, max, and dateConstraints to restrict selectable dates to valid ranges.
Do	Use hasClear when the date is optional so the user can easily reset it.
Do	Show a loading state with changeAction when the date triggers a server-side save.
Don't	Use a DateInput for free-form text that does not represent a calendar date.
Don't	Hide the label without surrounding context that makes the field purpose obvious.
Don't	Rely on the calendar alone — the text input lets users type dates directly, which is faster for known dates.

Anatomy

Element		Description
Label	required	Text above the input describing what date is expected.
Text input	required	A field where the user can type a date directly. Parses common formats like MM/DD/YYYY.
Calendar icon	required	A button that opens the calendar popover for visual date picking.
Calendar popover		A month grid that appears when the icon is clicked or the input is focused.
Clear button		A × button that resets the date value. Shown when hasClear is true and a date is set.
Status message		An error, warning, or success message below the input.

Import

ts
import {XDSDateInput} from '@xds/core/DateInput'

Props

Prop	Type	Description
labelrequired	string	Label text.
isLabelHidden	boolean (default: false)	Visually hide the label.
description	string	Helper text displayed below the label.
isOptional	boolean (default: false)	Show an "(optional)" indicator next to the label.
isRequired	boolean (default: false)	Mark the field as required.
isDisabled	boolean (default: false)	Disable the input and calendar.
value	ISODateString	Selected date in YYYY-MM-DD format.
onChange	(value: ISODateString \| undefined) => void	Callback invoked when the selected date changes.
changeAction	(value: ISODateString \| undefined) => void \| Promise<void>	Async action fired after onChange. Drives optimistic UI updates via useTransition.
isLoading	boolean (default: false)	Whether the input is in a loading state. Disables interaction and shows a spinner.
min	ISODateString	Minimum selectable date (YYYY-MM-DD).
max	ISODateString	Maximum selectable date (YYYY-MM-DD).
dateConstraints	Array<(date: Date) => boolean>	Array of custom constraint functions that disable specific dates.
placeholder	string (default: 'Select a date')	Placeholder text shown in the text input.
size	'sm' \| 'md' \| 'lg' (default: 'md')	Size of the input control.
status	XDSInputStatus	Status indicator object for error, warning, or success states with a message.
labelTooltip	string	Tooltip text displayed via an info icon at the end of the label.
hasClear	boolean (default: false)	Shows a clear (×) button when a date value is set. Clicking it clears the value and returns focus to the input.
numberOfMonths	1 \| 2 (default: 1)	Number of months displayed simultaneously in the calendar popover.
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

Examples

Common configurations, variations, and states.

DateInput — ClearableDate input with a clear button that resets the value. Use when the date field is optional and the user may need to undo their selection.

tsx
'use client';
import {useState} from 'react';
import {XDSDateInput} from '@xds/core/DateInput';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
type DateString =
  `${number}${number}${number}${number}-${number}${number}-${number}${number}`;
export default function DateInputClearable() {
  const [value, setValue] = useState<DateString | undefined>(
    '2026-04-06' as DateString,
  );
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSText type="supporting" color="secondary">
        {value ? `Selected: ${value}` : 'No date selected'}
      </XDSText>
      <XDSDateInput
        label="Event date"
        description="Pick a date for your event"
        placeholder="Select a date"
        value={value}
        onChange={setValue}
        hasClear
      />
    </XDSStack>
  );
}

DateInput — Date RangeDate input constrained to a min/max window. Use when only certain dates are valid, like booking availability or a fiscal quarter.

tsx
'use client';
import {useState} from 'react';
import {XDSDateInput} from '@xds/core/DateInput';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
type DateString =
  `${number}${number}${number}${number}-${number}${number}-${number}${number}`;
export default function DateInputDateRange() {
  const [value, setValue] = useState<DateString | undefined>(undefined);
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSText type="supporting" color="secondary">
        {value ? `Booked: ${value}` : 'Pick a date in the available range'}
      </XDSText>
      <XDSDateInput
        label="Booking date"
        min="2026-01-15"
        max="2026-02-15"
        description="Available dates: Jan 15 – Feb 15, 2026"
        placeholder="Select a booking date"
        value={value}
        onChange={setValue}
      />
    </XDSStack>
  );
}

DateInput — DescriptionDate input with helper text below the label explaining what the field expects. Use when the purpose of the date is not obvious from the label alone.

tsx
'use client';
import {useState} from 'react';
import {XDSDateInput} from '@xds/core/DateInput';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
type DateString =
  `${number}${number}${number}${number}-${number}${number}-${number}${number}`;
export default function DateInputWithDescription() {
  const [value, setValue] = useState<DateString | undefined>(undefined);
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSText type="supporting" color="secondary">
        Helper text explains what the field expects
      </XDSText>
      <XDSDateInput
        label="Start date"
        description="Your subscription begins on this date"
        placeholder="Select a start date"
        value={value}
        onChange={setValue}
      />
    </XDSStack>
  );
}

DateInput — ValidationDate input in all three status states: error, warning, and success. Use to surface validation issues, caution the user, or confirm a valid selection.

tsx
'use client';
import {useState} from 'react';
import {XDSDateInput} from '@xds/core/DateInput';
import {XDSStack} from '@xds/core/Layout';
type DateString =
  `${number}${number}${number}${number}-${number}${number}-${number}${number}`;
export default function DateInputWithValidation() {
  const [errorVal, setErrorVal] = useState<DateString | undefined>(
    '2026-01-25' as DateString,
  );
  const [warningVal, setWarningVal] = useState<DateString | undefined>(
    '2026-12-25' as DateString,
  );
  const [successVal, setSuccessVal] = useState<DateString | undefined>(
    '2026-03-10' as DateString,
  );
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSDateInput
        label="Event date"
        value={errorVal}
        onChange={setErrorVal}
        status={{type: 'error', message: 'This date is already booked'}}
      />
      <XDSDateInput
        label="Preferred date"
        value={warningVal}
        onChange={setWarningVal}
        status={{type: 'warning', message: 'This date falls on a holiday'}}
      />
      <XDSDateInput
        label="Start date"
        value={successVal}
        onChange={setSuccessVal}
        status={{type: 'success', message: 'Date confirmed'}}
      />
    </XDSStack>
  );
}

Showcase source

tsx
'use client';
import {useState} from 'react';
import {XDSDateInput} from '@xds/core/DateInput';
import {XDSStack} from '@xds/core/Layout';
import * as stylex from '@stylexjs/stylex';
type DateString =
  `${number}${number}${number}${number}-${number}${number}-${number}${number}`;
const styles = stylex.create({
  root: {
    width: 320,
  },
});
export default function DateInputShowcase() {
  const [date, setDate] = useState<DateString | undefined>(undefined);
  return (
    <XDSStack direction="vertical" xstyle={styles.root}>
      <XDSDateInput
        label="Start date"
        placeholder="Select a date"
        value={date}
        onChange={setDate}
        hasClear
      />
    </XDSStack>
  );
}