# Blazor DatePicker Overview

The <a href="https://www.telerik.com/blazor-ui/datepicker" target="_blank">Blazor Date Picker component</a> allows the user to choose a date from a visual Gregorian [Telerik UI for Blazor Calendar](https://www.telerik.com/blazor-ui/documentation/components/calendar/overview) or type it into a [date input](https://www.telerik.com/blazor-ui/documentation/components/dateinput/overview) that can accept only dates. You can control the date format of the input, how the user navigates through the calendar, and which dates the user cannot select.

## Creating Blazor Date Picker

1. Use the `TelerikDatePicker` tag to add the component to your Razor page.
2. Bind a `DateTime` or `DateTime?` object to the component `Value` parameter.
3. (optional) Set the `Format`, `Min`, `Max`, and `Width` parameters.

> caption Basic Date Picker with custom format, min and max

<demo metaUrl="client/datepicker/overview/" height="500"></demo>

## Date Input Typing Settings

The Blazor DatePicker
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
DatePicker.

## Increment Steps

The Date 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 `DatePickerSteps` tag and its parameters. [Read more about the Blazor Date Picker increment steps...](https://www.telerik.com/blazor-ui/documentation/components/datepicker/increment-steps)

## Focused Date

By default, the DatePicker 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 DatePicker 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 DatePicker 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/datepicker/events#focuseddatechanged). The focused date doesn't change during keyboard navigation within the same month.

## Events

The Blazor Date Picker generates events that you can handle and further customize its behavior. [Read more about the Blazor Date Picker events...](https://www.telerik.com/blazor-ui/documentation/components/datepicker/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).

## Header Template

The Blazor DatePicker allows you to customize the rendering of the Calendar popup header. Learn more from the [Header Template article](https://www.telerik.com/blazor-ui/documentation/components/datepicker/header-template).

## Adaptive Rendering

<demo metaUrl="client/datepicker/adaptive/" height="520"></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)

## Date Picker Parameters

The Blazor Date Picker provides various parameters that allow you to configure the component:

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

| Attribute            | Type and Default Value                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AdaptiveMode`       | `AdaptiveMode` enum <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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `BottomView`         | ` CalendarView` enum <br/> (`Month`)                     | Defines the bottommost view in the popup calendar to which the user can navigate to.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `DisabledDates`      | `List<DateTime>`                                         | A list of dates that cannot be selected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `Enabled`            | `bool`                                                   | Specifies whether typing in the input and clicking the button is allowed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `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/datepicker/overview#focused-date) when open.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `Format`             | `string` <br /> (`ShortDatePattern`)                     | The format of the DatePicker'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` attribute on the `<input />` element. Use it to attach a `<label for="">` to 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 that the user can select.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `Min`                | `DateTime` <br /> (`DateTime(1900, 1, 1, 0, 0, 0)`)      | The earliest date that the user can select.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `Placeholder`        | `string`                                                 | Maps to the `placeholder` attribute of the HTML element. The `Placeholder` will appear if the component is bound to a **nullable** DateTime object - `DateTime?`. It 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/datepicker/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?`                                                   | Maps to 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `Title`              | `string`                                                 | The title text rendered in the header of the popup(action sheet). Applicable only when [`AdaptiveMode` is set to `Auto`](https://www.telerik.com/blazor-ui/documentation/common-features/adaptive-rendering).                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `ValidateOn`         | `ValidationEvent` enum <br/> (`Input`)                   | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `View`               | ` CalendarView` enum <br/> (`Month`)                     | The current view that will be displayed in the popup calendar.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

The Date Picker is, essentially, a [DateInput](https://www.telerik.com/blazor-ui/documentation/components/dateinput/overview) and a [Calendar](https://www.telerik.com/blazor-ui/documentation/components/calendar/overview) and the properties it exposes are mapped to the corresponding properties of these two components. You can read more about their behavior in the respective components' documentation.

### 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 DatePicker:

| Attribute     | Type and Default Value | Description                                                                        |
| ------------- | ---------------------- | ---------------------------------------------------------------------------------- |
| `Class`       | `string`               | The custom CSS class rendered on the wrapping element.                             |
| `PopupClass`  | `string`               | An additional CSS class to customize the appearance of the Date Picker's dropdown. |
| `PopupHeight` | `string`               | Defines the height of the DatePicker's Popup. Defaults to `auto`.                  |
| `PopupWidth`  | `string`               | Defines the width of the DatePicker's Popup. Defaults to `auto`.                   |
| `Width`       | `string`               | Defines the width of the DatePicker. Defaults to `280px`.                          |

You can find more options for customizing the Date Picker styling in the [Appearance article](https://www.telerik.com/blazor-ui/documentation/components/datepicker/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.

## DatePicker Reference and Methods

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

| Method       | Description                                                                                                                                                                                                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Close`      | Closes the Calendar popup.                                                                                                                                                                                                                                                                         |
| `FocusAsync` | Focuses the Date Picker 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. |
| `NavigateTo` | Navigates to a specified date and view. The method expects a `DateTime` and `CalendarView` arguments.                                                                                                                                                                                              |
| `Open`       | Opens the Calendar popup.                                                                                                                                                                                                                                                                          |
| `Refresh`    | Re-renders the Calendar popup.                                                                                                                                                                                                                                                                     |

> caption Using Blazor DatePicker methods

<demo metaUrl="client/datepicker/methods-1/" height="420"></demo>

## Next Steps

* [Using the Date Picker Events](https://www.telerik.com/blazor-ui/documentation/components/datepicker/events)

* [Configuring the Date Picker Increment Steps](https://www.telerik.com/blazor-ui/documentation/components/datepicker/increment-steps)

## See Also

* [Live Demo: Date Picker](https://demos.telerik.com/blazor-ui/datepicker/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)
* [DatePicker API Reference](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikdatepicker-1)
