# Form Datepicker > `` is a BootstrapVue custom date picker input form control, which provides full > WAI-ARIA compliance and internationalization support. ## Overview As a form control wrapper component for the [``](/docs/components/calendar) component, it provides additional validation state presentation and a compact interface. Native HTML5 date inputs vary in presentation, accessibility, and in some instances are not supported by all browsers. `` provides a consistent and accessible interface across all browser platforms and devices. ```html ``` `` supports many of the props available on [``](/docs/components/calendar) as well as some of the props available on [``](/docs/components/dropdown). ## `v-model` return value By default, `` returns dates as a string in the `YYYY-MM-DD` format, which is the same format returned by native browser `` controls. You can have `` return a `Date` object (with no time portion) as the `v-model` value instead by setting the `value-as-date` prop. If no date is selected, `` returns an empty string `''`, or returns `null` if the `value-as-date` prop is set. Note that when `value-as-date` prop is set, the returned `Date` object will be in the browser's default timezone. If `` has a value set for the `name` prop, a hidden input will be created which will have its name attribute set to the value of the `name` prop, and the value attribute will be set to the selected date as a `YYYY-MM-DD` string. This will allow the `` selected value to be submitted via native browser form submission. ## Disabled and readonly states Setting the `disabled` prop will remove all interactivity of the `` component. Setting the `readonly` prop will disable selecting a date, but will keep the component interactive, allowing for date navigation. The `v-model` will not be updated in the readonly state. For disabling specific dates or setting minimum and maximum date limits, refer to the [Date constraints](#date-constraints) section. ```html ``` ## Date constraints ### Minimum and maximum dates Restrict the calendar range via the `min` and `max` props. The props accept a date string in the format of `YYYY-MM-DD` or a `Date` object. ```html ``` ### Disabling dates If you need to disable specific dates within the date picker, specify a function reference to the `date-disabled-fn` prop. The function is passed two arguments: - `ymd` The date as a `YYYY-MM-DD` string - `date` The date as a `Date` object The function should either return `true` if the date _cannot_ be selected (disabled), or `false` if the date _can_ be selected (enabled). Note that the function **cannot** be asynchronous, and should return a value as quickly as possible. ```html ``` Note the `min` and `max` date constraints are evaluated first, before `date-disabled-fn`. ## Validation states `` supports invalid and valid styling via the boolean `state` prop. Setting `state` to boolean `false` will style the input as invalid, while setting it to boolean `true` will style it as valid. Setting `state` to `null` will not show any validation state styling (the default). ```html ``` Note that native browser validation is _not_ available with ``. ## Styling ### Variants The selected date button (background color) defaults to the `'primary'` theme variant. You can change this to any of the Bootstrap v4 theme variant colors: `'secondary'`, `'success'`, `'danger'`, `'warning'`, `'info'`, etc, via the `selected-variant` prop. Today's date will also be highlighted (text color) using the same variant as the selected date by default. To specify a different theme color to use for today's date, use the `today-variant` prop. To disable highlighting of today's date altogether, set the `no-highlight-today` prop. The navigation buttons default to the `'secondary'` theme variant. You can change this via the `nav-button-variant` prop. ### Control sizing Fancy a smaller or larger `` control? Set the `size` prop to `'sm'` for a smaller form control, or `'lg'` for a larger form form control. Note this does not affect the size of the popup calendar dialog. ```html ``` ### Placeholder Add custom placeholder text to the control, when no date is selected, via the `placeholder` prop. If a placeholder is not provided, the value of the `label-no-date-selected` prop is used. ```html ``` ### Optional controls Add optional control buttons to the bottom of the calendar popup via the props `today-button`, `reset-button` and `close-button`. - The today button selects today's date - The reset button either clears the selected date, or sets the date to the value of the prop `reset-value` (if provided) - The close button closes the calendar popup By default, clicking on the today or reset button will also close the calendar popup, unless the prop `no-close-on-select` is set. ```html ``` The text for the optional buttons can be set via the `label-today-button`, `label-reset-button`, and the `label-close-button` props. Due to the limited width of the footer section, it is recommended to keep these labels short. Note that the `Set Today` button may not set the control today's date, if today's date is outside of the `min` or `max` date range restrictions. In the case it is outside of the range, it will set to either `min` or `max` (depending on which is closes to today's date). ### Dropdown placement Use the dropdown props `right`, `dropup`, `dropright`, `dropleft`, `no-flip`, and `offset` to control the positioning of the popup calendar. Refer to the [`` positioning section](/docs/components/dropdown#positioning) for details on the effects and usage of these props. ### Initial open calendar date v2.7.0+ By default, when no date is selected, the calendar view will be set to the current month (or the `min` or `max` date if today's date is out of range of `min` or `max`) when opened. You can change this behaviour by specifying a date via the `initial-date` prop. The initial date prop will be used to determine the calendar month to be initially presented to the user. It does not set the component's value. ### Dark mode Want a fancy popup with a dark background instead of a light background? Set the `dark` prop to `true` to enable the dark background. ### Optional decade navigation buttons Set the prop `show-decade-nav` to enable the previous and next decade buttons in the datepicker's date navigation toolbar. The props `label-prev-decade` and `label-next-decade` props can be used to provide custom label text for the decade buttons. For example usage, refer to the [Internationalization section](#internationalization) below. ### Button only mode v2.7.0+ Fancy just a button that launches the date picker dialog, or want to provide your own optional text input field? Use the `button-only` prop to render the datepicker as a dropdown button. The formatted date label will be rendered with the class `sr-only` (available only to screen readers). In the following simple example, we are placing the datepicker (button only mode) as an append to a ``, and we are using the `context` event to get the formatted date string and value: ```html ``` Control the size of the button via the `size` prop, and the button variant via the `button-variant` prop. ### Date string format v2.6.0+ To change format options of the displayed date text inside the component, e.g. in the header or placeholder, set the `date-format-options` prop to an object containing the requested format properties for the `Intl.DateTimeFormat` object (see also [Internationalization](#internationalization)). ```html ``` The following table summarizes the valid options for each format property: | Property | Possible values | | --------- | ------------------------------------------------------------ | | `year` | `'numeric'`, or `'2-digit'` | | `month` | `'numeric'`, `'2-digit'`, `'long'`, `'short'`, or `'narrow'` | | `day` | `'numeric'`, or `'2-digit'` | | `weekday` | `'long'`, `'short'`, or `'narrow'` | Notes: - Leaving out certain options may affect the formatted text string, e.g. the `weekday` - The formatted value will vary according to the resolved locale. Some locales may not support the `'narrow'` format and will fall back to `'short'` or `long'` (if `'short'` is not available) - `year`, `month` and `day` will always be shown. If you need to leave out a value, set the property to `undefined`, although this is highly discouraged for accessibility reasons ### Weekday name header format 2.12.0+ The calendar weekday name header format defaults to `'short'`, which is typically a three-character abbreviation of the weekday, although some [locales](#internationalization) may override this. The format can be controlled via the prop `weekday-header-format` and accepts one of three values: - `'long'` the full weekday name (e.g. Tuesday). Handy when using a full width calendar. Avoid using with the default calendar width. - `'short'` typically is a 2 or 3 letter abbreviation of the weekday name, depending on the selected locale (e.g. "Tue"). - `'narrow'` is typically a single character abbreviation (e.g., T). Two weekdays may have the same narrow style for some locales (e.g. Tuesday and Thursday's narrow style are both T). This can be handy for those locales that do not support the `'short'` format, such as locales `'ar'` and `'fa'`. ### Date navigation button slots 2.12.0+ To change the content of the calendar's date navigation buttons, BootstrapVue provides scoped slots for each button: - `'nav-prev-decade'` - `'nav-prev-year'` - `'nav-prev-month'` - `'nav-this-month'` (the go to selected/today button) - `'nav-next-month'` - `'nav-next-year'` - `'nav-next-decade'` All seven slots have the same scoped property available: | Property | Type | Description | | -------- | ------- | --------------------------------------------------------------------- | | `isRTL` | Boolean | Will be `true` when the date navigation bar is rendered right-to-left | You can use the `isRTL` scoped property to "flip" the prev vs next button content to handle the left-to-right to right-to-left orientation change — i.e. the previous year button will be on the right when `isRTL` is `true`, instead of the left. ### Full width calendar dropdown To create a full width calendar dropdown (where the width matches the input width), simply set the `menu-class` prop to `'w-100'` and set the `calendar-width` prop to `'100%'`: ```html ``` ## Internationalization Internationalization of the date picker's calendar is provided via [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat), except for labels applied to elements of the calendar control (aria-labels, selected status, and help text). You must provide your own translations for these labels. The available locales will be browser dependent (not all browsers support all locales) By default `` will use the browser's default locale, but you can specify the locale (or locales) to use via the `locale` prop. The prop accepts either a single locale string, or an array of locale strings (listed in order of preferred locale). The calendar starts the week on Sunday. This can be changed by setting the `start-weekday` prop to a number in the range of `0` to `6` where `0` represents Sunday, `1` for Monday, up to `6` for Saturday. ```html ``` You can listen to for the `context` event to determine the locale and directionality that the calendar has resolved to. Refer to the [``](/docs/components/calendar#internationalization) documentation for additional details. ## Accessibility The popup calendar supports the same [keyboard controls as ``](/docs/components/calendar#accessibility), along with the following: - Esc will close the popup calendar without selecting a date When internationalizing the datepicker, it is important to also update the `label-*` props with appropriate translated strings, so that international screen reader users will hear the correct prompts and descriptions. Refer to the [``](/docs/components/calendar#accessibility) documentation for additional details. ## Implementation notes `` is based upon the components [``](/docs/components/calendar) and [``](/docs/components/dropdown). `` uses Bootstrap's border and flex utility classes, along with button (`btn-*`) classes, dropdown (`dropdown*`) classes, and the `form-control*` (plus validation) classes. BootstrapVue's Custom SCSS/CSS is also required for proper styling of the date picker and calendar. ## See also - [`` Time picker custom form input](/docs/components/form-timepicker) - [`` Calendar date selection widget](/docs/components/calendar) - [`` Time selection widget](/docs/components/time) - [`` Dropdown component](/docs/components/dropdown)