Preview

Usage

<cs-date-picker value="2025-01-15" placeholder="YYYY/MM/DD"></cs-date-picker>
<cs-date-picker value="2025-01-15" disabled></cs-date-picker>
<cs-date-picker value="2025-01-15" invalid></cs-date-picker>

Properties

aria-describedbystring

Adds aria-describedby to the calendar.

aria-labelstring default: null

Adds an aria-label to the native control.

Use this if you don't have a visible label for this control.

aria-labelledbystring

Adds aria-labelledby to the calendar.

aria-requiredboolean default: null

Specifies whether to add aria-required to the native control.

auto-focusboolean default: false

Indicates whether the control should be focused as soon as the page loads, which enables the user to start typing without having to manually focus the control. Don't use this option on pages where the control may be scrolled out of the viewport.

date-disabled-reasonCalendarProps.DateDisabledReasonFunction

Provides a reason why a particular date in the calendar is not enabled (only when isDateEnabled returns false). If provided, the date becomes focusable.

disabledboolean

Specifies if the control is disabled, which prevents the user from modifying the value and prevents the value from being included in a form submission. A disabled control can't receive focus.

expand-to-viewportboolean

By default, the dropdown height is constrained to fit inside the height of its next scrollable container element. Enabling this property will allow the dropdown to extend beyond that container by using fixed positioning and React Portals.

Set this property if the dropdown would otherwise be constrained by a scrollable container, for example inside table and split view layouts.

We recommend you use discretion, and don't enable this property unless necessary because fixed positioning results in a slight, visible lag when scrolling complex pages.

formatDatePickerProps.Format

The format as it is displayed. It can take the following values:

• iso: ISO 8601 format without time, e.g.: 2024-01-30 (or 2024-01)
• long-localized: a more human-readable, localized format, e.g.: January 30, 2024 (or January, 2024)
• slashed: similar to ISO 8601 but with '/' in place of '-'. e.g.: 2024/01/30 (or 2024/01)

granularityCalendarProps.Granularity default: 'day'

Specifies the granularity at which users will be able to select a date. Defaults to day.

i18n-stringsDatePickerProps.I18nStrings

An object containing all the necessary localized strings required by the component.

input-formatDatePickerProps.InputFormat

Specifies the date format to use when the format is 'long-localized' and the user needs to edit the date.

The format of the input as it is being interacted with. It can take the following values:

• iso: ISO 8601 format without time, e.g.: 2024-01-30 (or 2024-01)
• slashed: similar to ISO 8601 but with '/' in place of '-'. e.g.: 2024/01/30 (or 2024/01)

is-date-enabledCalendarProps.IsDateEnabledFunction

Defines whether a particular date is enabled in the calendar or not. If you disable a date in the calendar, users can still enter this date using a keyboard. We recommend that you also validate these constraints on the client-side and server-side as you would for other form elements.

localestring default: 'en-US'

Specifies the locale to use to render month names and determine the starting day of the week. If you don't provide this, the locale is determined by the page and browser locales. Supported values and formats are listed in the JavaScript Intl API specification.

namestring

Specifies the name of the control used in HTML forms.

next-month-aria-labelstring

Specifies an aria-label for the 'next month' button.

open-calendar-aria-labelDatePickerProps.OpenCalendarAriaLabel

Specifies a function that generates the aria-label for the 'open calendar' button. The selectedDate parameter is a human-readable localised string representing the current value of the input. (for example, selectedDate => 'Choose Date' + (selectedDate ? `, selected date is ${selectedDate}` : ''))

placeholderstring default: 'YYYY/MM/DD'

Specifies the placeholder text rendered when the value is an empty string.

previous-month-aria-labelstring

Specifies an aria-label for the 'previous month' button.

read-onlyboolean default: false

Specifies if the control is read-only, which prevents the user from modifying the value but includes it in a form submission. A read-only control can receive focus.

Do not use read-only inputs outside of a form.

start-of-weeknumber default: 0

Determines the starting day of the week. The values 0-6 map to Sunday-Saturday. By default the starting day of the week is defined by the locale, but you can use this property to override it.

today-aria-labelstring

Used as part of the aria-label for today's date in the calendar.

valuestringrequired

The current input value, in YYYY-MM-DD format.

Events

blurCustomEvent<null>

Called when input focus is removed from the UI control.

changeCustomEvent<CalendarProps.ChangeDetail>

Called whenever a user changes the input value (by typing, pasting, or selecting a value). The event detail contains the current value of the field.

focusCustomEvent<null>

Called when input focus is moved to the UI control.