DatePicker

This component can display past, present, or future dates relevant to a task. Whilst this component is useful for selecting a range of dates, we recommend using DateInput for collecting data like date of birth.

Basic usage


import { DatePicker } from '@krakentech/coral';
 
<DatePicker label="Date Picker" />

Date Picker

Properties

disablePast / disableFuture

Use the disablePast flag if you need to disable past dates and the disableFuture flag if you need to disable future dates.


<DatePicker label="Disable Past" disablePast />
<DatePicker label="Disable Future" disableFuture />

Disable Past

Disable Future

disabled


<DatePicker disabled />

Disabled

defaultMonth

Customise the date that the calender opens to initially.


<DatePicker label="Date Picker" defaultMonth={new Date(2023, 11)} />

Date Picker

endIcon


<DatePicker label="With End Icon" endIcon={<IconCross />} />

With End Icon

startIcon


<DatePicker label="With Start Icon" startIcon={<IconCross />} />

With Start Icon

error / errorMessage

Analogous to the TextField component, the error flag and errorMessage prop are used for controlling error behaviour.


<DatePicker
    label="Date Picker"
    error
    errorMessage="Some generic error message."
/>

Date Picker

Some generic error message.

excludeDateIntervals

The excludeDateIntervals props provide a very convenient interface for excluding multiple date intervals.


const daysFromNow = (days: number) => {
    const today = new Date();
    return new Date(today.getTime() + days * 24 * 60 * 60 * 1000);
};
 
<DatePicker
    label="Date Picker"
    excludeDateIntervals={[
        { start: daysFromNow(-2), end: daysFromNow(2) },
        { start: daysFromNow(5), end: daysFromNow(8) },
    ]}
/>

Date Picker

excludeDates

The excludeDates props provide a very convenient interface for excluding specific dates.


<DatePicker
    label="Date Picker"
    excludeDates={[daysFromNow(-8), daysFromNow(-10)]}
/>

Date Picker

fullWidth


<DatePicker label="Date Picker" fullWidth />

Date Picker

includeDateIntervals

You can use includeDateIntervals if you want specific date spans to be allowed.


<DatePicker
    label="Date Picker"
    includeDateIntervals={[
        { start: daysFromNow(-2), end: daysFromNow(2) },
        { start: daysFromNow(5), end: daysFromNow(8) },
    ]}
/>

Date Picker

includeDates

You can use includeDates and includeDateIntervals if you want specific dates or date spans to be allowed.


<DatePicker
    label="Date Picker"
    includeDates={[daysFromNow(-1), daysFromNow(1), daysFromNow(3)]}
/>

Date Picker

isClearable


<DatePicker label="Date Picker" isClearable />

Date Picker

locale


<DatePicker label="Germany 🇩🇪" locale="de" />
<DatePicker label="Spain 🇪🇸" locale="es" />
<DatePicker label="France 🇫🇷" locale="fr" />
<DatePicker label="Italy 🇮🇹" locale="it" />
<DatePicker label="Japan 🇯🇵" locale="ja" />

Germany 🇩🇪

Spain 🇪🇸

France 🇫🇷

Italy 🇮🇹

Japan 🇯🇵

minDate / maxDate

The minDate and maxDate props are used to configure a valid time window.


<DatePicker
    label="Date Picker"
    minDate={daysFromNow(-12)}
    maxDate={daysFromNow(12)}
/>

Date Picker

open


const WithOpen = (args: DatePickerProps) => {
    const [open, setOpen] = useState(false);
 
    return (
        <Stack>
            <DatePicker
                label="Date Picker"
                open={open}
                onSelect={() => setOpen(false)}
            />
            <Button size="small" onClick={() => setOpen(!open)}>
                {open ? 'Close Datepicker' : 'Open Datepicker'}
            </Button>
        </Stack>
    );
};

Date Picker

theme


<Container padding="md" theme="base100">
    <DatePicker label="Theme: secondary500" theme="secondary500" />
</Container>

Theme: secondary500

placeholderText


<DatePicker label="Date Picker" placeholderText="Enter a date" />

