A date picker consists of a label, and group containing a date field and a button.

Clicking the button opens a popup containing a calendar.

The date field includes segments representing each unit of a date and time (e.g. years, months, days, etc.), each of which is individually focusable and editable using the keyboard.

The calendar popup offers a more visual way of choosing a date.

Import

import { Datepicker } from "@fuegokit/react";

Additional styling guides and examples are coming soon. For now, explore the examples at Storybook.

Usage

Date

yyyy

<Datepicker>
  <Datepicker.Label>Date</Datepicker.Label>
  <DatepickerGroup>
    <DatepickerDateInput>
      {(segment) => <DatepickerDateSegment segment={segment} />}
    </DatepickerDateInput>
    <DatepickerButton>
      <AkCalendarIcon />
    </DatepickerButton>

Anatomy

A date picker consists of a label, and group containing a date field and a button. Clicking the button opens a popup containing a calendar. The date field includes segments representing each unit of a date and time (e.g. years, months, days, etc.), each of which is individually focusable and editable using the keyboard. The calendar popup offers a more visual way of choosing a date.

Datepicker

Props

Datepicker

Contains all the parts of a Datepicker.

Name	Type	Default	Description
minValue	DateValue	-	The minimum allowed date that a user may select.
maxValue	DateValue	-	The maximum allowed date that a user may select.
isDateUnavailable	(date: DateValue) => boolean	-	Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
placeholderValue	DateValue	-	A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today's date at midnight.
hourCycle	12 \| 24	-	Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
granularity	Granularity	-	Determines the smallest unit that is displayed in the date picker. By default, this is "day" for dates, and "minute" for times.
hideTimeZone	boolean	false	Whether to hide the time zone abbreviation.
isDisabled	boolean	-	Whether the input is disabled.
isReadOnly	boolean	-	Whether the input can be selected but not changed by the user.
validationState	ValidationState	-	Whether the input should display its "valid" or "invalid" visual styling.
isRequired	boolean	-	Whether user input is required on the input before form submission. Often paired with the necessityIndicator prop to add a visual indicator to the input.
autoFocus	boolean	-	Whether the element should receive focus on render.
isReadOnly	boolean	-	Whether the input can be selected but not changed by the user.
isOpen	boolean	-	Whether the overlay is open by default (controlled).
defaultOpen	boolean	-	Whether the overlay is open by default (uncontrolled).
autoFocus	boolean	-	Whether the element should receive focus on render.
value	DateValue \| null	-	The current value (controlled).
defaultValue	DateValue \| null	-	The default value (uncontrolled).
children	ReactNode \| (values: DatePickerState) => ReactNode	-	The children of the component. A function may be provided to alter the children based on component state.
className	string \| (values: DatePickerState) => string	-	The CSS className for the element. A function may be provided to compute the class based on component state.
style	CSSProperties \| (values: DatePickerState) => CSSProperties	-	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Default	Description
onFocus	(e: FocusEvent<Target>) => void	-	Handler that is called when the element receives focus.
onBlur	(e: FocusEvent<Target>) => void	-	Handler that is called when the element loses focus.
onFocusChange	(isFocused: boolean) => void	-	Handler that is called when the element's focus status changes.
onKeyDown	(e: KeyboardEvent) => void	-	Handler that is called when a key is pressed.
onKeyUp	(e: KeyboardEvent) => void	-	Handler that is called when a key is released.
onOpenChange	(isOpen: boolean) => void	-	Handler that is called when the overlay's open state changes.
onChange	(value: MappedDateValue<DateValue>) => void	-	Handler that is called when the value changes.

Layout

Name	Type	Default	Description
slot	string	-	A slot name for the component. Slots allow the component to receive props from a parent component.

Accessibility

Name	Type	Default	Description
id	string	-	The element's unique identifier. See MDN.
aria-label	string	-	Defines a string value that labels the current element.
aria-labelledby	string	-	Identifies the element (or elements) that labels the current element.
aria-describedby	string	-	Identifies the element (or elements) that describes the object.
aria-details	string	-	Identifies the element (or elements) that provide a detailed, extended description for the object.

Datepicker.Label

A semantic HTML `<label>` for the Datepicker component.

