---
schema_version: "1"
id: 284f64efd875960f246979f4ffc0abf71f33e16a93e186f2c538f902d5edae60
title: Datetime 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/datetime/lightning-datetime.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-datetime.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 822b2050dafba7ccbd5341b3ca7993fd8d8d0b9a43db511c3c4348d3545bf179
products:
  - Lightning Component Reference
---

# Datetime Picker

**`lightning-input`**
_type="datetime"_ or _type="datetime-local"_

**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="datetime" model="lwc" namespace="lightning"}


:::::

:::::tab

A datetime field includes a text input to type a date and a datepicker
to select a date, and similar fields for typing or picking a time.

```html
<template>
  <lightning-input type="datetime" label="Created date"> </lightning-input>
</template>
```

There is no behavioral difference between the `datetime` and `datetime-local` types.

## 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                                                                               |
| ---------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| datetime   | [Datetime Picker](https://v1.lightningdesignsystem.com/components/datetime-picker/) | [Datetime Picker](https://www.lightningdesignsystem.com/components/datetime-picker/) |

## Usage

The timepicker displays a dropdown menu with time options in 15-minute intervals, starting from 12:00 AM. To specify custom time intervals (in minutes) for the dropdown options, use the `time-step-minutes` attribute. You can pass in an interval of 5 or more minutes.

<!-- prettier-ignore -->
```html
<lightning-input
  type="datetime"
  label="Event Start"
  time-step-minutes="10"
></lightning-input>
```

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

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".

On desktop, `lightning-input` provides its own date/time picker that's styled with the Lightning Design System. Your Salesforce locale setting determines the acceptable date and time formats you can type in the fields and the format displayed in the fields after you pick a date and time. Your Salesforce language setting determines the names of months and weekdays displayed in the datepicker calendar, and the labels of the date and time fields.

The date and time you enter are automatically validated against your Salesforce locale format during the `blur` event. The date and time displayed reflect your Salesforce time zone setting. Use the `timezone` attribute to specify a different time zone in IANA time zone database format. For example, specify `timezone="America/New_York"` for US Eastern Time or `timezone="GMT"` for Greenwich Mean Time.

## 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"`.

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 a user enters 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.

The component uses `time-style="short"` by default to display the time without seconds, such as 6:53 PM in the en-US locale. To display time including seconds,
set `time-style="medium"` or `time-style="long"`. The medium and long styles currently have the same formatting.

Your Salesforce locale setting determines the time format you can type in the field or select in the timepicker, either 12-hr time with AM/PM or 24-hr time format.

Use the `value` attribute to optionally supply an initial value for the date and time as an ISO8601 formatted datetime string such as `2020-11-03T18:13:41Z`.

## Date Range

Set `min` and `max` to ISO8601 formatted datetime strings to constrain the allowed date and time 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. Users can still select a date and time outside the range,
but 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.

Adding a `placeholder` value shows the placeholder text in both the date and time fields.

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

## Input Validation

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

<!--prettier-ignore-->
```html
<template>
  <lightning-input
    type="datetime"
    label="Meeting Start"
    required
    min="2026-01-01T09:00:00Z"
    max="2030-12-31T17:00:00Z"
    lwc:ref="meetingStart"
    message-when-value-missing="Meeting start time is required"
    message-when-range-underflow="Meeting must start after January 1, 2026 at 9:00 AM"
    message-when-range-overflow="Meeting must start before December 31, 2030 at 5:00 PM"
  >
  </lightning-input>
  <lightning-button label="Submit" onclick={handleSubmit}></lightning-button>
</template>
```

An error icon is displayed on an invalid date and time 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 datetime input in JavaScript, use the `checkValidity()` method. If one of the fields isn't valid, the `reportValidity()` method shows the error message below the first invalid field.

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

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

The `validity` attribute returns an object with read-only boolean properties. For the `datetime` 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, 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.

In Lightning Experience, a datepicker calendar that's opened overlays the record edit page or modal, the global header, and record form footer when scrolling.

## Time Zone Differences

Set the same time zone on your mobile device and in Salesforce to avoid confusion and potential validation issues. For example, suppose the current time is 4:00 PM ET. Your mobile device is set to the America/New_York time zone and you're interacting with Salesforce while it's set to the America/Los_Angeles time zone. When you tap an empty date/time field
on the mobile device, the native date/time picker automatically selects the current device time, 4:00 PM.

Since the current time is 1:00 PM in Salesforce, this input time is in the future. If there's a validation rule stating that the value must be earlier than the current time, for example, the value is invalid. This occurs only because of the time zone discrepancy, and only on mobile devices when the date/time field is initially empty.

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

## Accessibility

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

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

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

If the date or time 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).


:::::

::::::