Date-Time Masks

• Dec 13, 2022
• 7 minutes to read

The following components can use date-time input masks: Date Edit, Time Edit and Masked Input. Our date-time mask implementation supports Gregorian, Korean, Taiwanese, and Thai Buddhist calendars. Mask behavior can differ depending on the client computer’s culture settings.

Run Demo: Date Edit Run Demo: Time Edit Run Demo: Masked Input

Date-time masks impose the following requirements on editor value type:

• Set the DxDateEdit.Date/DxTimeEdit.Time/DxMaskedInput.Value property to a DateTime object.
• If you bind the Masked Input’s edit value to an object other than DateTime, set MaskMode to MaskMode.DateTime.

For information on other mask types, refer to the following topic: Masks.

Date-Time Mask Navigation Modes

Date-time masks support the following navigation modes:

Regular (default)

After a user enters a specific part of a date/time value, he/she should move the caret to another part using a keyboard or a mouse pointer.

Advancing caret

In this mode, after a user enters and completes a specific part of a date/time value, the caret moves to the following part of a date/time value that can be edited. To enable this mode, set the CaretMode property to MaskCaretMode.Advancing.

Apply a Mask

To apply a date-time mask to the component, assign a pattern (see the sections below) to the component’s Mask property.

The DxDateTimeMaskProperties component specifies additional mask-related settings (for example, a caret mode, the current culture).

<DxDateEdit @bind-Date="Date"
            Mask="@DateTimeMask.ShortDate">
    <DxDateTimeMaskProperties CaretMode="@MaskCaretMode.Advanced"/>
</DxDateEdit>

@code{
    DateTime Date { get; set; } = DateTime.Now;
}

Predefined Masks

Predefined date-time masks allow you to apply a frequently used pattern so that you do not need to construct a mask. Note that pattern representation depends on the current culture. For example, the same input mask can specify different patterns in the U.S. and France. A culture-specific date-time format is defined by the CultureInfo.DateTimeFormat property. Users can change the regional format in the Settings → Time & Language → Region system dialog.

The following mask patterns are supported:

Built-in Patterns

Use DateTimeMask properties to specify built-in patterns. Each property is a wrapper for the corresponding format string (see the section below). This technique simplifies the setup process for users who are not familiar with the standard format strings.

<DxDateEdit @bind-Date="Date"
            Mask="@DateTimeMask.ShortDate">
</DxDateEdit>

@code{
    DateTime Date { get; set; } = DateTime.Now;
}

Standard Format Strings

Refer to the following article for more information on supported format strings: Standard date and time format strings.

<DxDateEdit @bind-Date="Date"
            Mask="F">
</DxDateEdit>

@code{
    DateTime Date { get; set; } = DateTime.Now;
}

The following table lists available mask specifiers:

Predefined Pattern	.NET Format String	Description	Sample
ShortDate	d	Short date format (“mm/dd/yyyy”).	2/18/2021
LongDate	D	Long date format.	Thursday, February 18, 2021
ShortTime	t	Short time format (“hh:mm AM/PM”).	7:51 PM
LongTime	T	Long time format (“hh:mm:ss AM/PM”).	7:51:13 PM
ShortDateTime	g	Combines short date and short time masks.	2/18/2021 7:51 PM
	G	Combines short date and long time masks.	2/18/2021 7:51:13 PM
	f	Combines long date and short time masks.	Thursday, February 18, 2021 7:51 PM
LongDateTime	F	Full time format according to the FullDateTimePattern property value. In the “en-US” culture, this specifier combines long date and long time masks.	February 18, 2021 7:51:13 PM
RFC1123	R or r	Date-time in the RFC1123 format.	Thu, 18 Feb 2021 19:51:13 GMT
ISO8601	s	Sortable ISO8601 date-time format.	2021-02-18T19:51:13
Universal	u	Universal sortable date-time format.	2021-02-18 19:51:13Z
MonthAndDay	M or m	Full month name and day number.	February 18
MonthAndYear	Y or y	Full month name and year number.	February 2021

Standard masks cannot be combined within a single expression. For instance, if you set the M, t mask - the output does not display as follows: Month DD, HH:MM AM(PM). To get this type of mask, use custom mask placeholders (see below).

Custom Masks

You can combine custom mask placeholders to create custom masks of any complexity. For example, to create the Year-ShortMonth-Date DayOfWeek mask, combine custom mask placeholders as follows:

<DxDateEdit @bind-Date="DateVDatealueCustom" 
            Mask="yyyy-MMM-dd dddd">
</DxDateEdit>

