Balance Logo
Balance
Reckon Design System
Open playroom

Date Picker

Allow users to select a single date or a range of dates.
Install
pnpm add @balance-web/date-picker
Import usage
import {
Calendar,
DatePicker,
AGGridDatePicker,
CalendarPicker,
DateRangePicker,
CalendarRangePicker
} from '@balance-web/date-picker';
  • Code
  • API

NOTE: all date components expect their value to be an ISO 8601 date string (without the time signature), which follows the format yyyy-mm-dd

Alternatives

The kind of date (exact, approximate, memorable) you are requesting from the user will determine which component is best to use.

  • DateInput — When the date is memorable or distant, such as a date of birth

DatePicker

Allows the user to view, type and pick dates from a calendar.

Edit in Playroom

size

There are three options for the size, "medium" is the default.

disabled

Disables the input.

Calendar props

The date picker implements react-day-picker under the hood. A subset of the API is available to influence the calendar appearance and behaviour:

  • disabledDays
  • modifiers
  • initialMonth
  • fromMonth
  • toMonth

Notice that we're disallowing selection of days prior to today using the disabledDays property. We're also disabling navigation to months prior to today using fromMonth because they would not be selectable.

DateRangePicker

The range picker functions much like the DatePicker except it lets the user select or type a date range.

Size

The DateRangePicker accepts the same "size" property as the DatePicker.

disabled

Disables the input.

Keyboard shortcuts

t

Selects todays date.

CalendarPicker

A simple version of the DatePicker meant to be used for UIs that require filtering instead of forms. It does not have text input.

CalendarPicker

A simple version of the DateRangePicker meant to be used for UIs that require filtering instead of forms. It does not have text input.

Testing

All date picker components support the data attribute to facilitate testing with automatic testid generation and hierarchical prefixing. When you provide a base testid, the component automatically generates testids for all its interactive elements using that base as a prefix.

For more information on how to use the data attribute, see the Core documentation.

Additionally each balance component will be annotated with a data-balance-component attribute to help identify the boundary of the component in tests.

Selecting these with xpath should be straightforward, as the testids are structured hierarchically. For example, if you set data={{ testid: 'my-component' }}, the generated testids will be prefixed with my-component, making it easy to select specific elements in your tests.

Example XPath Selectors

The date picker balance component which you've set up with a testid of my-component:

//*[@data-balance-component='date-picker' and @data-testid='my-component']

The button of any date picker balance component with a testid of my-component can be selected like this:

//*[@data-testid='my-component--button']

(or if you want to be very specific, you can use the full path)

//*[@data-balance-component='date-picker' and @data-testid='my-component']//*[@data-testid='my-component--button']

DatePicker

The DatePicker supports testids for all its interactive elements:

This will generate the following testids:

  • payment-date - Main wrapper element
  • payment-date--input - Text input field
  • payment-date--clearButton - Clear button (when value exists)
  • payment-date--popover - Calendar popover dialog
  • payment-date--calendar - Calendar component
  • payment-date--shortcuts - Keyboard shortcuts legend (when enabled)

DateRangePicker

The DateRangePicker supports testids for its date range selection elements:

This will generate the following testids:

  • pay-period - Main wrapper element
  • pay-period--startInput - Start date input field
  • pay-period--endInput - End date input field
  • pay-period--clearButton - Clear button (when value exists)
  • pay-period--popover - Calendar popover dialog
  • pay-period--calendar - Calendar component

CalendarPicker

The CalendarPicker supports testids for its button-only date selection:

This will generate the following testids:

  • filter-date - Main wrapper element
  • filter-date--button - Trigger button
  • filter-date--popover - Calendar popover dialog
  • filter-date--calendar - Calendar component

CalendarRangePicker

The CalendarRangePicker supports testids for its button-only date range selection:

This will generate the following testids:

  • filter-period - Main wrapper element
  • filter-period--button - Trigger button
  • filter-period--popover - Calendar popover dialog
  • filter-period--calendar - Calendar component
Copyright © 2025 Reckon. Designed and developed in partnership with Thinkmill.
Bitbucket logoJira software logoConfluence logo