Date Picker

Date and Time pickers let users select a date and time for a form.

install	yarn add @clayui/date-picker
version
use	`import DatePicker from '@clayui/date-picker';`

Table of Contents

Time
Range
Internationalization
Custom Footer
Programatically Expand Dropdown
Note about Moment.js
API Reference

Date Picker is created following the principles of Lexicon, Internationalization and Extension Points by default is integrated with Time Picker that offers the minimum of features to set a time.

By default Date Picker does not handle input masking, letting you take control so you can take care of internationalization. Date Picker will update the Calendar only when the value entered in the input is a valid date, respecting the dateFormat API.

For mobile viewing mode, Lexicon encourages you to use the native Date Picker, they are many robust and more accessible in the mobile view, Clay offers the useNative API to replace the Date Picker view mode with the native and continue to get the features of the component.

Warning These components are meant to cover desktop browser needs. The OS native component must be used on mobile devices.

The component is treated as controlled, use the onValueChange and value APIs to control the flow of information.

Warning You can set a range of years using the API


years

, which can be displayed in the Date Picker, if the user enters a year that is not within the range will be treated as an invalid date.

import {Provider} from '@clayui/core';
import DatePicker from '@clayui/date-picker';
import React from 'react';

export default function App() {
  const [value, setValue] = React.useState(null);

  return (
    <Provider spritemap="/icons.svg">
      <div className="p-4">
        <DatePicker
          onChange={setValue}
          placeholder="YYYY-MM-DD"
          value={value}
          years={{
            end: new Date().getFullYear(),
            start: 1997,
          }}
        />
      </div>
    </Provider>
  );
}

Time

The ClayTimePicker by default is already implemented in the Date Picker, you can enable it using the time API. To provide a context for the timezone user, use the timezone API for this.

import {Provider} from '@clayui/core';
import DatePicker from '@clayui/date-picker';
import React from 'react';

export default function App() {
  const [value, setValue] = React.useState(null);

  return (
    <Provider spritemap="/icons.svg">
      <div className="p-4">
        <DatePicker
          onChange={setValue}
          placeholder="YYYY-MM-DD HH:mm"
          time
          timezone="GMT+01:00"
          value={value}
          years={{
            end: new Date().getFullYear(),
            start: 2008,
          }}
        />
      </div>
    </Provider>
  );
}

Range

Range is used to allowing the user to select a date range using a single calendar. The user can interact in the single input to select the start and end dates using the - separator, the separator is fixed.

When a range is selected using the input or the calendar, the onValueChange callback is called with the value in string type, respecting the format of the dateFormat for both dates together with the separator.

Warning The time is not supported when the


range

is enabled.

import {Provider} from '@clayui/core';
import DatePicker from '@clayui/date-picker';
import React from 'react';

export default function App() {
  const [value, setValue] = React.useState(null);

  return (
    <Provider spritemap="/icons.svg">
      <div className="p-4">
        <DatePicker
          onChange={setValue}
          placeholder="YYYY-MM-DD - YYYY-MM-DD"
          range
          value={value}
          years={{
            end: new Date().getFullYear(),
            start: 1997,
          }}
        />
      </div>
    </Provider>
  );
}

Internationalization

To set internationalization of the component, you need to configure the props according to the language. Date Picker offers low level APIs to configure firstDayOfWeek, weekdaysShort, months, timezone and dateFormat, you can follow the example below to set up a Date Picker for Russian.

import {Provider} from '@clayui/core';
import DatePicker from '@clayui/date-picker';
import React from 'react';

export default function App() {
  const [value, setValue] = React.useState(null);

  return (
    <Provider spritemap="/icons.svg">
      <div className="p-4">
        <DatePicker
          dateFormat="dd.MM.yyyy"
          firstDayOfWeek={1}
          months={[
            'Январь',
            'Февраль',
            'Март',
            'Апрель',
            'Май',
            'Июнь',
            'Июль',
            'Август',
            'Сентябрь',
            'Октябрь',
            'Ноябрь',
            'Декабрь',
          ]}
          onChange={setValue}
          placeholder="DD.MM.YYYY"
          value={value}
          weekdaysShort={['Вс', 'Пн', 'Вт', 'Ср', 'Чт', 'Пт', 'Сб']}
          years={{
            end: new Date().getFullYear(),
            start: 2008,
          }}
        />
      </div>
    </Provider>
  );
}

firstDayOfWeek by default the value by default the value is 0 (Sunday) and its values are the days of the week, 1 (Monday), 2 (Tuesday), 3 (Wednesday), 4 (Thursday), 5 (Friday), 6 (Saturday).
dateFormat and timeFormat is defined according to the formatting rules of date-fns which is an implementation of the unicode technical standards .
months is an Array<string> with available months starting January to December .
weekdaysShort is an Array<string> with the names of the days of the week in short form , starting from Sunday to Saturday .

Warning It is not necessary to reverse or change the order of the values of


weekdaysShort

