DatePicker

A date picker that combines a date field and a calendar popover for selecting a date.

Date

mmddyyyy

Usage#

import { DatePicker } from '@backstage/ui';

<DatePicker label="Date" />

API reference#

Prop	Type	Default	Description
size	smallmedium	small	Visual size of the picker. Use small for dense layouts, medium for prominent fields.
label	string	-	Visible label displayed above the picker.
secondaryLabel	string	-	Secondary text shown next to the label. If not provided and isRequired is true, displays Required.
description	string	-	Help text displayed below the label.
value	DateValue	-	Controlled value of the date.
defaultValue	DateValue	-	Default value for uncontrolled usage.
onChange	(value: DateValue \| null) => void	-	Handler called when the selected date changes.
granularity	dayhourminutesecond	day	Smallest unit displayed. Defaults to "day" for dates and "minute" for times.
minValue	DateValue	-	Minimum allowed date. Dates before this are disabled.
maxValue	DateValue	-	Maximum allowed date. Dates after this are disabled.
isDateUnavailable	(date: DateValue) => boolean	-	Callback invoked for each calendar date. Return true to mark a date as unavailable.
name	string	-	Form field name for the date, submitted as ISO 8601.
isRequired	boolean	-	Whether the field is required for form submission.
isDisabled	boolean	-	Whether the picker is disabled.
isReadOnly	boolean	-	Whether the picker is read-only.
className	string	-	Additional CSS class name for custom styling.
style	CSSProperties	-	Inline CSS styles object.

Inherits all React Aria DatePicker props.

Examples#

Sizes#

<Flex direction="column" gap="4">
  <DatePicker label="Small" size="small" />
  <DatePicker label="Medium" size="medium" />
</Flex>

Small

mmddyyyy

Medium

mmddyyyy

With default value#

import { parseDate } from '@internationalized/date';

<DatePicker
  label="Booking date"
  defaultValue={parseDate('2025-02-03')}
/>

Booking date

232025

Disabled#

<DatePicker
  label="Date"
  isDisabled
/>

Date

mmddyyyy

Theming#

Our theming system is based on a mix between CSS classes, CSS variables and data attributes. If you want to customise this component, you can use one of these class names below.

bui-DatePicker