DocsBlog

  • 0.25.3

  • light

    dark

    system

    Switch mode

  • Cerberus

    Acheron

    Elysium

Get Started
Components
Styling
Theming

Concepts

OverviewCompositionTesting

Layout

Aspect RatioBleedBoxCenterContainerDividerFlexFloatGridLink OverlayScrollableStackWrap

Components

AccordionAdmonitionAvatarButtonCarouselCheckboxClipboardCollapsibleComboboxConfirm ModalCTAModalDate PickerDialogFieldFieldsetFile UploaderIcon ButtonInputLoading StatesMenuNotificationsNumber InputPin InputProgressPrompt ModalRadioRatingSelectSplit ButtonSwitchTableTabsTagTextTextareaToggleTooltip

Utilities

Client OnlyDownload TriggerEnvironmentFeature FlagsFocus TrapForFormat ByteFormat NumberFormat Relative TimeFrameHighlightJSON Tree ViewLocaleLocal StoragePortalPresenceShowsplitPropsTheme

Date Picker

A date picker component for selecting single or range dates.

  • npm
  • source
  • recipe
  • Ark
import {
  DatePicker,
  DatePickerLabel,
  DatePickerInput,
  DatePickerCalendar
} from '@cerberus/react'

Usage

The DatePicker component is a controlled component that allows users to select a single date or a range of dates. It consists of a label, input field, and a calendar view.

Single Date Picker

SMTWTFS
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
Jan
Feb
Mar
Apr
May
Jun
Jul
Aug
Sep
Oct
Nov
Dec
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
Copy
import {
  DatePicker,
  DatePickerLabel,
  DatePickerInput,
  DatePickerCalendar,
  Field,
} from '@cerberus/react'
import { Box } from 'styled-system/jsx'


function StaticPreview() {
  return (
    <Box w="2/3">
      <Field>
        <DatePicker id="start_date" name="start_date">
          <DatePickerLabel>Start date</DatePickerLabel>
          <DatePickerInput />
          <DatePickerCalendar />
        </DatePicker>
      </Field>
    </Box>
  )
}

Date Range Picker

To create a date range picker, set the selectionMode prop to range on the DatePicker component and use the RangePickerInput component as the input field.

SMTWTFS
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
Jan
Feb
Mar
Apr
May
Jun
Jul
Aug
Sep
Oct
Nov
Dec
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
Copy
import {
  DatePicker,
  DatePickerLabel,
  RangePickerInput,
  DatePickerCalendar,
  Field,
} from '@cerberus/react'
import { Box } from 'styled-system/jsx'


function RangePreview() {
  return (
    <Box gap="4" w="2/3">
      <Field>
        <DatePicker id="range_dates" name="range_dates" selectionMode="range">
          <DatePickerLabel>Search range</DatePickerLabel>
          <RangePickerInput />
          <DatePickerCalendar />
        </DatePicker>
      </Field>
    </Box>
  )
}

Using Default Values

You can set the default values for the range date picker by passing the defaultValue prop to the DatePicker component in the form of an Array of two date strings.

Note

The `defaultValue` prop is only used when the component is first rendered. If you need to update the value dynamically, use the `value` prop instead.

SMTWTFS
29
30
31
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
Jan
Feb
Mar
Apr
May
Jun
Jul
Aug
Sep
Oct
Nov
Dec
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
Copy
import {
  DatePicker,
  DatePickerLabel,
  RangePickerInput,
  DatePickerCalendar,
  Field,
  parseDate,
} from '@cerberus/react'
import { Box } from 'styled-system/jsx'


function RangeDefaultValuePreview() {
  const defaultValue = parseDate(['2025-01-01', '2025-01-15'])


  return (
    <Box gap="4" w="2/3">
      <Field>
        <DatePicker
          defaultValue={defaultValue}
          name="range_dates_dv"
          selectionMode="range"
        >
          <DatePickerLabel>Search range</DatePickerLabel>
          <RangePickerInput />
          <DatePickerCalendar />
        </DatePicker>
      </Field>
    </Box>
  )
}

Custom Styles

You can customize the DatePicker width and other styles using the css prop along with the data-part selector to target specific primitives.

SMTWTFS
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
Jan
Feb
Mar
Apr
May
Jun
Jul
Aug
Sep
Oct
Nov
Dec
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
SMTWTFS
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
Jan
Feb
Mar
Apr
May
Jun
Jul
Aug
Sep
Oct
Nov
Dec
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
Copy
import {
  DatePicker,
  DatePickerLabel,
  DatePickerInput,
  DatePickerCalendar,
  Field,
} from '@cerberus/react'
import { Grid } from 'styled-system/jsx'


function CustomStylesDemo() {
  return (
    <Grid columns={2} gap="4" w="3/4">
      <Field>
        <DatePicker
          name="custom_start_date"
          css={{
            w: 'full',
            '& :is([data-part=control])': {
              w: 'full',
            },
          }}
        >
          <DatePickerLabel>Start date</DatePickerLabel>
          <DatePickerInput />
          <DatePickerCalendar />
        </DatePicker>
      </Field>
      <Field>
        <DatePicker
          name="custom_end_date"
          css={{
            w: 'full',
            '& :is([data-part=control])': {
              w: 'full',
            },
          }}
        >
          <DatePickerLabel>End date</DatePickerLabel>
          <DatePickerInput />
          <DatePickerCalendar />
        </DatePicker>
      </Field>
    </Grid>
  )
}

Date Helpers

The DatePicker component relies on different date utilities to handle date parsing and formatting. Here are the options available:

Creating Dates

You can create a structured date Object using the CalendarDate class. This function accepts a date string or an object with year, month, and day properties.

import { CalendarDate } from '@cerberus/react'
const date = new CalendarDate(2022, 2, 3);

