XDSDateInput@xds/core · DateInput
Preview coming soon

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

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

Anatomy

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

Import

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

Props

PropTypeDescription
labelrequired
stringLabel text.
isLabelHidden
boolean (default: false)Visually hide the label.
description
stringHelper 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
ISODateStringSelected date in YYYY-MM-DD format.
onChange
(value: ISODateString | undefined) => voidCallback 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
ISODateStringMinimum selectable date (YYYY-MM-DD).
max
ISODateStringMaximum 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
XDSInputStatusStatus indicator object for error, warning, or success states with a message.
labelTooltip
stringTooltip 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
StyleXStylesStyleX 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>
  );
}