Date picker

CANARY

Component demo

Interactive example

Web component

React

<ic-date-picker
label="When would you like to collect your coffee?"
></ic-date-picker>

<IcDatePickerlabel="When would you like to collect your coffee?"/>

Date picker details

Props

All components also accept native properties supported by the DOM, such asclassName and style .

Name	Description	Default
Property label Attribute label	The label for the date input. Required type: string
Property dateFormat Attribute date-format	The format in which the date will be displayed. type: IcDateFormat - "DD/MM/YYYY" \| "MM/DD/YYYY" \| "YYYY/MM/DD"	"DD/MM/YYYY"
Property disableDays Attribute	The days of the week to disable. type: IcWeekDays[]	[]
Property disableDaysMessage Attribute disable-days-message	The text to display as the validation message when`disableDays` is`true` and a disabled date is entered. type: string	"The date you have selected is on a day of the week that is not allowed. Please select another date."
Property disableFuture Attribute disable-future	If`true` , dates in the future are not allowed. A validation message will appear if a date in the future is entered. type: boolean	false
Property disableFutureMessage Attribute disable-future-message	The text to display as the validation message when`disableFuture` is`true` and a date in the future is entered. type: string	"Dates in the future are not allowed. Please select a date in the past."
Property disablePast Attribute disable-past	If`true` , dates in the past are not allowed. A validation message will appear if a date in the past is entered. type: boolean	false
Property disablePastMessage Attribute disable-past-message	The text to display as the validation message when`disablePast` is`true` and a date in the past is entered. type: string	"Dates in the past are not allowed. Please select a date in the future."
Property disabled Attribute disabled	If`true` , the disabled state will be set. type: boolean	false
Property helperText Attribute helper-text	The helper text that will be displayed for additional field guidance. This will default to the text "Use format" along with the`dateFormat` value. type: string
Property hideHelperText Attribute hide-helper-text	If`true` , the helper text will be visually hidden, but still read out by screenreaders. type: boolean	false
Property hideLabel Attribute hide-label	If`true` , the label will be visually hidden, but the required label will still be read out by screen readers. type: boolean	false
Property inputId Attribute input-id	The ID for the input field. The default will be an automatically generated value. type: string
Property invalidDateMessage Attribute invalid-date-message	The text to display as the validation message when an invalid date is entered. type: string	"Please enter a valid date."
Property max Attribute max	The latest date that will be allowed. The value can be in any format supported as`dateFormat` , in ISO 8601 date string format (`yyyy-mm-dd` ) or as a JavaScript`Date` object. The value of this prop is ignored if`disableFuture` is set to`true` . type: string \| Date - Date \| string	""
Property min Attribute min	The earliest date that will be allowed. The value can be in any format supported as`dateFormat` , in ISO 8601 date string format (`yyyy-mm-dd` ) or as a JavaScript`Date` object. The value of this prop is ignored if`disablePast` is set to`true` . type: string \| Date - Date \| string	""
Property name Attribute name	The name of the control, which is submitted with the form data. type: string
Property openAtDate Attribute open-at-date	The date visible when the calendar opens. Used if no date is currently selected. The value can be in any format supported as`dateFormat` , in ISO 8601 date string format (`yyyy-mm-dd` ) or as a JavaScript`Date` object. type: string \| Date - Date \| string	""
Property required Attribute required	If`true` , the input will require a value. type: boolean	false
Property showDaysOutsideMonth Attribute show-days-outside-month	If`true` , days outside the current month will be visible in the date picker. type: boolean	true
Property showPickerClearButton Attribute show-picker-clear-button	If`true` , the`Clear` button on the date picker will be visible. type: boolean	true
Property showPickerTodayButton Attribute show-picker-today-button	If`true` , the`Go to today` button on the date picker will be visible. type: boolean	true
Property size Attribute size	The size of the date picker to be displayed. type: IcSizes - "large" \| "medium" \| "small"	"medium"
Property startOfWeek Attribute start-of-week	The first day of the week.`0` for Sunday,`1` for Monday, etc. Default is Monday. type: IcWeekDays - IcWeekDays.Friday \| IcWeekDays.Monday \| IcWeekDays.Saturday \| IcWeekDays.Sunday \| IcWeekDays.Thursday \| IcWeekDays.Tuesday \| IcWeekDays.Wednesday	IcWeekDays.Monday
Property validationStatus Attribute validation-status	The validation status - e.g. 'error' \| 'warning' \| 'success'. This will override the built-in date validation. type: IcInformationStatusOrEmpty - "" \| "error" \| "success" \| "warning"	""
Property validationText Attribute validation-text	The text to display as the validation message. This will override the built-in date validation. type: string	""
Property value Attribute value	The value of the date picker. The value can be in any format supported as`dateFormat` , in ISO 8601 date string format (`yyyy-mm-dd` ) or as a JavaScript`Date` object. type: string \| Date \| null \| undefined - Date \| string	""