Note

View the CalendarDate documentation for more details on how to use it.

Parsing Dates

You can use the parseDate function to convert an array of date strings into a date object that the DatePicker can understand.

import { parseDate } from '@cerberus/react'
const date = parseDate(['2025-01-01', '2025-01-15'])

Note

View the parseDate documentation for more details on how to use it.

Today's Date

You can use the today function to get the current date in a format that the DatePicker can understand.

import { today, getLocalTimeZone } from '@cerberus/react'


const nyDate = today('America/New_York');
const localDate = today(getLocalTimeZone());

Note

View the today documentation for more details on how to use it.

Formatting Dates

You can use the DateFormatter class to format a date object into a string. This is useful for displaying dates in a human-readable format.

import { DateFormatter } from '@cerberus/react'


const formatter = new DateFormatter('en-US', {
  dateStyle: 'long',
  timeZone: 'America/New_York'
})
const date = formatter.format(new Date()); // "January 1, 2025"

Note

View the DateFormatter documentation for more details on how to use it.

Primitives

You can utilize the primitive components or the css prop to customize the date picker.

ComponentDescription
DatePickerRootThe main container for the date-picker items.
DatePickerLabelThe label for the date-picker.
DatePickerControlThe control for the date-picker.
DatePickerInputThe input field and trigger for the date-picker.
DatePickerTriggerThe trigger for the date-picker.
DatePickerClearTriggerThe trigger to clear the date-picker.
DatePickerPositionerThe positioner for the date-picker.
DatePickerContentThe content of the date-picker calendar.
DatePickerYearSelectThe select input for the year in the date-picker.
DatePickerMonthSelectThe select input for the month in the date-picker.
DatePickerViewThe container (view) of the calendar.
DatePickerContextThe context provider for the date-picker calendar.
DatePickerViewControlThe triggers that update the calendar in the view.
DatePickerPrevTriggerThe trigger to navigate to the previous view.
DatePickerNextTriggerThe trigger to navigate to the next view.
DatePickerViewTriggerThe trigger to navigate to a specific view.
DatePickerRangeTextThe text that displays the range of dates selected.
DatePickerTableThe table that contains the calendar.
DatePickerTableRowThe row of the calendar table.
DatePickerTableHeadThe header of the calendar table.
DatePickerTableHeaderThe header cell of the calendar table.
DatePickerTableBodyThe body of the calendar table.
DatePickerTableCellThe cell of the calendar table.
DatePickerTableTriggerThe trigger of the cell in the calendar table.

Data Attributes

The Primitives additionally use the following data attributes for custom styling:

NameValueDescription
data-scopedate-pickerThe scope of the components.
data-partrootThe root container part.
data-partlabelThe label part.
data-partcontrolThe control part.
data-partinputThe input part.
data-parttriggerThe trigger part.
data-partclearTriggerThe clear trigger part.
data-partpositionerThe positioner part.
data-partcontentThe content part.
data-partviewControlThe view control part.
data-partprevTriggerThe previous trigger part.
data-partnextTriggerThe next trigger part.
data-partviewTriggerThe view trigger part.
data-partrangeTextThe range text part.
data-partyearSelectThe year select part.
data-partmonthSelectThe month select part.
data-partviewThe view part.
data-parttableThe table part.
data-parttableHeadThe table head part.
data-parttableBodyThe table body part.
data-parttableRowThe table row part.
data-parttableHeaderThe table header part.
data-parttableCellThe table cell part.
data-parttableCellTriggerThe table cell trigger part.

API

Props

DatePicker

The DatePicker component accepts all the props of the DatePickerRoot primitive

DatePickerLabel

The DatePickerLabel component accepts all the props of the DatePickerLabel primitive

DatePickerInput

The DatePickerInput component accepts all the props of the DatePickerInputEl primitive

Parts

The DatePickerParts API is an Object containing the full family of components.

Note

It is best to only use the DatePickerParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

NameDescription
RootThe DatePickerRoot component and main container for the date-picker items.
LabelThe DatePickerLabel component and label for the date-picker.
ControlThe DatePickerControl component and control for the date-picker.
InputThe DatePickerInput component and input field and trigger for the date-picker.
TriggerThe DatePickerRoot component and trigger for the date-picker.
ClearTriggerThe DatePickerClearTrigger component and trigger to clear the date-picker.
PositionerThe DatePickerPositioner component and positioner for the date-picker.
ContentThe DatePickerContent component and content of the date-picker calendar.
YearSelectThe DatePickerYearSelect component and select input for the year in the date-picker.
MonthSelectThe DatePickerMonthSelect component and select input for the month in the date-picker.
ViewThe DatePickerView component and container (view) of the calendar.
ContextThe DatePickerContext component and context provider for the date-picker calendar.
ViewControlThe DatePickerViewControl component and triggers that update the calendar in the view.
PrevTriggerThe DatePickerPrevTrigger component and trigger to navigate to the previous view.
NextTriggerThe DatePickerNextTrigger component and trigger to navigate to the next view.
ViewTriggerThe DatePickerViewTrigger component and trigger to navigate to a specific view.
RangeTextThe DatePickerRangeText component and text that displays the range of dates selected.
TableThe DatePickerTable component and table that contains the calendar.
TableRowThe DatePickerTableRow component and row of the calendar table.
TableHeadThe DatePickerTableHead component and header of the calendar table.
TableHeaderThe DatePickerTableHeader component and header cell of the calendar table.
TableBodyThe DatePickerTableBody component and body of the calendar table.
TableCellThe DatePickerTableCell component and cell of the calendar table.
TableTriggerThe DatePickerTableTrigger component and trigger of the cell in the calendar table.

On this page

  • Edit this page on Github
Cerberus Design System | Docs