# Blazor DateTime Picker Overview

The Blazor DateTime Picker component allows the user to choose both a date and a time from a visual list in a dropdown, or to type it into a [date input](https://www.telerik.com/blazor-ui/documentation/components/dateinput/overview) that can accept only DateTime values. You can control the date and time format of the input, and respond to [events](https://www.telerik.com/blazor-ui/documentation/components/datetimepicker/events).

## Creating Blazor DateTimePicker

1. Add the `TelerikDateTimePicker` tag to your razor page.
2. Bind a `DateTime` object to the component
3. Optionally, provide custom `Format`, `Min` and `Max` values

> caption Basic datetime picker with custom format, min and max

<demo metaUrl="client/datetimepicker/basic-2/" height="620"></demo>

## Date Input Typing Settings

The DateTimePicker
textbox is a [DateInput component](https://www.telerik.com/blazor-ui/documentation/components/dateinput/overview), which provides various parameters to configure the keyboard typing experience. The settings are related to:

* Caret placement;
* Two-digit year values;
* Automatic correction of invalid date segments.

See the [DateInput keyboard documentation](https://www.telerik.com/blazor-ui/documentation/components/dateinput/keyboard-typing) for details and examples. The same DateInput parameters with the same behavior exist for the
DateTimePicker.

## Increment Steps

The DateTime Picker enables the end users to change the selected value by clicking the rendered arrows. You can set the increment and decrement steps through the nested `DateTimePickerSteps` tag and its parameters. [Read more about the Blazor DateTime Picker increment steps...](https://www.telerik.com/blazor-ui/documentation/components/datetimepicker/increment-steps)

## Focused Date

By default, the DateTimePicker Calendar shows:

* The current month if no value is selected.
* The month of the selected value.

The `FocusedDate` parameter allows the app to open the DateTimePicker Calendar on a different month. The parameter value changes automatically to:

* The currently displayed month during Calendar navigation.
* The new selected value's date.
* Today's date if the DateTimePicker popup is closed without selecting a value.

In all the above cases, the component fires the [`FocusedDateChanged` event](https://www.telerik.com/blazor-ui/documentation/components/datetimepicker/events#focuseddatechanged). The focused date doesn't change during keyboard navigation within the same month.

## Events

The Blazor DateTime Picker generates events that you can handle and further customize its behavior. [Read more about the Blazor DateTime Picker events...](https://www.telerik.com/blazor-ui/documentation/components/datetimepicker/events).

## Validation

You can ensure that the component value is acceptable by using the built-in validation. [Read more about input validation...](https://www.telerik.com/blazor-ui/documentation/common-features/input-validation).

## Action Buttons

When using the dropdown to edit dates, you must click the "Set" button to commit the date. It is located in the Time portion of the dropdown (you will be navigated to it automatically upon selecting a date). Clicking "Cancel", or outside of the dropdown without clicking "Set", will revert the time to the original value. You can also commit a date by clicking the "NOW" button which will choose the current time.

## Format

The time format specifiers in the `Format` control the tumblers available in the dropdown. For example, the `HH` specifier will result in a hour selector in a 24 hour format. If you also add the `tt` specifier, you will also get the AM/PM tumbler, but the 24 hour format will still be used. This means that you can also add several tumblers for the same time portion if the format string repeats them.

## Adaptive Rendering

<demo metaUrl="client/datetimepicker/adaptive/" height="670"></demo>

The component supports different popup rendering depending on the screen size. [Read more about the Adaptive Rendering functionality and how to enable it...](https://www.telerik.com/blazor-ui/documentation/common-features/adaptive-rendering)

## Blazor DateTime Picker Parameters

The Blazor Date Time Picker provides various parameters that allow you to configure the component. Also check the [DateTimePicker's public API](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikdatetimepicker-1).

<style>
    .article table {
        table-layout: auto;
        word-break: normal;
    }
</style>

| Attribute            | Type and Default Value                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AdaptiveMode`       | `AdaptiveMode` <br /> (`None`)                           | The [adaptive mode](https://www.telerik.com/blazor-ui/documentation/common-features/adaptive-rendering) of the component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `AutoComplete`       | `string` <br /> (`"off"`)                                | The `autocomplete` HTML attribute of the `input`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `DebounceDelay`      | `int` <br/> (`150`)                                      | Time in milliseconds between the last typed symbol and the value update. Use it to balance between client-side performance and number of database queries.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `Enabled`            | `bool`                                                   | Defines if the `DateTimePicker` is enabled                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `ReadOnly`           | `bool`                                                   | If set to `true`, the component will be readonly and will not allow user input. The component is not readonly by default and allows user input.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `FocusedDate`        | `DateTime`                                               | The [focused date in the popup Calendar](https://www.telerik.com/blazor-ui/documentation/components/datetimepicker/overview#focused-date) when open.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `Format`             | `string` <br /> (`FullDateTimePattern`)                  | The format of the DateTimePicker's DateInput. The default value depends on `CultureInfo.CurrentCulture`. Read more at [Supported date formats by the DateInput](https://www.telerik.com/blazor-ui/documentation/components/dateinput/supported-formats).                                                                                                                                                                                                                                                                                                                                                                      |
| `Id`                 | `string`                                                 | The `id` HTML attribute of the `input`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `InputMode`          | `string`                                                 | The [`inputmode` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode) of the `<input />` element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `Max`                | `DateTime` <br /> (`DateTime(2099, 12, 31, 23, 59, 59)`) | The latest date and time that the user can select                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `Min`                | `DateTime` <br /> (`DateTime(1900, 1, 1, 0, 0, 0)`)      | The earliest date and time that the user can select                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `Placeholder`        | `string`                                                 | The `placeholder` attribute of the HTML element. The placeholder will appear if the component is bound to nullable DateTime object - `DateTime?`, but will not be rendered if the component is bound to the default value of a non-nullable DateTime object. The Placeholder value will be displayed when the input is not focused. Once the user focuses it to start typing, the Format Placeholder (default or [customized one](https://www.telerik.com/blazor-ui/documentation/components/datetimepicker/overview#format-placeholder)) will override the Placeholder to indicate the format the date should be entered in. |
| `ShowClearButton`    | `bool`                                                   | Defines if the user can clear the component value through an **x** button rendered inside the input.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `ShowWeekNumbers`    | `bool`                                                   | Sets if the popup Calendar will display week numbers according to the [ISO-8601 format](https://learn.microsoft.com/en-us/dotnet/api/system.globalization.isoweek.getweekofyear). Note that the [ISO week number may differ from the conventional .NET week number](https://learn.microsoft.com/en-us/dotnet/api/system.globalization.calendar.getweekofyear).                                                                                                                                                                                                                                                                |
| `ShowOtherMonthDays` | `bool` <br/> (`true`)                                    | Defines whether the leading and trailing days from other months in the Calendar popup are visible in the current month view.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `TabIndex`           | `int?`                                                   | The `tabindex` attribute of the HTML element. You can use it to customize the order in which the inputs in your form focus with the `Tab` key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `ValidateOn`         | `ValidationEvent` enum <br/> (`Input`)                   | `ValidateOn` - configures the event that will trigger validation (if validation is enabled). Read more at [Validation Modes for Simple Inputs](https://www.telerik.com/blazor-ui/documentation/common-features/input-validation#validation-modes-for-simple-inputs)                                                                                                                                                                                                                                                                                                                                                           |
| `Value`              | `DateTime` or `DateTime?`                                | The current value of the component. Supports two-way binding.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Typing User Experience

The component provides multiple parameters, which control the [caret placement, two-digit year values and the auto-correct behavior of the textbox. See the **DateInput** documentation for details](https://www.telerik.com/blazor-ui/documentation/components/dateinput/keyboard-typing).

### Styling and Appearance

The following parameters enable you to customize the appearance of the Blazor DateTimePicker:

| Attribute    | Type and Default Value | Description                                                                       |
| ------------ | ---------------------- | --------------------------------------------------------------------------------- |
| `Class`      | `string`               | The CSS class that will be rendered on the `input` element                        |
| `PopupClass` | `string`               | Additional CSS class to customize the appearance of the DateTimePicker's dropdown |
| `Width`      | `string`               | The width of the `DateTimePicker`                                                 |

You can find more options for customizing the DateTimePicker styling in the [Appearance article](https://www.telerik.com/blazor-ui/documentation/components/datetimepicker/appearance).

### Format Placeholder

It is possible to set custom strings as placeholders for each date format segment. This feature is available for the following Telerik UI for Blazor components:

* DateInput
* DatePicker
* DateRangePicker
* DateTimePicker
* TimePicker

To set up the `FormatPlaceholder`, use the `<*Component*FormatPlaceholder>` nested tag. It allows you to set format placeholders by using the following parameters:

* `Day`
* `Month`
* `Year`
* `Hour`
* `Minute`
* `Second`
* `Weekday`
* `DayPeriod`

By default, the value for all parameters is `null`, which applies the full format specifier.

## Blazor DateTimePicker Reference and Methods

Add a reference to the component instance to use the [Date Time Picker's methods](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikdatetimepicker-1).

| Method       | Description                                                                                                                                                                                                                                                                                           |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Close`      | Closes the Calendar popup.                                                                                                                                                                                                                                                                            |
| `FocusAsync` | Focuses the DateTimePicker textbox. Always `await` this call, as it relies on `JSInterop`. Also check the dedicated KB article about [programmatic input component focusing](https://www.telerik.com/blazor-ui/documentation/knowledge-base/inputs-set-focus), which provides more examples and tips. |
| `Open`       | Opens the Calendar popup.                                                                                                                                                                                                                                                                             |

<demo metaUrl="client/datetimepicker/basic-1/" height="420"></demo>

## Next Steps

* [DateTimePicker Events](https://www.telerik.com/blazor-ui/documentation/components/datetimepicker/events)

## See Also

* [Live Demo: DateTime Picker](https://demos.telerik.com/blazor-ui/datetimepicker/overview)
* [Input Validation](https://www.telerik.com/blazor-ui/documentation/common-features/input-validation)
* [Supported Input Date Formats](https://www.telerik.com/blazor-ui/documentation/components/dateinput/supported-formats)
* [DateTimePicker API Reference](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikdatetimepicker-1)