Property

label

Attribute

label

The label for the date input.

Required

type: string

Property

dateFormat

Attribute

date-format

The format in which the date will be displayed.

type: IcDateFormat - "DD/MM/YYYY" | "MM/DD/YYYY" | "YYYY/MM/DD"

Default: "DD/MM/YYYY"

Property

disableDays

Attribute

The days of the week to disable.

type: IcWeekDays[]

Default: []

Property

disableDaysMessage

Attribute

disable-days-message

The text to display as the validation message whendisableDays istrue and a disabled date is entered.

type: string

Default: "The date you have selected is on a day of the week that is not allowed. Please select another date."

Property

disableFuture

Attribute

disable-future

Iftrue , dates in the future are not allowed. A validation message will appear if a date in the future is entered.

type: boolean

Default: false

Property

disableFutureMessage

Attribute

disable-future-message

The text to display as the validation message whendisableFuture istrue and a date in the future is entered.

type: string

Default: "Dates in the future are not allowed. Please select a date in the past."

Property

disablePast

Attribute

disable-past

Iftrue , dates in the past are not allowed. A validation message will appear if a date in the past is entered.

type: boolean

Default: false

Property

disablePastMessage

Attribute

disable-past-message

The text to display as the validation message whendisablePast istrue and a date in the past is entered.

type: string

Default: "Dates in the past are not allowed. Please select a date in the future."

Property

disabled

Attribute

disabled

Iftrue , the disabled state will be set.

type: boolean

Default: false

Property

helperText

Attribute

helper-text

The helper text that will be displayed for additional field guidance. This will default to the text "Use format" along with thedateFormat value.

type: string

Property

hideHelperText

Attribute

hide-helper-text

Iftrue , the helper text will be visually hidden, but still read out by screenreaders.

type: boolean

Default: false

Property

hideLabel

Attribute

hide-label

Iftrue , the label will be visually hidden, but the required label will still be read out by screen readers.

type: boolean

Default: false

Property

inputId

Attribute

input-id

The ID for the input field. The default will be an automatically generated value.

type: string

Property

invalidDateMessage

Attribute

invalid-date-message

The text to display as the validation message when an invalid date is entered.

type: string

Default: "Please enter a valid date."

Property

max

Attribute

max

The latest date that will be allowed. The value can be in any format supported asdateFormat , in ISO 8601 date string format (yyyy-mm-dd ) or as a JavaScriptDate object. The value of this prop is ignored ifdisableFuture is set totrue .

type: string | Date - Date | string

Default: ""

Property

min

Attribute

min

The earliest date that will be allowed. The value can be in any format supported asdateFormat , in ISO 8601 date string format (yyyy-mm-dd ) or as a JavaScriptDate object. The value of this prop is ignored ifdisablePast is set totrue .

type: string | Date - Date | string

Default: ""

Property

name

Attribute

name

The name of the control, which is submitted with the form data.

type: string

Property

openAtDate

Attribute

open-at-date

The date visible when the calendar opens. Used if no date is currently selected. The value can be in any format supported asdateFormat , in ISO 8601 date string format (yyyy-mm-dd ) or as a JavaScriptDate object.

type: string | Date - Date | string

Default: ""

Property

required

Attribute

required

Iftrue , the input will require a value.

type: boolean

Default: false

Property

showDaysOutsideMonth

Attribute

show-days-outside-month

Iftrue , days outside the current month will be visible in the date picker.

type: boolean

Default: true

Property

showPickerClearButton

Attribute

show-picker-clear-button

Iftrue , theClear button on the date picker will be visible.

type: boolean

Default: true

Property

showPickerTodayButton

Attribute

show-picker-today-button

Iftrue , theGo to today button on the date picker will be visible.

type: boolean

Default: true

Property

size

Attribute

size

The size of the date picker to be displayed.

type: IcSizes - "large" | "medium" | "small"

Default: "medium"

Property

startOfWeek

Attribute

start-of-week

The first day of the week.0 for Sunday,1 for Monday, etc. Default is Monday.