Name	Type	Default	Description
-	-	-	A `<Datepicker.Label>` accepts all props supported by the `<label>` HTML element.

Datepicker.Group

Name	Type	Default	Description
-	-	-	A <Datepicker.Group> accepts all HTML attributes.

Datepicker.DateInput

The <DateInput> component renders a group of date segments. It accepts a function as its children, which is called to render a <DateSegment> for each segment.

Name	Type	Default	Description
children*	(segment: DateSegment) => ReactElement	-	-
className	string \| (values: DateInputRenderProps) => string	-	The CSS className for the element. A function may be provided to compute the class based on component state.
style	CSSProperties \| (values: DateInputRenderProps) => CSSProperties	-	The inline style for the element. A function may be provided to compute the style based on component state.

Datepicker.DateSegment

The <DateSegment> component renders an individual segment.

Name	Type	Default	Description
segment*	DateSegment	-
children	ReactNode \| (values: DateSegmentRenderProps) => ReactNode	-	The children of the component. A function may be provided to alter the children based on component state.
className	string \| (values: DateSegmentRenderProps) => string	-	The CSS className for the element. A function may be provided to compute the class based on component state.

Layout

Name	Type	Default	Description
style	CSSProperties \| (values: DateSegmentRenderProps) => CSSProperties	-	The inline style for the element. A function may be provided to compute the style based on component state.

Datepicker.Button

A `<Button>` accepts its contents as children. Other props such as `onPress` and `isDisabled` will be set by the `DatePicker` or `Calendar`.

Name	Type	Default	Description
form	string	-	The form element to associate the button with. The value of this attribute must be the id of a form in the same document.
formAction	string	-	The URL that processes the information submitted by the button. Overrides the action attribute of the button's form owner.
formEncType	string	-	Indicates how to encode the form data that is submitted.
formMethod	string	-	Indicates the HTTP method used to submit the form.
formNoValidate	boolean	-	Indicates that the form is not to be validated when it is submitted.
formTarget	string	-	Overrides the target attribute of the button's form owner.
name	string	-	Submitted as a pair with the button's value as part of the form data.
value	string	-	The value associated with the button's name when it's submitted with the form data.
isDisabled	boolean	-	Whether the button is disabled.
autoFocus	boolean	-	Whether the element should receive focus on render.
type	'button' \| 'submit' \| 'reset'	-	The behavior of the button when used in an HTML form.
children	ReactNode \| (values: ButtonRenderProps) => ReactNode	-	The children of the component. A function may be provided to alter the children based on component state.
className	string \| (values: ButtonRenderProps) => string	-	The CSS className for the element. A function may be provided to compute the class based on component state.
style	CSSProperties \| (values: ButtonRenderProps) => CSSProperties	-	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Default	Description
onPress	(e: PressEvent) => void	-	Handler that is called when the press is released over the target.
onPressStart	(e: PressEvent) => void	-	Handler that is called when a press interaction starts.
onPressEnd	(e: PressEvent) => void	-	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressChange	(isPressed: boolean) => void	-	Handler that is called when the press state changes.
onPressUp	(e: PressEvent) => void	-	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
onFocus	(e: FocusEvent<Target>) => void	-	Handler that is called when the element receives focus.
onBlur	(e: FocusEvent<Target>) => void	-	Handler that is called when the element loses focus.
onFocusChange	(isFocused: boolean) => void	-	Handler that is called when the element's focus status changes.
onKeyDown	(e: KeyboardEvent) => void	-	Handler that is called when a key is pressed.
onKeyUp	(e: KeyboardEvent) => void	-	Handler that is called when a key is released.

Layout

Name	Type	Default	Description
slot	string	-	A slot name for the component. Slots allow the component to receive props from a parent component.

Accessibility

Name	Type	Default	Description
id	string	-	The element's unique identifier. See MDN.
excludeFromTabOrder	boolean	-	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
aria-expanded	boolean \| 'true' \| 'false'	-	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
aria-haspopup	boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog' \| 'true' \| 'false'	-	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
aria-controls	string	-	Identifies the element (or elements) whose contents or presence are controlled by the current element.
aria-pressed	boolean \| 'true' \| 'false' \| 'mixed'	-	Indicates the current "pressed" state of toggle buttons.
aria-label	string	-	Defines a string value that labels the current element.
aria-labelledby	string	-	Identifies the element (or elements) that labels the current element.
aria-describedby	string	-	Identifies the element (or elements) that describes the object.
aria-details	string	-	Identifies the element (or elements) that provide a detailed, extended description for the object.

