DateTimePicker

23 Sep 202513 minutes to read

Represents the DateTimePicker component that allows user to select
or enter a date time value.

<input id="dateTimePicker"/>
<script>
  let dateTimePickerObject:DateTimePicker = new DateTimePicker({ value: new Date() });
  dateTimePickerObject.appendTo("#dateTimePicker");
</script>

Properties

allowEdit boolean

Support for allowEdit has been provided from
v16.2.46.
Specifies whether the input textbox is editable or not. Here the user can select the value from the
popup and cannot edit in the input textbox.

Defaults to true

calendarMode CalendarType

Gets or sets the Calendar’s Type like gregorian or islamic.

Defaults to Gregorian

cssClass string

Specifies the root CSS class of the DatePicker that allows to
customize the appearance by overriding the styles.

Defaults to null

dayHeaderFormat DayHeaderFormats

Specifies the format of the day that to be displayed in header. By default, the format is ‘short’.
Possible formats are:

  • Short - Sets the short format of day name (like Su ) in day header.
  • Narrow - Sets the single character of day name (like S ) in day header.
  • Abbreviated - Sets the min format of day name (like Sun ) in day header.
  • Wide - Sets the long format of day name (like Sunday ) in day header.

Defaults to Short

depth CalendarView

Sets the maximum level of view such as month, year, and decade in the Calendar.
Depth view should be smaller than the start view to restrict its view navigation.

Defaults to Month<table><tr><td colSpan=1 rowSpan=1>view
</td><td colSpan=1 rowSpan=1>Description
</td></tr><tr><td colSpan=1 rowSpan=1>Month
</td><td colSpan=1 rowSpan=1>Calendar view shows up to the days of the month.
</td></tr><tr><td colSpan=1 rowSpan=1>Year
</td><td colSpan=1 rowSpan=1>Calendar view shows up to the months of the year.
</td></tr><tr><td colSpan=1 rowSpan=1>Decade
</td><td colSpan=1 rowSpan=1>Calendar view shows up to the years of the decade.
</td></tr></table>> For more details about depth refer to calendarViewdocumentation.

enableMask boolean

Specifies whether it is a masked datetimepicker or not.
By default the datetimepicker component render without masked input.
If you need masked datetimepicker input then specify it as true.

Defaults to false

enablePersistence boolean

Enable or disable persisting component’s state between page reloads. If enabled, following list of states will be persisted.

  1. value

Defaults to false

enableRtl boolean

Enable or disable rendering component in right to left direction.

Defaults to false

enabled boolean

Specifies the component to be disabled or not.

Defaults to true

firstDayOfWeek number

Gets or sets the Calendar’s first day of the week. By default, the first day of the week will be based on the current culture.

Defaults to 0

floatLabelType FloatLabelType|string

Specifies the placeholder text to be floated.
Possible values are:
Never: The label will never float in the input when the placeholder is available.
Always: The floating label will always float above the input.
Auto: The floating label will float above the input after focusing or entering a value in the input.

Defaults to Syncfusion.EJ2.Inputs.FloatLabelType.Never

format string|FormatObject

Specifies the format of the value that to be displayed in component. By default, the format is based on the culture. You can set
the format to “format:’dd/MM/yyyy hh:mm’” or “format:{skeleton:’medium’}” either in string or object.

To know more about the date format standards, refer to the Internationalization Date Format
Internationalization section.

Defaults to null

fullScreenMode boolean

Specifies the component popup display full screen in mobile devices.

Defaults to false

htmlAttributes { : }

You can add the additional html attributes such as disabled, value etc., to the element.
If you configured both property and equivalent html attribute then the component considers the property value.

<input id="datetimepicker" type="text">
import { DateTimePicker } from '@syncfusion/ej2-calendars';

let datetimepicker: DateTimePicker = new DateTimePicker({
  htmlAttributes:  { name: "appointment", placeholder:"Select a date and time" }
});
datetimepicker.appendTo('#datetimepicker');

Defaults to {}

inputFormats string[]|FormatObject[]

Specifies an array of acceptable date input formats for parsing user input.

Defaults to null

keyConfigs { : }