Default: IcWeekDays.Monday

Property

validationStatus

Attribute

validation-status

The validation status - e.g. 'error' | 'warning' | 'success'. This will override the built-in date validation.

type: IcInformationStatusOrEmpty - "" | "error" | "success" | "warning"

Default: ""

Property

validationText

Attribute

validation-text

The text to display as the validation message. This will override the built-in date validation.

type: string

Default: ""

Property

value

Attribute

value

The value of the date picker. The value can be in any format supported asdateFormat , in ISO 8601 date string format (yyyy-mm-dd ) or as a JavaScriptDate object.

type: string | Date | null | undefined - Date | string

Default: ""

CSS Custom Properties

Name	Description
--ic-z-index-date-picker	z-index of date picker.
--input-width	Width of the input field

--ic-z-index-date-picker z-index of date picker.

--input-width Width of the input field

Events

All components also accept native events supported by the DOM, such as onClick and onKeyDown .

Name	Description	Signature
Web component icChange React onIcChange	Emitted when the value has changed.	{ value: Date; }

Web component

icChange

React

onIcChange

Emitted when the value has changed.

{ value: Date; }

Variants

Sizes

Set the size of the date picker by using thesize prop. This prop takes the valuessmall ,medium orlarge . Depending on the chosen size, the prop will apply styling to increase or decrease the amount of spacing within the component.

Interactive example

Web component

React

<ic-date-picker
label="When would you like to collect your coffee?"
size="small"
></ic-date-picker>
<ic-date-picker
label="When would you like to collect your coffee?"
size="medium"
></ic-date-picker>
<ic-date-picker
label="When would you like to collect your coffee?"
size="large"
></ic-date-picker>

IcDatePicker
  label="When would you like to collect your coffee?"
  size="small"
/>
<IcDatePickerlabel="When would you like to collect your coffee?"/>
<IcDatePicker
label="When would you like to collect your coffee?"
size="large"
/>

Max width

Set the size of the input field by using the--input-width CSS custom property. The picker will grow, but not exceed its maximum supported width.

Interactive example

Web component

React

<ic-date-picker
label="When would you like to collect your coffee?"
size="small"
></ic-date-picker>
<ic-date-picker
label="When would you like to collect your coffee?"
size="medium"
></ic-date-picker>
<ic-date-picker
label="When would you like to collect your coffee?"
size="large"
></ic-date-picker>

<IcDatePicker
className={classes.datePicker}
label="When would you like to collect your coffee?"
size="small"
/>
<IcDatePicker
className={classes.datePicker}
label="When would you like to collect your coffee?"
/>
<IcDatePicker
className={classes.datePicker}
label="When would you like to collect your coffee?"
size="large"
/>

Disabled

Interactive example

Web component

React

<ic-date-picker
label="When would you like to collect your coffee?"
disabled="true"
></ic-date-picker>

<IcDatePicker
label="When would you like to collect your coffee?"
disabled
/>

Date formats

ThedateFormat prop determines how dates are displayed. The supported formats areDD/MM/YYYY ,MM/DD/YYYY orYYYY/MM/DD . The default format isDD/MM/YYYY .

Interactive example

Web component

React

<ic-date-pickerlabel="When would you like to collect your coffee?"></ic-date-picker>
<ic-date-pickerlabel="When would you like to collect your coffee?"date-format="MM/DD/YYYY"></ic-date-picker>
<ic-date-pickerlabel="When would you like to collect your coffee?"date-format="YYYY/MM/DD"></ic-date-picker>

<IcDatePickerlabel="When would you like to collect your coffee?"/>
<IcDatePickerlabel="When would you like to collect your coffee?"dateFormat="MM/DD/YYYY"/>
<IcDatePickerlabel="When would you like to collect your coffee?"dateFormat="YYYY/MM/DD"/>

Value

Thevalue prop sets the date in the input field. The value can be in any format supported by thedateFormat prop, in ISO 8601 date string format (yyyy-mm-dd) or as a JavaScript Date object.

Interactive example

Web component

React

<ic-date-pickerlabel="When would you like to collect your coffee?"value="01/01/2024"></ic-date-picker>

<IcDatePickerlabel="When would you like to collect your coffee?"value="01/01/2024"/>

Open at date

If novalue is set, theopenAtDate prop can be used to specify the date in view when the calendar view is opened. If not set to a value, the calendar will default to showing the current date.

The supported formats are the same as for thevalue prop.

Interactive example

Web component