@code{
    DateTime Date { get; set; } = DateTime.Now;
}

You can use any of the following characters to build custom date-time masks.

Specifier or placeholder	Description	Example
d (%d, if used alone)	Day of a month.	1, 2, 3 … 31
dd	Day of a month, with a leading zero for single-digit values.	01, 02, 03 … 31
ddd	Read-only abbreviated name of the day of the week. Abbreviated day names are specified by the culture’s AbbreviatedDayNames property.	Mon, Tue, Sat
dddd	Read-only name of the day of the week. Day names are specified by the culture’s DayNames property.	Monday, Tuesday, Saturday
F or f (%F or %f, if used alone)	One fraction of a second. You can repeat this specifier up to seven times. Masks that have 4 or more “f” (“F”) specifiers are read-only.	1 to 9 (f or F) 01 to 99 (ff or FF) 0000001 to 9999999 (fffffff or FFFFFFF)
s (%s, if used alone)	Second.	1, 2, 3 … 59
ss	Second, with a leading zero for single-digit values.	01, 02, 03 … 59
h	Hour in the 12-hour format.	1, 2, 3 … 12
hh	Hour in the 12-hour format, with a leading zero for single-digit values.	01, 02, 03 … 12
H	Hour in the 24-hour format.	0, 1, 2 … 23
HH	Hour in the 24-hour format, with a leading zero for single-digit values.	00, 01, 02 … 23
m	Minute.	0, 1, 2 … 59
mm	Minute, with a leading zero for single-digit values.	00, 01, 02 … 59
M	A month number.	1, 2, 3 … 12
MM	A month number, with a leading zero for single-digit values.	01, 02, 03 … 12
MMM	Abbreviated month name according to the culture (the AbbreviatedMonthNames property).	Jan, Feb, Mar
MMMM	Full month name according to the culture (the MonthNames property).	January, February, March
y (%y, if used alone)	Last two digits of a year.	1 for 2001, 20 for 2020
yy	Last two digits of a year with a leading zero for single-digit values.	01 for 2001, 20 for 2020
yyyy	Four-digit year.	0001 - 9999
g	Read-only era.	AD or BC
tt	A time designator.	AM or PM
t (%t, if used alone)	The first letter of the time designator.	A or P
z	Hours offset from UTC, with no leading zeros. Read-only.	-1, +5
zz	Hours offset from UTC, with a leading zero for single-digit values. Read-only.	-01, +05
zzzz	Hours and minutes offset from UTC. Read-only.	-01:00, +05:00
:	Time separator that is defined by the current culture. The actual separator is specified by the TimeSeparator property.	: in the en-US culture
/	Date separator that is defined by the current culture. The actual separator is specified by the DateSeparator property.	/ in the en-US culture
\	Commands the editor to treat the following symbol as a regular character, not a date-time specifier.	The zz sequence defines a two-digit time zone mask, but the \z\z sequence displays static zz text.
' or "	Allows you to add static (read-only) strings.	‘Current time:’ HH:mm

User Capabilities

• The Up/Down arrow keys increase/decrease the date-time value part under the caret.
• The mouse wheel increases and decreases the date-time value part under the caret.
• Keyboard letters select the corresponding month. For example, the j character selects January. Subsequent presses select June and then July.
• Keyboard numbers select the corresponding month.
• The Space key moves the caret to the next date-time value part.
• The date separator key moves the caret to the next date part.
• The time separator key moves the caret to the next time part.
• The century is automatically determined based on the culture’s TwoDigitYearMax setting. Type 0 to enter a custom century.

User Scenarios

Universal Sortable Date without Time

<DxDateEdit @bind-Date="Value"
            Mask="yyyy-MM-dd">
</DxDateEdit>

@code{
    DateTime Value { get; set; } = DateTime.Now;
}

The yyyy-MM-dd mask allows users to enter dates in the sortable format (year-month-day) without a time section.

Date with an Abbreviated Month Name

<DxDateEdit @bind-Date="Value"
            Mask="yyyy-MMM-dd">
</DxDateEdit>

@code{
    DateTime Value { get; set; } = DateTime.Now;
}

The yyyy-MMM-dd mask displays dates with abbreviated month names. Users can also enter numbers to specify the corresponding month.

Day Name to the Right of a Date

<DxDateEdit @bind-Date="Value"
            Mask="yyyy-MM-dd dddd">
</DxDateEdit>

@code{
    DateTime Value { get; set; } = DateTime.Now;
}

The yyyy-MM-dd dddd mask allows users to enter dates in the sortable format (year-month-day). The name of the corresponding day is displayed to the right of the value and cannot be edited.