Skip to main contentSkip to search
Clay
  • Get Started
    • How to Use Clay
    • How to Read This Documentation
    • Composition Philosophy
    • Migrating From v2.x
    • Using Clay in JSPs
  • Components
    • Alert
    • Application Bar
    • Aspect Ratio
    • Autocomplete
    • Badge
    • Breadcrumb
    • Button Group
    • Buttons
    • Card
    • Chart
    • Color Picker
    • Data Provider
    • Date Picker
    • DropDown
    • Empty State
    • Form
      • Checkbox
      • Dual List Box
      • Input
      • Radio Group
      • Select
      • Select Box
      • Toggle Switch
    • Forms Hierarchy
    • Heading
    • Icon
    • Label
    • Layout
    • Link
    • List
    • Loading Indicator
    • Localized Input
    • Management Toolbar
    • Modal
    • Multi Select
    • Multi Step Nav
    • Nav
    • Navigation Bar
    • OverlayMask
    • Pagination
    • Pagination Bar
    • Panel
    • Picker
    • Popover
    • Progress Bar
    • Provider
    • Sidebar
    • Slider
    • Sticker
    • Table
    • Tabs
    • Text
    • Timelines
    • Time Picker
    • Toolbar
    • Tooltip
    • TreeView
    • Upper Toolbar
    • VerticalBar
    • Vertical Navigation
  • Contributing
  • CSS Framework
    • Paver
    • SCSS
    • Color
    • Grid
    • Content
      • Typography
      • C Kbd
    • Utilities
      • Accessibility
      • Autofit
      • Border
      • C Focus Inset
      • C Inner
      • Color Utilities
      • C Spacing Utilities
      • Display
      • Flex
      • Float
      • Inline Item
      • Overflow
      • Position
      • Shadow
      • Text
      • Vertical Align
      • Visibility
      • Width and Height
    • Playground
  • Examples
K
  • Docs
  • Sass API
  • Blog
  • Storybook
  • Codesandbox
  • Github
  • Use this menu to toggle between Atlas and Base Themes.

Date Picker

yarn add @clayui/date-picker

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

  • Examples
  • Markup
  • API

Stable3.91.0View in LexiconCHANGELOGstorybook demos

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

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.

WarningThese 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.

WarningYou 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.
Copied!
Code Sample (expand to see it)

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.

Copied!
Code Sample (expand to see it)

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.

WarningThe time is not supported when the range is enabled.
Copied!
Code Sample (expand to see it)

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.

Copied!
Code Sample (expand to see it)
  • 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.
WarningIt 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.

Copied!
Code Sample (expand to see it)

Programatically Expand Dropdown

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.

How can this be improved? Create an issue!