React

<ic-date-pickerlabel="When would you like to collect your coffee?"helper-text="The calendar will open showing 25th December 2024, if no date selected"open-at-date="2024-12-25"></ic-date-picker>

<IcDatePickerlabel="When would you like to collect your coffee?"helperText="The calendar will open showing 25th December 2024, if no date selected"openAtDate="2024-12-25"/>

Start of week

The first day of the week can be changed by setting thestartOfWeek prop. This is a numeric value where 0 = Sunday, 1 = Monday, etc. up to 6 = Saturday.

Interactive example

Web component

React

<ic-date-pickerlabel="When would you like to collect your coffee?"start-of-week="0"></ic-date-picker>

<IcDatePickerlabel="When would you like to collect your coffee?"startOfWeek={0}/>

Disable days of week

Specific days of the week can be disabled from selection by setting thedisableDays prop. The value can be set as an array of numeric values where 0 = Sunday, 1 = Monday, etc. up to 6 = Saturday.

Interactive example

Web component

React

<ic-date-pickerid="weekday-picker"label="When would you like to collect your coffee?"></ic-date-picker>

<IcDatePickerlabel="When would you like to collect your coffee?"disableDays={disabledDaysOfWeek}/>

Max and min

Themax andmin props can be used to limit the range of dates available for selection. Values can be in any format supported by thedateFormat prop, in ISO 8601 date string format (yyyy-mm-dd) or as a JavaScript Date object.

Interactive example

Web component

React

<ic-date-pickerlabel="When would you like to collect your coffee?"helper-text="Choose a date between the 1st and 31st of July"min="2024-07-01"max="2024-07-31"show-picker-today-button="false"></ic-date-picker>

<IcDatePickerlabel="When would you like to collect your coffee?"helperText="Choose a date between the 1st and 31st of July"min="2024-07-01"max="2024-07-31"showPickerTodayButton={false}/>

Disable dates in past

Dates before today can be disabled with thedisablePast prop.

Interactive example

Web component

React

<ic-date-pickerlabel="When would you like to collect your coffee?"disable-past="true"></ic-date-picker>

<IcDatePickerlabel="When would you like to collect your coffee?"disablePast/>

Disable dates in future

Dates after today can be disabled with thedisableFuture prop.

Interactive example

Web component

React

<ic-date-pickerlabel="When would you like to collect your coffee?"disable-future="true"></ic-date-picker>

<IcDatePickerlabel="When would you like to collect your coffee?"disableFuture/>

Days outside month hidden

Days outside of the current month in view can be hidden by setting theshowDaysOutsideMonth prop tofalse .

Interactive example

Web component

React

<ic-date-pickerlabel="When would you like to collect your coffee?"show-days-outside-month="false"></ic-date-picker>

<IcDatePickerlabel="When would you like to collect your coffee?"showDaysOutsideMonth={false}/>

Today and clear buttons hidden

The 'Go to today' and 'Clear' buttons can be hidden from the calendar view by setting theshowPickerTodayButton andshowPickerClearButton props tofalse .

Interactive example

Web component

React

<ic-date-pickerlabel="When would you like to collect your coffee?"show-picker-today-button="false"show-picker-clear-button="false"></ic-date-picker>

<IcDatePickerlabel="When would you like to collect your coffee?"showPickerTodayButton={false}showPickerClearButton={false}/>

Javascript dates

Any prop that accepts a date value can be set to a Javascript Date object. The following example sets thevalue ,max andmin props.

Interactive example

Web component

React

<ic-date-picker
id="js-date-picker"
label="When would you like to collect your coffee?"
helper-text="Choose a date between the 1st and 31st of July"
show-picker-today-button="false"
></ic-date-picker>

<IcDatePicker
label="When would you like to collect your coffee?"
min={newDate(2024,6,1)}
max={newDate(2024,6,31)}
value={newDate(2024,6,15)}
helperText="Choose a date between the 1st and 31st of July"
showPickerTodayButton={false}
/>

IcChange Event

TheIcChange event is emitted by the date picker when the selected date changes.

Interactive example

Selected date:

Web component

React

<ic-date-picker
id="ic-change-date-picker"
label="When would you like to collect your coffee?"
></ic-date-picker>
<spanid="selected-date">
  Selected date:
</span>

<IcDatePicker
label="When would you like to collect your coffee?"
onIcChange={dateChangedHandler}
value={value}
/>
<span>
{selectedDate}
</span>

Last reviewed 31 May 2024 .