Datepicker.Popover

A `<Popover>` is an overlay to hold the `<Calendar>`, positioned relative to the `<Group>`. By default, it has a placement of bottom start within a `<DatePicker>`, but this and other positioning properties may be customized.

Name	Type	Default	Description
triggerRef	RefObject<Element>	-	The ref for the element which the popover positions itself with respect to. When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone.
placement	Placement	'bottom'	The placement of the element with respect to its anchor element.
containerPadding	number	12	The placement padding that should be applied between the element and its surrounding container.
offset	number	0	The additional offset applied along the main axis between the element and its anchor element.
crossOffset	number	0	The additional offset applied along the cross axis between the element and its anchor element.
shouldFlip	boolean	true	Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.
isNonModal	boolean	-	Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies. Most popovers should not use this option as it may negatively impact the screen reader experience. Only use with components such as combobox, which are designed to handle this situation carefully.
isKeyboardDismissDisabled	boolean	false	Whether pressing the escape key to close the popover should be disabled. Most popovers should not use this option. When set to true, an alternative way to close the popover with a keyboard must be provided.
arrowSize	number	0	Cross size of the overlay arrow in pixels.
boundaryElement	Element	document.body	Element that that serves as the positioning boundary.
scrollRef	RefObject<Element>	overlayRef	A ref for the scrollable region within the overlay.
shouldUpdatePosition	boolean	true	Whether the overlay should update its position automatically.
arrowBoundaryOffset	number	0	The minimum distance the arrow's edge should be from the edge of the overlay element.
children	ReactNode \| (values: PopoverRenderProps) => ReactNode	-	The children of the component. A function may be provided to alter the children based on component state.
className	string \| (values: PopoverRenderProps) => string	-	The CSS className for the element. A function may be provided to compute the class based on component state.
style	CSSProperties \| (values: PopoverRenderProps) => CSSProperties	-	The inline style for the element. A function may be provided to compute the style based on component state.

Layout

Name	Type	Default	Description
slot	string	-	A slot name for the component. Slots allow the component to receive props from a parent component.
maxHeight	number	-	The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height.

Datepicker.Popover

Name	Type	Default	Description
children	ReactNode \| (opts: DialogRenderProps) => ReactNode	-	The ref for the element which the popover positions itself with respect to. When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone.
className	string	-	The CSS className for the element.
style	CSSProperties	-	The inline style for the element.

Events

Name	Type	Default	Description
onClose	() => void	-	-

Layout

Name	Type	Default	Description
slot	string	-	A slot name for the component. Slots allow the component to receive props from a parent component.

Accessibility

Name	Type	Default	Description
role	'dialog' \| 'alertdialog'	'dialog'	The accessibility role for the dialog.
id	string	-	The element's unique identifier. See MDN.
aria-label	string	-	Defines a string value that labels the current element.
aria-labelledby	string	-	Identifies the element (or elements) that labels the current element.
aria-describedby	string	-	Identifies the element (or elements) that describes the object.
aria-details	string	-	Identifies the element (or elements) that provide a detailed, extended description for the object.

Datepicker.Calendar

A `<Calendar>` accepts one or more month grids as chilren, along with previous and next buttons to navigate forward and backward.