the definition of the API


firstDayOfWeek

will take care of changing this, keep the order from Sunday to Saturday .

Custom Footer

To customize the Date Picker content footer you can use the footerElement API, its type is a Function that should return an element (Read more about renders props), this personalization point is treated as an extension point in the Lexicon language.

import {Provider} from '@clayui/core';
import DatePicker from '@clayui/date-picker';
import React from 'react';

export default function App() {
  const [value, setValue] = React.useState(null);

  return (
    <Provider spritemap="/icons.svg">
      <div className="p-4">
        <DatePicker
          footerElement={() => <span>Footer Content</span>}
          onChange={setValue}
          placeholder="YYYY-MM-DD"
          value={value}
          years={{
            end: new Date().getFullYear(),
            start: 2008,
          }}
        />
      </div>
    </Provider>
  );
}

If you want to expand or close the picker from outside of the component, use the props expand and onExpandChange.

Note about Moment.js

In version 3.4.0, we made the decision to switch to use date-fns instead of Moment.js due to dependency size. Making this changed help reduce the size of @clayui/date-picker by almost 50 KB.

API Reference

DatePicker

React.ForwardRefExoticComponent<IProps & React.RefAttributes<HTMLInputElement>>

Parameters

Properties

ariaLabels

IAriaLabels | undefined

Labels for the aria attributes

dateFormat

string | undefined

Set the format of how the date will appear in the input element. See available: https://date-fns.org/v2.14.0/docs/format

defaultExpanded

boolean | undefined

Property to set if expanded by default (uncontrolled).

defaultMonth

Date | undefined

The start date to be displayed on the calendar as “Today”. Used to mark the start date of the day and when resetting.

defaultValue

string | undefined

Property to set the default value (uncontrolled).

disabled

boolean | undefined

Flag to disable the component, buttons, open the datepicker, etc…

expanded

boolean | undefined

Determines if menu is expanded or not (controlled).

firstDayOfWeek

FirstDayOfWeek | undefined

Set the first day of the week, starting from 0 (Sunday) to 6 (Saturday).

footerElement

((object: { spritemap?: string; }) => React.ReactNode) | undefined

Function that should return the React element to render on the datepicker footer.

id

string | undefined

Id to be applied to the element.

Deprecated

initialExpanded

boolean | undefined

Flag to indicate if date is initially expanded when expand and onExpandChange are not being used.

Deprecated

initialMonth

Date | undefined

The start date to be displayed on the calendar as “Today”. Used to mark the start date of the day and when resetting.

inputName

string | undefined

Name of the input.

months

Array<string> | undefined

The names of the months.

onChange

InternalDispatch<string> | undefined

Callback that is called when the value changes (controlled).

onExpandedChange

InternalDispatch<boolean> | undefined

Callback for when dropdown changes its expanded state (controlled).

onNavigation

((data: Date) => void) | undefined

Called when the user is browsing the date picker, changing the month, year and navigating with arrows.

Deprecated

onValueChange

InternalDispatch<string> | undefined

Called when the input change.

Second argument gives the type that caused the value change

placeholder

string | undefined

Describe a brief tip to help users interact.

range

boolean | undefined

Flag to indicate the user will use the date-range date-picker

spritemap

string | undefined

Path to the location of the spritemap resource.

time

boolean | undefined

Flag to enable datetime selection.

timezone

string | undefined

Flag to indicate the timezone of the Time Picker.

use12Hours

boolean | undefined

Flag to indicate if 12-hour use, when true, should show am/pm input.

useNative

boolean | undefined

Flag to indicate whether to use native date picker

value

string | undefined

The value property sets the current value (controlled).

weekdaysShort

Array<string> | undefined

Short names of days of the week to use in the header of the month. It should start from Sunday.

years

{ end: number; start: number; } | undefined

List of years available for navigation within the selector.

yearsCheck

boolean | undefined

Flag to indicate whether the DatePicker should validate if the year is included in the range of years. Disable only if your range is dynamic.

Returns

ReactElement<any, string | JSXElementConstructor<any>> | null

Edit this page on GitHub

Contributors

Matuzalém Teles, Bryce Osterhaus, Diego Nascimento, Krešimir Čoko, Ilza Medeiros

Last edited May 11, 2025 at 5:57:01 PM

Table of Contents

Time
Range
Internationalization
Custom Footer
Programatically Expand Dropdown
Note about Moment.js
API Reference

Date Picker

Time

Range

Internationalization

Custom Footer

Programatically Expand Dropdown

Note about Moment.js

API Reference

DatePicker

Parameters

Properties

ariaLabels

dateFormat

defaultExpanded

defaultMonth

defaultValue

disabled

expanded

firstDayOfWeek

footerElement

id

initialExpanded

initialMonth

inputName

months

onChange

onExpandedChange

onNavigation

onValueChange

placeholder

range

spritemap

time

timezone

use12Hours

useNative

value

weekdaysShort

years

yearsCheck

Returns