DateInput·component·@astryxdesign/core

Date Input

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.

Open in Playground @astryxdesign/core/DateInput

Showcases and examples

6 documented examples

Date Input

A date input field with a calendar popover. Type a date or click the calendar icon to pick one.

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · date-input-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {useState} from 'react';
import {DateInput} from '@astryxdesign/core/DateInput';
import {Stack} from '@astryxdesign/core/Layout';

type DateString =
  `${number}${number}${number}${number}-${number}${number}-${number}${number}`;

export default function DateInputShowcase() {
  const [date, setDate] = useState<DateString | undefined>(undefined);

  return (
    <Stack
      direction="vertical"
      width="100%"
      style={{minWidth: 240, maxWidth: 400}}>
      <DateInput
        label="Start date"
        placeholder="Select a date"
        value={date}
        onChange={setDate}
        hasClear
      />
    </Stack>
  );
}

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.

Provide clear labels and descriptions so users understand what date is expected.
Use min, max, and dateConstraints to restrict selectable dates to valid ranges.
Use hasClear when the date is optional so the user can reset it.
Show a loading state with changeAction when the date triggers a server-side save.
Use DateInput inside InputGroup when adding a short static prefix or suffix, such as a due-date hint.
Use a DateInput for free-form text that does not represent a calendar date.
Hide the label without surrounding context that makes the field purpose obvious.
Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.
Wrap a disabled DateInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

Typed props

Prop	Type and behavior
`label`	`string` · required 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.
`disabledMessage`	`string` Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled DateInput in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.
`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`	`{type: 'warning' \| 'error' \| 'success', message?: string}` Status indicator object for error, warning, or success states with a message.
`statusVariant`	`'attached' \| 'detached' \| 'tooltip'` · default 'attached' How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.
`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.
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'` · default 0 First day of week in the calendar popover. A number (0 = Sunday to 6 = Saturday) or a three-letter day name.
`format`	`'date' \| 'date_long' \| 'date_weekday' \| 'system_date' \| ((value: ISODateString) => string)` · default 'date_long' How the committed date value is displayed. Named values are reused from Timestamp's format vocabulary: 'date' shows 'Mar 21, 2026', 'date_long' shows 'March 21, 2026', 'date_weekday' shows 'Wed, Mar 21, 2026', 'system_date' shows '2026-03-21'. A function receives the ISO value and returns a custom string. Applies only to the committed value, never to text being typed.
`presentation`	`'popover' \| 'bottom-sheet' \| 'native' \| 'adaptive-bottom-sheet' \| 'adaptive-native'` · default 'adaptive-native' Which surface draws the date picker. 'adaptive-native' (the default) uses Astryx's calendar popover on a fine pointer and the browser/OS picker (input type=date) on a coarse pointer, keeping Astryx fallbacks where a native control cannot express the value; 'native' always uses the browser/OS picker with no fallback; 'adaptive-bottom-sheet' uses the popover on a fine pointer and Astryx's bottom-sheet picker on a coarse pointer; 'popover' and 'bottom-sheet' force that Astryx surface on every pointer. Every value opens a picker; a typed-only field is TimeInput's alone. Use a non-native presentation for a field that needs weekStartsOn, numberOfMonths or dateConstraints, none of which a native picker can express.
`nativePicker`	`'touch' \| 'always' \| 'never'` · default 'touch' Deprecated: use presentation ('touch' = 'adaptive-native', 'always' = 'native', 'never' = 'adaptive-bottom-sheet'). Still works exactly as released; presentation wins when both are set.
`width`	`SizeValue` Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.
`xstyle`	`StyleXStyles` StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.

Anatomy

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 · optional

A month grid that appears when the icon is clicked or the input is focused.

Clear button · optional

A × button that resets the date value. Shown when hasClear is true and a date is set.

Status message · optional

An error, warning, or success message below the input.

Theming

Targets

astryx-date-input

Visual props: size, status

States: disabled

astryx-date-input-toggle-icon

States: state

astryx-date-input-clear-icon

Deprecated; use input-clear-icon.