---
schema_version: "1"
id: ec2eead83868c56952d40a30e76f47ad4ce31614871d5e25e4570fbfd80ba01a
title: Date Picker
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/date/lightning-date.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-date.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 4a9d91192394efe53a7a9e00efbcdebef3398ec70f5606dfee6b7a5e8cd7df3b
products:
  - Lightning Component Reference
---

# Date Picker

**`lightning-input`**
_type="date"_

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="date" model="lwc" namespace="lightning"}


:::::

:::::tab

A date input field includes a text input to type a date and a datepicker
to select a date.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="date" label="Birthday"> </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-input` implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or [SLDS 2 styling](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm) based on the org's theme or the container app that you use.

| Input Type | SLDS 1                                                                      | SLDS 2                                                                       |
| ---------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| date       | [Datepickers](https://v1.lightningdesignsystem.com/components/datepickers/) | [Datepickers](https://www.lightningdesignsystem.com/components/datepickers/) |

## Usage

On mobile devices, this component uses the native datepicker, which ignores the `date-style` attribute. The native datepicker uses the user's device settings for names of months and weekdays, the input date format, and the calendar type.

On desktop, this component uses a datepicker styled with the Lightning Design System. This picker uses the user's Salesforce language setting for names of months and weekdays, and the user's Salesforce locale setting for the date format. The entered date is validated against the user's Salesforce locale format during the `blur` event.

## Date Style

The component uses `date-style="medium"` by default to display the date
in a medium-length style, such as Jan 7, 2020 in the en-US locale.
To display a short style such as 1/7/2020, set `date-style="short"` in the component. To display a long style such as January 7, 2020, set `date-style="long"`.

When the field receives focus, a message appears under the field with the date format based on the user locale and `date-style` value.
For example, if your user locale is en-US and the `date-style` is `medium`, the message displays "Format: Dec 31, 2024".

The date entered must be valid for the user's Salesforce locale, and match one of the short, medium, or long styles. If the date entered is valid, the component accepts the input and reformats it to the specified `date-style` during the `blur` event.
For example, if the component specifies `date-style="long"` and you enter 1/7/2020 in the en-US locale, the component reformats it to January 7, 2020.

The component accepts a month value of `13` to accommodate conditions that sometimes require a 13th month in a year. For most locales, if you enter `13` for the month, the component converts the date to the first month of the following year during the `blur` event.

Use the `value` attribute to supply an initial value for the date as an ISO8601 formatted date string,
such as `2020-11-03`.

## Date Range

Set `min` and `max` to ISO8601 formatted date strings to constrain the allowed date values.

- If you set a `min` value, the datepicker calendar displays the month specified in the `min` value, and the previous month button is disabled. For example, if you specify `min="2025-1-1"`, the calendar displays January 2025 and the previous month button is disabled.
- If you set a `max` value, the datepicker calendar displays the month specified in the `max` value, and the next month button is disabled. For example, if you specify `max="2025-12-31"`, the calendar displays December 2025 and the next month button is disabled.

The datepicker shows dates outside the min and max range in gray as a visual cue. Although users can select a date outside the range,
the `blur` event triggers the field to display a validation error message.

## Add Field-Level Help and Placeholder Text

To provide a hint for entering information in the field, specify help text with the `field-level-help` attribute. Field-level help adds an info icon next to the input label, with a tooltip displaying your specified help text.

To provide sample input in the field, use the `placeholder` attribute. For example, in a `date` input, show the date in the expected format.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="date"
        label="Event Date"
        placeholder="mm/dd/yy"
        field-level-help="The event date must be in the future"
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Input Validation

To ensure a date is provided, use the `required` attribute. Use `min` and `max` attributes to constrain the allowed date range. The component automatically validates the date format based on the user's Salesforce locale.

<!-- prettier-ignore -->
```html
<template>
  <lightning-input
    type="date"
    label="Event Date"
    required
    min="2026-01-01"
    max="2030-12-31"
    lwc:ref="eventDate"
    message-when-value-missing="Event date is required"
    message-when-range-underflow="Event date must be after January 1, 2025"
    message-when-range-overflow="Event date must be before December 31, 2030"
  >
  </lightning-input>
  <lightning-button label="Submit" onclick={handleSubmit}></lightning-button>
</template>
```

An error icon is displayed on an invalid date field, except on desktop browsers.

**note:** For the default error messages, see the [`lightning-input` documentation](/docs/platform/lightning-component-reference/guide/lightning-input.html).

To validate the date input, use the `checkValidity()` method. If the value isn't valid, the `reportValidity()` method shows the error message below the date field.

```javascript
import { LightningElement } from "lwc";

export default class DateValidation extends LightningElement {
  handleSubmit() {
    const dateInput = this.refs.eventDate;
    console.log(dateInput.validity.valid); // Returns true or false
    if (!dateInput.checkValidity()) {
      dateInput.reportValidity();
      return;
    }
    // Proceed with form submission
    const selectedDate = dateInput.value;
  }
}
```

The `validity` attribute returns an object with read-only boolean properties. For the `date` type, these attributes apply:

- `badInput` - Indicates that the value is invalid or doesn't match the allowed format for the user's locale
- `customError` - Indicates that a custom error has been set using `setCustomValidity()`
- `patternMismatch` - Indicates that the value doesn't match the allowed pattern
- `rangeOverflow` - Indicates that the date is greater than the specified `max` attribute
- `rangeUnderflow` - Indicates that the date is less than the specified `min` attribute
- `typeMismatch` - Indicates that an invalid format was entered
- `valueMissing` - Indicates that no value is provided when the `required` attribute is set
- `valid` - True if none of the preceding properties are true

The `badInput` validity error for `date` and `datetime` fields displays a default message that varies by locale. For example, "Your entry does not match the allowed format Dec 31, 2024" is displayed for en-US locale, but a different date format is shown for a different locale.

The `valueMissing` validity error for `date` and `datetime` displays "Complete this field with format `[format]`" where `[format]` is the date format that's determined by the user locale. For example: "Complete this field with format Dec 31, 2024"

The `valueMissing` validity error for `date` and `datetime` displays "Complete this field with format `[format]`" where `[format]` is the date format that's determined by the user locale. For example: "Complete this field with format MMM d, yyyy"

## Usage Considerations

You can guide users with a `field-level-help` tooltip and a `placeholder` prompt in the text field, as described in [Add Field-Level Help and Placeholder Text](#add-field-level-help-and-placeholder-text).

On desktop, the datepicker calendar clips behind other components on the page if the parent container of `lightning-input` has a smaller width or height than the calendar. To prevent clipping, give the parent container a minimum width of 285px and minimum height of 310px.

By default, the datepicker calendar renders above all modals and the main Salesforce header.

## Accessibility

When you use the `label` attribute, the component generates a unique ID for the internal `<label>` and uses a standard `for` attribute to link it to the date field.

If you use the `label-hidden` variant, the component maintains the `for` attribute to link between the date field and the label.

If you use the `field-level-help` attribute, the component creates an `aria-describedby` link between the date field and the help tooltip.

If the date field fails validation, the component adds `aria-invalid="true"` and links the error message to the input by using `aria-describedby`.

For additional ARIA attributes that you can use, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).

## Custom Events

**`change`**

The event fired when a value is changed in the input field.

The `change` event returns one of the following `event.target` parameters, depending on input type.

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| value     | string | Returns the input value. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html)


:::::

:::::tab
For this component's attributes and methods, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).


:::::

::::::