Customizes the key actions in DateTimePicker.
For example, when using German keyboard, the key actions can be customized using these shortcuts.
Input Navigation

Key action
 Key
altUpArrow
 alt+uparrow
altDownArrow
 alt+downarrow
escape
 escape

Calendar Navigation (Use the following list of keys to navigate the currently focused Calendar after the popup has opened).

Key action
 Key
controlUp
 ctrl+38
controlDown
 ctrl+40
moveDown
 downarrow
moveUp
 uparrow
moveLeft
 leftarrow
moveRight
 rightarrow
select
 enter
home
 home
end
 end
pageUp
 pageup
pageDown
 pagedown
shiftPageUp
 shift+pageup
shiftPageDown
 shift+pagedown
controlHome
 ctrl+home
controlEnd
 ctrl+end
altUpArrow
 alt+uparrow
spacebar
 space
altRightArrow
 alt+rightarrow
altLeftArrow
 alt+leftarrow

TimePicker Navigation (Use the below list of shortcut keys to interact with the TimePicker after the TimePicker Popup has opened).

Key action
 Key
down
 downarrow
up
 uparrow
left
 leftarrow
right
 rightarrow
 
<input id="datetimepicker" type="text">
import { DateTimePicker } from '@syncfusion/ej2-calendars';

let datetimepicker: DateTimePicker = new DateTimePicker({
    keyConfigs: { 
    select: "space",
    home: "ctrl+home",
    end: "ctrl+end"
  }
});
datetimepicker.appendTo('#datetimepicker');

Defaults to null

locale string

Overrides the global culture and localization value for this component. Default global culture is ‘en-US’.

Defaults to ’’

maskPlaceholder MaskPlaceholderModel

Specifies the mask placeholder to be displayed on masked datetimepicker.

Defaults to {day:’day’ , month:’month’, year: ‘year’, hour:’hour’,minute:’minute’,second:’second’,dayOfTheWeek: ‘day of the week’}

max Date

Gets or sets the maximum date that can be selected in the DateTimePicker.

Defaults to new Date(2099, 11, 31)

maxTime Date

Gets or sets the maximum time that can be selected in the time popup of the DateTimePicker.

Defaults to null

min Date

Gets or sets the minimum date that can be selected in the DateTimePicker.

Defaults to new Date(1900, 00, 01)

minTime Date

Gets or sets the minimum time that can be selected in the time popup of the DateTimePicker.

Defaults to null

openOnFocus boolean

By default, the popup opens while clicking on the datetimepicker icon.
If you want to open the popup while focusing the datetime input then specify its value as true.

Defaults to false

placeholder string

Specifies the placeholder text that to be is displayed in textbox.

Defaults to null

readonly boolean

Specifies the component in readonly state. When the Component is readonly it does not allow user input.

Defaults to false

scrollTo Date

Specifies the scroll bar position if there is no value is selected in the timepicker popup list or
the given value is not present in the timepicker popup list.

 <input id="datetimepicker" type="text">
import { DateTimePicker } from '@syncfusion/ej2-calendars';

let datetimepicker: DateTimePicker = new DateTimePicker({
  scrollTo: new Date("1/1/2018 5:30 PM")
});
datetimepicker.appendTo('#datetimepicker');

Defaults to null

serverTimezoneOffset number

By default, the date value will be processed based on system time zone.
If you want to process the initial date value using server time zone
then specify the time zone value to serverTimezoneOffset property.

Defaults to null

showClearButton boolean

Specifies whether to show or hide the clear icon in textbox.

Defaults to true

showTodayButton boolean

Specifies whether the today button is to be displayed or not.

Defaults to true

start CalendarView

Specifies the initial view of the Calendar when it is opened.
With the help of this property, initial view can be changed to year or decade view.

Defaults to Month<table><tr><td colSpan=1 rowSpan=1>View
</td><td colSpan=1 rowSpan=1>Description
</td></tr><tr><td colSpan=1 rowSpan=1>Month
</td><td colSpan=1 rowSpan=1>Calendar view shows the days of the month.
</td></tr><tr><td colSpan=1 rowSpan=1>Year
</td><td colSpan=1 rowSpan=1>Calendar view shows the months of the year.
</td></tr><tr><td colSpan=1 rowSpan=1>Decade
</td><td colSpan=1 rowSpan=1>Calendar view shows the years of the decade.
</td></tr></table>> For more details about start refer tocalendarViewdocumentation.