Date Picker

popperPlacement


<DatePicker label="Date Picker" popperPlacement="auto" />

Date Picker

optional


<DatePicker label="Date Picker" optional />

Date Picker (optional)

selectsRange


<DatePicker label="Date Picker" selectsRange />

Date Picker

shouldCloseOnSelect


<DatePicker label="Date Picker" shouldCloseOnSelect />

Date Picker

showYearPicker


<DatePicker label="Year range picker" showYearPicker selectsRange />
<DatePicker label="Year picker" showYearPicker />
<DatePicker label="Year picker with disabled past" showYearPicker disablePast={true} />

Year range picker

Year picker

Year picker with disabled past

Accessibility

aria-labels


<DatePicker
    label="Date Picker"
    nextMonthButtonLabel="Next Month"
    nextYearButtonLabel="Next Year"
    previousMonthButtonLabel="Previous Month"
    previousYearButtonLabel="Previous Year"
/>

Date Picker

User Events


<DatePicker 
    onBlur={() => {}} 
    onCalendarClose={() => {}}
    onCalendarOpen={() => {}}
    onChange={(date) => {}}
    onClickOutside={(event) => {}}
    onFocus={(event) => {}}
    onInputClick={() => {}}
    onKeyDown={(event) => {}}
    onMonthChange={(date) => {}}
    onSelect={(date, event) => {}}
    ...
/>

Responsiveness


<Container padding="md" theme={{ base: "base900", lg: "base100" }}>
    <DatePicker
        label="Responsive"
        fullWidth={{ base: false, lg: true }}
        theme={{ base: "base100", lg: "secondary500" }}
    />
</Container>

Responsive

Full API