Name	Type	Default	Description
visibleDuration	DateDuration	{months: 1}	The amount of days that will be displayed at once. This affects how pagination works.
minValue	DateValue	-	The minimum allowed date that a user may select.
maxValue	DateValue	-	The maximum allowed date that a user may select.
isDateUnavailable	(date: DateValue) => boolean	-	Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
isDisabled	boolean	false	Whether the calendar is disabled.
isReadOnly	boolean	false	Whether the calendar value is immutable.
autoFocus	boolean	false	Whether to automatically focus the calendar when it mounts.
focusedValue	DateValue	-	Controls the currently focused date within the calendar.
defaultFocusedValue	DateValue	-	The date that is focused when the calendar first mounts (uncountrolled).
validationState	ValidationState	-	Whether the current selection is valid or invalid according to application logic.
validationState	ValidationState	-	Whether the current selection is valid or invalid according to application logic.
value	DateValue \| null	-	The current value (controlled).
defaultValue	DateValue \| null	-	The default value (uncontrolled).
children	ReactNode \| (values: CalendarState) => ReactNode	-	The children of the component. A function may be provided to alter the children based on component state.
className	string \| (values: CalendarState) => string	-	The CSS className for the element. A function may be provided to compute the class based on component state.
style	CSSProperties \| (values: CalendarState) => CSSProperties	-	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Default	Description
onFocusChange	(date: CalendarDate) => void	-	Handler that is called when the focused date changes.
onChange	(value: MappedDateValue<DateValue>) => void	-	Handler that is called when the value changes.

Layout

Name	Type	Default	Description
slot	string	-	A slot name for the component. Slots allow the component to receive props from a parent component.

Datepicker.CalendarGrid

A `<CalendarGrid>` renders an individual month within a `<Calendar>`. It accepts a function as its children, which is called to render a `<CalendarCell>` for each date. This renders a default `<CalendarGridHeader>`, which displays the weekday names in the column headers. This can be customized by providing a `<CalendarGridHeader>` and `<CalendarGridBody>` as children instead of a function.

Name	Type	Default	Description
children	ReactElement \| ReactElement[] \| (date: CalendarDate) => ReactElement	-	Either a function to render calendar cells for each date in the month, or children containing a <CalendarGridHeader>`` and` when additional customization is needed.
offset	DateDuration	-	An offset from the beginning of the visible date range that this CalendarGrid should display. Useful when displaying more than one month at a time.
weekdayStyle	'narrow' \| 'short' \| 'long'	'narrow'	The style of weekday names to display in the calendar grid header, e.g. single letter, abbreviation, or full day name.
className	string	-	The CSS className for the element.
style	CSSProperties	-	The inline style for the element.

Datepicker.CalendarGridHeader

A `<CalendarGridHeader>` renders the header within a `<CalendarGrid>`, displaying a list of weekday names. It accepts a function as its children, which is called with a day name abbreviation to render a `<CalendarHeaderCell>` for each column header.

Name	Type	Default	Description
children	(day: string) => ReactElement	-	A function to render a <CalendarHeaderCell> for a weekday name.
className	string	-	The CSS className for the element.
style	CSSProperties	-	The inline style for the element.

Datepicker.CalendarHeaderCell

A <CalendarHeaderCell> renders a column header within a <CalendarGridHeader>. It typically displays a weekday name.

Name	Type	Default	Description
children	React.ReactNode	-	The children of the component.
className	string	-	The CSS className for the element.
style	CSSProperties	-	The inline style for the element.

Datepicker.CalendarGridBody

A `<CalendarGridBody>` renders the body within a `<CalendarGrid>`. It accepts a function as its children, which is called to render a `<CalendarCell>` for each date.

Name	Type	Default	Description
children	React.ReactNode	-	The children of the component.
className	string	-	The CSS className for the element.
style	CSSProperties	-	The inline style for the element.

Datepicker.CalendarGridBody

A `<CalendarCell>` renders an individual date within a `<CalendarGrid>`.

Name	Type	Default	Description
date	CalendarDate	-	The date to render in the cell.
children	ReactNode \| (values: CalendarCellRenderProps) => ReactNode	-	The children of the component. A function may be provided to alter the children based on component state.
className	string \| (values: CalendarCellRenderProps) => string	-	The CSS className for the element. A function may be provided to compute the class based on component state.
style	CSSProperties \| (values: CalendarCellRenderProps) => CSSProperties	-	The inline style for the element. A function may be provided to compute the style based on component state.

Datepicker

Import

Usage

Anatomy

Props

Datepicker

Datepicker.Label

Datepicker.Group

Datepicker.DateInput

Datepicker.DateSegment

Datepicker.Button

Datepicker.Popover

Datepicker.Popover

Datepicker.Calendar

Datepicker.CalendarGrid

Datepicker.CalendarGridHeader

Datepicker.CalendarHeaderCell

Datepicker.CalendarGridBody

Datepicker.CalendarGridBody

See also