XDS — Design System

DateInput@xds/core · XDSDateInput v0.0.13

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.

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

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.

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>
  );
}

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.

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

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.

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> ); }

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> ); }

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> ); }

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> ); }

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> ); }