Name	Type	Default
`disabled`	`boolean` If `true`, the component will be disabled and not respond to user interactions.	`false`
`disableFuture`	`boolean` If `true`, future dates will be disabled.	`false`
`disablePast`	`boolean` If `true`, past dates will be disabled.	`false`
`defaultMonth`	`Date` The default month to display when the DatePicker is opened.
`endIcon`	`ReactNode` The icon displayed at the end of the DatePicker input.
`error`	`boolean` If `true`, the component will have error styling set.	`false`
`errorMessage`	`string` If set, the `ErrorMessage` component will be rendered below the input with this text.	`'Invalid input'`
`excludeDateIntervals`	`{ start: Date; end: Date; }[]` A list of date intervals to exclude from selection. Each interval is defined by a start and end date.	`[]`
`excludeDates`	`Date[]` A list of dates to exclude from selection.	`[]`
`fullWidth`	`ResponsiveVariant<boolean>` If `true`, the input will take up the full width of its container.
`id`	`string` The id of the input element. If unspecified, an id will be generated internally.
`includeDateIntervals`	`{ start: Date; end: Date; }[]` A list of date intervals to include from selection. Each interval is defined by a start and end date.	`[]`
`includeDates`	`Date[]` A list of dates to include from selection.	`[]`
`isClearable`	`boolean` If `true`, the input will be clearable, allowing users to remove the selected date. This will render a clear button inside the input field.	`false`
`label`	`string` The label for the DatePicker input field.
`locale`	`SupportedLocale` The locale to use for formatting dates.	`en-GB`
`maxDate`	`Date \| null` The maximum date allowed for selection.
`minDate`	`Date \| null` The minimum date allowed for selection.
`name`	`string` The field name used on the POST request when the form is submitted.
`nextMonthButtonLabel`	`string` The aria-label for the DatePicker’s next month button.	`'Next month'`
`nextYearButtonLabel`	`string` The aria-label for the DatePicker’s next year button.	`'Next year'`
`numberOfMonths`	`number` The number of months to display in the DatePicker.
`onBlur`	`FocusEventHandler<HTMLInputElement>` Callback fired when the input loses user focus. `event` The focus event source of the callback.
`onCalendarClose`	`() => void` Callback fired when the calendar popup is closed.
`onCalendarOpen`	`() => void` Callback fired when the calendar popup is opened.
`onChange`	`(date: Date \| DateRange \| null) => void` Callback fired when the selected date changes. `date` The selected date or date range, depending on the `selectsRange` prop.
`onClickOutside`	`(event: Event \| undefined) => void` Callback fired when the user clicks outside the DatePicker. `event` The event source of the callback
`onFocus`	`(event: Event \| undefined) => void` Callback fired when the DatePicker input gains user focus. `event` The focus event source of the callback.
`onInputClick`	`() => void` Callback fired when the DatePicker input is clicked.
`onKeyDown`	`(event: KeyboardEvent<HTMLDivElement>) => void` Callback fired when a key is pressed down on the DatePicker input.
`onMonthChange`	`(date: Date) => void` Callback fired when the month is changed. `date` The new month date.
`onSelect`	`(date: Date, event: Event \| undefined) => void` Callback fired when a date is selected. `date` The selected date. `event` The event source of the callback.
`open`	`boolean` If `true`, the DatePicker will be opened by default when rendered.
`theme`	`ResponsiveVariant<SharedThemeTypes>` The colourway applied to this component.	`'base100'`
`placeholderText`	`string` The placeholder text for the input field.
`popperPlacement`	`Placement` Position of the popper relative to the input.
`previousMonthButtonLabel`	`string` The aria-label for the DatePicker’s previous month button.	`'Previous month'`
`previousYearButtonLabel`	`string` The aria-label for the DatePicker’s previous year button.	`'Previous year'`
`optional`	`boolean` Add an optional flag to the label for this field (controlled by https://coral-oe.vercel.app/?path=/docs/guides-configuration—docs#overrides-optional-indicator optionalIndicator). This should be set to true if you have set this field to be optional in your validation schema.	`false`
`selectsRange`	`boolean` If `true`, the DatePicker will allow selecting a range of dates.	`false`
`shouldCloseOnSelect`	`boolean` If `true`, the DatePicker will close the calendar popup when a date is selected.	`true`
`showYearPicker`	`boolean` If `true`, the DatePicker will show a year picker rather than a month picker.	`false`
`showYearDropdown`	`boolean` If `true`, the DatePicker will show a year dropdown for selecting years.	`false`
`startIcon`	`ReactNode` The icon displayed at the start of the DatePicker input field.
`tabIndex`	`number` The tab index for the DatePicker input.
`title`	`string` The label title for the DatePicker input.
`valueInput`	`string \| Date \| DateRange \| null` Provides external control over the `input` state. This is the value that is displayed in the input field, and should match the value set in `valueDate`.
`valueDate`	`Date \| DateRange \| null` Provides external control over the `date` state. Depending on if the picker is used in single or range mode this value may be a single Date or a Date range array.
`yearDropdownItemNumber`	`number` The number of items which are displayed in the year dropdown in each direction.	`100`
`upLevelButtonLabel`	`string` The aria-label for the button that moves back to calendar view from Month or Year view.	`'Back to Calendar'`
`monthSelectionLabel`	`string` The aria-label for the manual month selection.	`'Select Month'`
`yearSelectionLabel`	`string` The aria-label for the manual year selection.	`'Select Year'`
`datesTableLabel`	`ReactNode`
`monthsTableLabel`	`ReactNode`
`yearsTableLabel`	`ReactNode`

Design

Good to know

Choose a date picker if you need or want the user to select a date in the past, present or future this could include. This can also include a date range. The date picker is partnered with a text field, this means the user can manually input the date or select it from the calendar to avoid manual error.

How does it work?

When text field is clicked the calendar appears below. This allows you to interact with it or manually input the desired date. Once a date or date range is selected the text field automatically fills and the calendar disappears.

How do I navigate date, month and year?

The day you simply select from the calendar. The ‘down’ chevron allows you to see the various years (in 12 year groups). The ‘left’ and ‘right’ chevrons allow you to navigate the months on the existing year.

Component breakdown

Corner radius: 12px
Fill colour: Blueberry and Ink
Text colour: Ice and Purple Haze
Title: H6
Days: Caption text
Dates/Years: Body Text 2