step number

Specifies the time interval between the two adjacent time values in the time popup list .

Defaults to 30

strictMode boolean

Specifies the component to act as strict. So that, it allows to enter only a valid
date and time value within a specified range or else it
will resets to previous value. By default, strictMode is in false.
it allows invalid or out-of-range value with highlighted error class.

Defaults to false> For more details refer toStrict Mode documentation.

timeFormat string

Specifies the format of the time value that to be displayed in time popup list.

Defaults to null

value Date

Gets or sets the selected date of the Calendar.

Defaults to null

weekNumber boolean

Determines whether the week number of the year is to be displayed in the calendar or not.

Defaults to false> For more details about weekNumber refer toCalendar with week numberdocumentation.

weekRule WeekRule

Specifies the rule for defining the first week of the year.

Defaults to FirstDay

width number|string

Specifies the width of the DatePicker component.

Defaults to null

zIndex number

specifies the z-index value of the popup element.

Defaults to 1000

Methods

addEventListener

Adds the handler to the given event listener.

Parameter Type Description
eventName string A String that specifies the name of the event
handler Function Specifies the call to run when the event occurs.

Returns void

appendTo

Appends the control within the given HTML element

Parameter Type Description
selector (optional) string | HTMLElement Target element where control needs to be appended

Returns void

attachUnloadEvent

Adding unload event to persist data when enable persistence true

Returns void

currentView

Gets the current view of the DatePicker.

Returns string

dataBind

When invoked, applies the pending property changes immediately to the component.

Returns void

destroy

To destroy the widget.

Returns void

detachUnloadEvent

Removing unload event to persist data when enable persistence true

Returns void

focusIn

Sets the focus to widget for interaction.

Returns void

focusOut

Remove the focus from widget, if the widget is in focus state.

Returns void

getLocalData

Returns the persistence data for component

Returns any

getPersistData

Gets the properties to be maintained upon browser refresh.

Returns string

getRootElement

Returns the route element of the component

Returns HTMLElement

handleUnload

Handling unload event to persist data when enable persistence true

Returns void

Navigates to specified month or year or decade view of the DatePicker.

Parameter Type Description
view CalendarView Specifies the view of the calendar.
date Date Specifies the focused date in a view.

Returns void

onPropertyChanged

Called internally if any of the property value changed.

Parameter Type Description
newProp DateTimePickerModel Returns the dynamic property value of the component.
oldProp DateTimePickerModel Returns the previous property value of the component.

Returns void

refresh

Applies all the pending property changes and render the component again.

Returns void

removeDate

This method is used to remove the single or multiple dates from the values property of the Calendar.

Parameter Type Description
dates Date | Date[] Specifies the date or dates which need to be removed from the values property of the Calendar.

Returns void

removeEventListener

Removes the handler from the given event listener.

Parameter Type Description
eventName string A String that specifies the name of the event to remove
handler Function Specifies the function to remove

Returns void

Inject

Dynamically injects the required modules to the component.

Parameter Type Description
moduleList Function[] ?

Returns void

Events

blur EmitType<Object>

Triggers when input loses the focus.

change EmitType<ChangedEventArgs>

Triggers when the Calendar value is changed.

cleared EmitType<ClearedEventArgs>

Triggers when datetimepicker value is cleared using clear button.

close EmitType<Object>

Triggers when popup is closed.

created EmitType<Object>

Triggers when DateTimePicker is created.

destroyed EmitType<Object>

Triggers when DateTimePicker is destroyed.

focus EmitType<Object>

Triggers when input gets focus.

Triggers when the Calendar is navigated to another level or within the same level of view.

open EmitType<Object>

Triggers when popup is opened.

renderDayCell EmitType<RenderDayCellEventArgs>

Triggers when each day cell of the Calendar is rendered.