DatePicker

Source@react-form-builder/components-material-ui

Installation

Use the following command to install the package:

npm install @react-form-builder/components-material-ui

The DatePicker component uses additional dependencies to handle dates. Install them if your package manager does not install peer dependencies automatically.

npm install @mui/x-date-pickers dayjs

Introduction

The DatePicker component provides a calendar interface for users to select a date. It offers a user-friendly way to input dates with proper validation, localization support, and Material Design styling. The component includes features like date range restrictions, different views (day, month, year), and various display options.

The DatePicker component is based on Material UI X DatePicker. It is included within the following NPM package: @react-form-builder/components-material-ui.

The component uses Day.js for date manipulation and supports customizable date formats through the format property. Date values should be provided as strings in the specified format or as ISO 8601 strings that can be parsed by Day.js.

The DatePicker component can be configured to fit specific requirements using the properties described below.

Main properties

The following general properties are available within the Main tab:

Basic configuration

Name	Type	Description	Default
Label	string	Text label displayed above the date picker field	-
Disabled	boolean	If true, the date picker is disabled and cannot be interacted with	false
Error	boolean	Applies error styling to the field to indicate an invalid value	false
Helper text	string	Helper text displayed below the field to provide additional context or validation messages	-
Required	boolean	If true, the field is marked as required (adds an asterisk to the label)	false
Value	date	The currently selected date value (must be a valid date)	-
Format	string	Date format string used for display and parsing (e.g., "yyyy-MM-dd", "MM/dd/yyyy")	-
Read only	boolean	If true, the date picker is read-only and cannot be edited	false
Auto focus	boolean	If true, automatically focuses the date picker when the component mounts	false
Name	string	The name attribute for the form field, used when submitting forms	-

Date restrictions

Name	Type	Description	Default
Min date	date	Earliest date that can be selected (inclusive)	-
Max date	date	Latest date that can be selected (inclusive)	-
Disable past	boolean	If true, prevents selection of dates before the current date	false
Disable future	boolean	If true, prevents selection of dates after the current date	false
Reference date	date	Date used to generate the initial calendar view when no value is selected	-
Default value	date	Initial date value when the component is first rendered (if no value is set)	-

Display and behavior

Name	Type	Description	Default
Close on select	boolean	Closes the date picker dialog automatically after a date is selected	true
Display week number	boolean	Shows week numbers in the calendar view	false
Show days outside current month	boolean	Displays days from the previous and next months in the current month view	false
View	choice	The initial view to display (day, month, or year calendar)	-
Views	choice	The available views (day, month, and year calendar)	-
Open to	choice	The view to open when the picker is activated	-
Format density	choice	Controls spacing in date formatting: dense (compact) or spacious (more spacing)	dense
Fixed week number	number	Fixed number of weeks to display (forces consistent calendar height)	-
Months per row	number	Number of month calendars to display per row in month/year views	-
Years per row	number	Number of year items to display per row in year view	-
Years order	choice	Sorting order of years: ascending (oldest first) or descending (newest first)	asc

State and interaction

Name	Type	Description	Default
Loading	boolean	If true, displays a loading spinner indicating data is being loaded	false
Open	boolean	If true, the date picker dialog is open; can be used for controlled state management	false
Disable open picker	boolean	If true, prevents opening the picker dialog (useful for read-only display)	false
Disable highlight today	boolean	If true, disables the visual highlighting of the current date in the calendar	false
Desktop mode media query	string	CSS media query string that determines when to switch to desktop mode layout	-

Event handlers

Name	Type	Description
onChange	event	Fired when the date value changes
onAccept	event	Fired when a date is accepted (e.g., on Enter key press or when clicking "OK")
onClose	event	Fired when the picker dialog closes
onError	event	Fired when date validation fails
onMonthChange	event	Fired when the month view changes
onOpen	event	Fired when the picker dialog opens
onSelectedSectionsChange	event	Fired when selected sections in the input field change
onViewChange	event	Fired when the view (day/month/year) changes
onYearChange	event	Fired when the year view changes

At the bottom of the Main properties menu, you can find additional options:

• Render When: Provides conditional rendering for your component as described in the corresponding chapter.
• HTML attributes: Allows you to provide custom HTML attributes for your form.

Style properties

These are properties that allow to customize the size, color and other style properties of your component:

• For Device: You can provide component's style customization for all devices or specific devices by using this dropdown list. Refer to Adaptive Layout for more details.

• Component > Class Name: Add a class name for your component for the subsequent styling if necessary.

• Wrapper: The options below enable you to tailor the appearance of your component and customize it for a specific device type, as selected in the For Device property:

  Name	Type	Description
  Width	number	Specifies the width for your component
  Height	number	Specifies the height for your component
  Margin top/right/bottom/left	number	Margin values for you component
  Color	string	Allows customizing the text color
  Background color	string	Enables customizing the background color

Localization Setup

The DatePicker component supports multiple languages through Day.js locales. To enable localization:

1. Import the required Day.js locales in your application:

import 'dayjs/locale/en.js'
import 'dayjs/locale/de.js'
import 'dayjs/locale/ar.js'
import 'dayjs/locale/it.js'
import 'dayjs/locale/fa.js'
import 'dayjs/locale/fr.js'
import 'dayjs/locale/hi.js'
import 'dayjs/locale/es.js'
import 'dayjs/locale/ja.js'
import 'dayjs/locale/ko.js'
import 'dayjs/locale/sr.js'
import 'dayjs/locale/zh.js'

note

You only need to import the locales that your application actually uses. Importing unnecessary locales will increase your bundle size.

2. Wrap your form builder or viewer with MuiLocalizationProvider:

import {BuilderView} from '@react-form-builder/core'
import {components, MuiViewerWrapper, MuiLocalizationProvider} from '@react-form-builder/components-material-ui'

const builderView = new BuilderView(components)
  .withViewerWrapper(MuiViewerWrapper)
  .withViewerWrapper(MuiLocalizationProvider)

The MuiLocalizationProvider automatically detects the current language from the form context and applies the appropriate locale to all date pickers. If no language is specified, it defaults to English (en).

Supported Locales

The DatePicker component supports the following locales out of the box:

• English (en)
• German (de)
• Arabic (ar)
• Italian (it)
• Persian (fa)
• French (fr)
• Hindi (hi)
• Spanish (es)
• Japanese (ja)
• Korean (ko)
• Serbian (sr)
• Chinese (zh)

To add support for additional locales, import the corresponding Day.js locale file and ensure it's available in your application bundle.