Date picker API

Import

import { DatePicker } from '@cimpress-ui/react';

Value format

Date picker uses the @internationalized/date package to represent dates and times. You do not need to install this package separately. All exports from @internationalized/date are re-exported from @cimpress-ui/react/date.

Refer to @internationalized/date documentation to learn more about it. Remember that whenever the documentation instructs you to import something from @internationalized/date, you can import the same thing from @cimpress-ui/react/date instead.

Time

To display a time within the date picker, pass a CalendarDateTime instance to the value or defaultValue prop. You can also control how many date/time segments are displayed using the granularity prop.

Preview
Code

In this example, both fields are controlled with the same state value, but with different display granularity.

Date and time of birth

11119901054AM

Date of birth

1111990

import { DatePicker, Stack, Text } from '@cimpress-ui/react';
import { type CalendarDateTime, parseDateTime } from '@cimpress-ui/react/date';
import { useState } from 'react';

export default function Demo() {
  const [selectedDate, setSelectedDate] = useState<CalendarDateTime | null>(() => parseDateTime('1990-11-01T10:54'));

  return (
    <Stack gap={32}>
      <Text as="p">
        In this example, both fields are controlled with the same state value, but with different display granularity.
      </Text>
      <DatePicker label="Date and time of birth" value={selectedDate} onChange={setSelectedDate} granularity="minute" />
      <DatePicker label="Date of birth" value={selectedDate} onChange={setSelectedDate} granularity="day" />
    </Stack>
  );
}

Time zones

Provide a ZonedDateTime instance to the date picker to make it time zone aware.

Preview
Code

In this example, both fields are controlled with the same state value, but with different time zones.

Date and time of birth (Warsaw)

1111990354AMGMT+1

Date and time of birth (Los Angeles)

10311990654PMPST

import { DatePicker, Stack, Text } from '@cimpress-ui/react';
import { parseZonedDateTime, toTimeZone, type ZonedDateTime } from '@cimpress-ui/react/date';
import { LocalizationProvider } from '@cimpress-ui/react/i18n';
import { useState } from 'react';

export default function Demo() {
  const [selectedDate, setSelectedDate] = useState<ZonedDateTime | null>(() =>
    parseZonedDateTime('1990-11-01T03:54[Europe/Warsaw]'),
  );

  return (
    <Stack gap={32}>
      <Text as="p">
        In this example, both fields are controlled with the same state value, but with different time zones.
      </Text>
      <LocalizationProvider locale="en-US">
        <DatePicker
          label="Date and time of birth (Warsaw)"
          value={selectedDate}
          onChange={setSelectedDate}
          granularity="minute"
        />
        <DatePicker
          label="Date and time of birth (Los Angeles)"
          value={selectedDate ? toTimeZone(selectedDate, 'America/Los_Angeles') : null}
          onChange={(value) => setSelectedDate(value ? toTimeZone(value, 'Europe/Warsaw') : null)}
          granularity="minute"
        />
      </LocalizationProvider>
    </Stack>
  );
}

Controlled/uncontrolled usage

This component can be used in a controlled or uncontrolled way.

In the controlled way, this component doesn’t maintain its own internal state, and its value is provided by the parent component. Use the controlled way when you need to be able to change the state of this component in other parts of your application.

In the uncontrolled way, this component maintains its own internal state, and can optionally notify the parent component when its internal state changes. Use the uncontrolled way when you don’t need to change the state of this component in other parts of your application.

Preview
Code

Date of birth (controlled)

1222025

Date of birth (uncontrolled)

1222025

import { DatePicker, Stack } from '@cimpress-ui/react';
import { type CalendarDate, getLocalTimeZone, today } from '@cimpress-ui/react/date';
import { useState } from 'react';

export default function Demo() {
  const [selectedDate, setSelectedDate] = useState<CalendarDate | null>(() => today(getLocalTimeZone()));

  return (
    <Stack gap={32}>
      <DatePicker label="Date of birth (controlled)" value={selectedDate} onChange={setSelectedDate} />
      <DatePicker label="Date of birth (uncontrolled)" defaultValue={today(getLocalTimeZone())} />
    </Stack>
  );
}

Imperative API

This component exposes an imperative API through the apiRef prop. This API allows triggering behaviors that can’t be expressed by props.

Preview
Code

Date of birth

1222025

import { Button, DatePicker, type DatePickerApi, Stack } from '@cimpress-ui/react';
import { getLocalTimeZone, today } from '@cimpress-ui/react/date';
import { useRef } from 'react';

export default function Demo() {
  const apiRef = useRef<DatePickerApi>(null);

  return (
    <Stack gap={16}>
      <DatePicker label="Date of birth" defaultValue={today(getLocalTimeZone())} apiRef={apiRef} />

      <Button onPress={() => apiRef.current?.focus()}>Focus</Button>
    </Stack>
  );
}

Accessibility notes

Grids in the popup calendar follow the ARIA grid pattern. See the linked page for a list of available keyboard interactions.

Each date and time unit in the date picker field is an individually focusable and editable segment. Each segment can be edited using a keyboard, and incremented/decremented using up/down arrow keys. Use left/right arrow keys or the Tab key to move between segments.

DatePicker requires a textual label to remain accessible to assistive technologies. See our accessibility guide for more details.

Changing the calendar system

By default, DatePicker selects a calendar system based on the application’s locale. You can force the date picker to use a specific calendar system using a locale extension subtag.

Preview
Code

Date of birth

mmddyyyy

This date picker uses the Gregorian calendar.

Date of birth

mmddyyyySaka

This date picker uses the Indian calendar.

import { DatePicker, Stack } from '@cimpress-ui/react';
import { LocalizationProvider } from '@cimpress-ui/react/i18n';

export default function Demo() {
  return (
    <Stack gap={32}>
      <LocalizationProvider locale="en-US-u-ca-gregory">
        <DatePicker label="Date of birth" description="This date picker uses the Gregorian calendar." />
      </LocalizationProvider>

      <LocalizationProvider locale="en-US-u-ca-indian">
        <DatePicker label="Date of birth" description="This date picker uses the Indian calendar." />
      </LocalizationProvider>
    </Stack>
  );
}

Forms

Date picker can integrate with native HTML forms. See our forms guide to learn how to work with forms.

API reference

DatePicker

Allows users to enter or select a date and time value.

See date picker usage guidelines.

ref Section titled “ ref ” Ref<HTMLDivElement>: The ref type for this component.

DatePickerProps<T extends DateValue>

id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
label Section titled “ label ” string: The content to display as the label.
aria-label Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
form Section titled “ form ” string: The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See MDN.
name Section titled “ name ” string: The name of the input element, used when submitting an HTML form. See MDN.
description Section titled “ description ” string: A description for the field. Provides a hint such as specific requirements for what to choose.
error Section titled “ error ” FieldError: An error message for the field.
validate Section titled “ validate ” (value: MappedDateValue) => string | true | string[] | undefined: A function that returns an error message (or true) if a given value is invalid. Validation errors are displayed to the user when the form is submitted. For real-time validation, use the error prop instead.
apiRef Section titled “ apiRef ” RefObject<DatePickerApi | null>: A React ref that allows access to the imperative API of this component.
focusedValue Section titled “ focusedValue ” DateValue | null: Controls the currently focused date within the calendar.
defaultFocusedValue Section titled “ defaultFocusedValue ” DateValue | null: The date that is focused when the calendar first mounts (uncountrolled).
minValue Section titled “ minValue ” DateValue | null: The minimum allowed date that a user may select.
maxValue Section titled “ maxValue ” DateValue | null: The maximum allowed date that a user may select.
isDateUnavailable Section titled “ isDateUnavailable ” (date: DateValue) => boolean: Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
placeholderValue Section titled “ placeholderValue ” T | null: A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today's date at midnight.
granularity Section titled “ granularity ” Granularity: Determines the smallest unit that is displayed in the date picker. By default, this is "day" for dates, and "minute" for times.
firstDayOfWeek Section titled “ firstDayOfWeek ” 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat': The day that starts the week.
autoComplete Section titled “ autoComplete ” string: Describes the type of autocomplete functionality the input should provide if any. See MDN.
isOpen Section titled “ isOpen ” boolean: Whether the overlay is open by default (controlled).
defaultOpen Section titled “ defaultOpen ” boolean: Whether the overlay is open by default (uncontrolled).
onOpenChange Section titled “ onOpenChange ” (isOpen: boolean) => void: Handler that is called when the overlay's open state changes.
onFocus Section titled “ onFocus ” (e: FocusEvent<Element>) => void: Handler that is called when the element receives focus.
onBlur Section titled “ onBlur ” (e: FocusEvent<Element>) => void: Handler that is called when the element loses focus.
autoFocus Section titled “ autoFocus ” boolean: Whether the element should receive focus on render.
isRequired Section titled “ isRequired ” boolean: Whether user input is required on the input before form submission.
isInvalid Section titled “ isInvalid ” boolean: Whether the input value is invalid.
isDisabled Section titled “ isDisabled ” boolean: Whether the input is disabled.
isReadOnly Section titled “ isReadOnly ” boolean: Whether the input can be selected but not changed by the user.
value Section titled “ value ” T | null: The current value (controlled).
defaultValue Section titled “ defaultValue ” T | null: The default value (uncontrolled).
onChange Section titled “ onChange ” (value: MappedDateValue<T> | null) => void: Handler that is called when the value changes.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

Date picker API

Import

Value format

Time

Time zones

Controlled/uncontrolled usage

Imperative API

Accessibility notes

Changing the calendar system

Forms

API reference

DatePicker

ref

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

label

aria-label

aria-labelledby

aria-describedby

aria-details

form

name

description

error

validate

apiRef

focusedValue

defaultFocusedValue

minValue

maxValue

isDateUnavailable

placeholderValue

granularity

firstDayOfWeek

autoComplete

isOpen

defaultOpen

onOpenChange

onFocus

onBlur

autoFocus

isRequired

isInvalid

isDisabled

isReadOnly

value

defaultValue

onChange

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft