# salla-datetime-picker (https://docs.salla.dev/twilight/react/web-components/salla-datetime-picker)



{/* Generated by scripts/sync-web-components.mjs from the components docs.json. Do not edit by hand. */}

A date and time input backed by the Flatpickr library, which is loaded on demand. Use it where a customer picks a
date or a time, for example a gift send date. It renders a text input inside the component and opens a calendar popup.

Options are passed to Flatpickr once, after the component first renders, so changing an option prop later has no effect.
Props that take functions or DOM elements (`disable`, `enable`, `formatDate`, `dateParser`, `appendTo`, `positionElement`)
must be set as JavaScript properties, not HTML attributes. Boolean props are set as attributes like `enable-time` or `no-calendar`.

## Use it [#use-it]

In HTML or JSX, use the tag `<salla-datetime-picker>` with the **Attribute** names below. In React, the wrapper takes the **Property** names (camelCase).

```tsx
import { SallaDatetimePicker } from '@salla.sa/twilight-components-react/datetime-picker';
```

**Client-only.** On the server this wrapper renders a placeholder (a skeleton, or nothing), and the real component mounts in the browser. Do not rely on it for content that search engines must see.

## Try it [#try-it]

<Demo name="web-components/salla-datetime-picker" />

## Example [#example]

```tsx
import { useEffect } from 'react';
import { SallaDatetimePicker } from '@salla.sa/twilight-components-react/datetime-picker';

export function Example() {
  useEffect(() => {
    document.querySelector('salla-datetime-picker').addEventListener('picked', e => console.log(e.detail));
  }, []);

  return (
    <SallaDatetimePicker name="send_at" enableTime time_24hr minDate="today" dateFormat="Y-m-d H:i" locale="ar" />
  );
}
```

```html
<salla-datetime-picker name="send_at" enable-time time_24hr min-date="today" date-format="Y-m-d H:i" locale="ar"></salla-datetime-picker>
<script>
  document.querySelector('salla-datetime-picker').addEventListener('picked', e => console.log(e.detail));
</script>
```

## Properties [#properties]

| Property                | Attribute                 | Description                                                                                                                                                                                                                                                                                                                                   | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Default                                                          |
| ----------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `allowInput`            | `allow-input`             | Allows the user to type a date directly into the input field. Defaults to true.                                                                                                                                                                                                                                                               | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `true`                                                           |
| `allowInvalidPreload`   | `allow-invalid-preload`   | Allows the preloading of an invalid date. When disabled, the field will be cleared if the provided date is invalid                                                                                                                                                                                                                            | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                                          |
| `altFormat`             | `alt-format`              | The date format of the visible input when `altInput` is true. Uses the same tokens as `dateFormat`.                                                                                                                                                                                                                                           | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `"F j, Y"`                                                       |
| `altInput`              | `alt-input`               | Shows the user a readable date in `altFormat` and keeps a hidden input with the value in `dateFormat`.                                                                                                                                                                                                                                        | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                                          |
| `altInputClass`         | `alt-input-class`         | This class will be added to the input element created by the altInput option. Note that altInput already inherits classes from the original input.                                                                                                                                                                                            | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                                                                  |
| `appendTo`              | `append-to`               | The element to append the calendar popup to, instead of `body`. Set it as a JS property.                                                                                                                                                                                                                                                      | `HTMLElement`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `undefined`                                                      |
| `ariaDateFormat`        | `aria-date-format`        | Defines how the date will be formatted in the aria-label for calendar days, using the same tokens as dateFormat. If you change this, you should choose a value that will make sense if a screen reader reads it out loud.                                                                                                                     | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `"F j, Y"`                                                       |
| `autoFillDefaultTime`   | `auto-fill-default-time`  | Whether the default time should be auto-filled when the input is empty and gains or loses focus.                                                                                                                                                                                                                                              | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `true`                                                           |
| `clickOpens`            | `click-opens`             | Whether clicking on the input opens the picker. Defaults to true.                                                                                                                                                                                                                                                                             | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `true`                                                           |
| `closeOnSelect`         | `close-on-select`         | Whether the calendar closes after a date is selected. Defaults to true.                                                                                                                                                                                                                                                                       | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `true`                                                           |
| `conjunction`           | `conjunction`             | The text used to separate dates in the input when `mode` is `multiple`.                                                                                                                                                                                                                                                                       | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                                                                  |
| `dateFormat`            | `date-format`             | The format of the date shown in the input and stored in `value`, using Flatpickr tokens such as `Y-m-d` or `Y-m-d H:i`. See [https://flatpickr.js.org/formatting/](https://flatpickr.js.org/formatting/) for the tokens. Defaults to `Y-m-d`.                                                                                                 | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `"Y-m-d"`                                                        |
| `dateParser`            | `date-parser`             | A custom function `(dateString, format) => Date` used to parse typed or initial date strings. Set it as a JS property.                                                                                                                                                                                                                        | `(date: string, format: string) => Date`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                                                                  |
| `defaultDate`           | `default-date`            | The initially selected date(s). Use an array for `multiple` and `range` modes, otherwise a single Date, timestamp or date string in `dateFormat`. Ignored when `value` is set.                                                                                                                                                                | `Date \| DateOption[] \| number \| string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                                  |
| `defaultHour`           | `default-hour`            | The hour (0 to 23) the time picker starts at when no date is selected. Defaults to 12. Used with `enable-time`.                                                                                                                                                                                                                               | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `12`                                                             |
| `defaultMinute`         | `default-minute`          | The minute (0 to 59) the time picker starts at when no date is selected. Defaults to 0. Used with `enable-time`.                                                                                                                                                                                                                              | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `0`                                                              |
| `defaultSeconds`        | `default-seconds`         | The seconds (0 to 59) the time picker starts at when no date is selected. Defaults to 0. Used with `enable-seconds`.                                                                                                                                                                                                                          | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `0`                                                              |
| `disable`               | `disable`                 | Dates the user cannot select. An array of dates (Date, timestamp or string), `{ from, to }` ranges, or functions that receive a Date and return true to disable it. Set it as a JS property. See [https://chmln.github.io/flatpickr/examples/#disabling-specific-dates](https://chmln.github.io/flatpickr/examples/#disabling-specific-dates) | `DateLimit<DateOption>[]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `[]`                                                             |
| `disableMobile`         | `disable-mobile`          | When true, always uses the Flatpickr calendar on mobile devices instead of the native date widget. Defaults to false.                                                                                                                                                                                                                         | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                                          |
| `disabled`              | `disabled`                | Disables the input.                                                                                                                                                                                                                                                                                                                           | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                                          |
| `enable`                | `enable`                  | Only these dates can be selected, using the same item types as `disable`. Defaults to a function that allows every date. Set it as a JS property. See [https://chmln.github.io/flatpickr/examples/#disabling-all-dates-except-select-few](https://chmln.github.io/flatpickr/examples/#disabling-all-dates-except-select-few)                  | `DateLimit<DateOption>[]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `[(_) => true]`                                                  |
| `enableSeconds`         | `enable-seconds`          | Shows a seconds field in the time picker. Used with `enable-time`.                                                                                                                                                                                                                                                                            | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                                          |
| `enableTime`            | `enable-time`             | Shows a time picker next to the calendar so the user also picks a time.                                                                                                                                                                                                                                                                       | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                                          |
| `formatDate`            | `format-date`             | A custom function `(date, format, locale) => string` used instead of the built-in formatting. Set it as a JS property.                                                                                                                                                                                                                        | `(date: Date, format: string, locale: Object) => string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                                                                  |
| `hourIncrement`         | `hour-increment`          | Step of the hour input, including scrolling. Defaults to 1.                                                                                                                                                                                                                                                                                   | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `1`                                                              |
| `inline`                | `inline`                  | Shows the calendar permanently below the input instead of in a popup.                                                                                                                                                                                                                                                                         | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                                          |
| `locale`                | `locale`                  | The locale code of the calendar, for example `ar` or `en`. The matching Flatpickr language file is loaded when it is not `en`. Defaults to `en`. See [https://chmln.github.io/flatpickr/localization/](https://chmln.github.io/flatpickr/localization/)                                                                                       | `"at" \| "hr" \| "th" \| "tr" \| "id" \| "is" \| "default" \| "no" \| "cy" \| "es" \| "mn" \| "ms" \| "ar" \| "az" \| "be" \| "bg" \| "bn" \| "bs" \| "ca" \| "cat" \| "ckb" \| "cs" \| "da" \| "de" \| "en" \| "eo" \| "et" \| "fa" \| "fi" \| "fo" \| "fr" \| "gr" \| "he" \| "hi" \| "hu" \| "hy" \| "it" \| "ja" \| "ka" \| "ko" \| "km" \| "kz" \| "lt" \| "lv" \| "mk" \| "my" \| "nl" \| "nn" \| "pa" \| "pl" \| "pt" \| "ro" \| "ru" \| "si" \| "sk" \| "sl" \| "sq" \| "sr" \| "sv" \| "uk" \| "vn" \| "zh" \| "uz" \| "uz_latn" \| "zh_tw"` | `"en"`                                                           |
| `maxDate`               | `max-date`                | The latest date that a user can pick (inclusive), as a Date, timestamp or date string.                                                                                                                                                                                                                                                        | `Date \| number \| string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `null`                                                           |
| `maxTime`               | `max-time`                | The latest time that a user can pick (inclusive). Used with `enable-time`.                                                                                                                                                                                                                                                                    | `Date \| number \| string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `null`                                                           |
| `minDate`               | `min-date`                | The earliest date that a user can pick (inclusive), as a Date, timestamp or date string such as `today`.                                                                                                                                                                                                                                      | `Date \| number \| string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `null`                                                           |
| `minTime`               | `min-time`                | The earliest time that a user can pick (inclusive). Used with `enable-time`.                                                                                                                                                                                                                                                                  | `Date \| number \| string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `null`                                                           |
| `minuteIncrement`       | `minute-increment`        | Step of the minute input, including scrolling. Defaults to 5.                                                                                                                                                                                                                                                                                 | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `5`                                                              |
| `mode`                  | `mode`                    | Selection mode. One of `single` (default), `multiple` or `range`. `time` is also accepted by the type, but to get a time-only picker use `enable-time` with `no-calendar`.                                                                                                                                                                    | `"multiple" \| "range" \| "single" \| "time"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `"single"`                                                       |
| `monthSelectorType`     | `month-selector-type`     | How the month should be displayed in the header of the calendar. If showMonths has a value greater than 1, the month is always shown as static.                                                                                                                                                                                               | `"dropdown" \| "static"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `"dropdown"`                                                     |
| `name`                  | `name`                    | The `name` of the input, used when it is submitted inside a form.                                                                                                                                                                                                                                                                             | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                                                                  |
| `nextArrow`             | `next-arrow`              | HTML of the icon used to go to the next month.                                                                                                                                                                                                                                                                                                | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `'<span class="sicon-keyboard_arrow_right"></span>'`             |
| `noCalendar`            | `no-calendar`             | Hides the day calendar. Use it with `enable-time` to make a time-only picker.                                                                                                                                                                                                                                                                 | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                                          |
| `placeholder`           | `placeholder`             | Placeholder text of the input. Defaults to the translated "select send date and time" text.                                                                                                                                                                                                                                                   | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `salla.lang.get('blocks.buy_as_gift.select_send_date_and_time')` |
| `position`              | `position`                | Where the calendar popup appears relative to the input, such as `auto`, `above`, `below`, or a combination like `below left`. A function `(self, customElement) => void` can also set the position yourself. Defaults to `auto`.                                                                                                              | `"above center" \| "above left" \| "above right" \| "above" \| "auto center" \| "auto left" \| "auto right" \| "auto" \| "below center" \| "below left" \| "below right" \| "below" \| ((self: any, customElement: HTMLElement) => void)`                                                                                                                                                                                                                                                                                                             | `"auto"`                                                         |
| `positionElement`       | `position-element`        | The element the calendar is positioned against. Defaults to the date input. Set it as a JS property.                                                                                                                                                                                                                                          | `HTMLElement`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |                                                                  |
| `prevArrow`             | `prev-arrow`              | HTML of the icon used to go to the previous month.                                                                                                                                                                                                                                                                                            | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `'<span class="sicon-keyboard_arrow_left"></span>'`              |
| `required`              | `required`                | Marks the input as required for form validation.                                                                                                                                                                                                                                                                                              | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |                                                                  |
| `shorthandCurrentMonth` | `shorthand-current-month` | Whether to display the current month name in shorthand mode, e.g. "Sep" instead "September"                                                                                                                                                                                                                                                   | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                                          |
| `showMonths`            | `show-months`             | How many months the calendar shows at the same time. Defaults to 1.                                                                                                                                                                                                                                                                           | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `1`                                                              |
| `static`                | `static`                  | Places the calendar inside the component's wrapper, next to the input, instead of at the end of `body`.                                                                                                                                                                                                                                       | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                                          |
| `time_24hr`             | `time_-2-4hr`             | Shows the time picker in 24 hour mode without AM/PM. Used with `enable-time`. The attribute is `time_24hr`.                                                                                                                                                                                                                                   | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                                          |
| `value`                 | `value`                   | The selected date or time as a string, in the format of `dateFormat`. It is updated when the user picks a value. When set at load, it is parsed with `Date.parse` and takes priority over `defaultDate`.                                                                                                                                      | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `null`                                                           |
| `weekNumbers`           | `week-numbers`            | Shows week numbers in the calendar.                                                                                                                                                                                                                                                                                                           | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                                          |
| `wrap`                  | `wrap`                    | Flatpickr `wrap` option for external toggle elements. See [https://chmln.github.io/flatpickr/examples/#flatpickr-external-elements](https://chmln.github.io/flatpickr/examples/#flatpickr-external-elements)                                                                                                                                  | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                                          |

## Events [#events]

Listen with `addEventListener`, or the `on` prop of the React wrapper (for example `onModalBack`).

| Event          | Description                                                                                                                                      | Detail |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| `invalidInput` | Fires when the input fails validation, for example when it is `required` and empty on form submit. `event.detail` is the native `invalid` event. | `any`  |
| `picked`       | Fires when the user picks a date or time. `event.detail` is the new value as a string in `dateFormat`.                                           | `any`  |

## Related [#related]

Used inside: [`<salla-gifting>`](https://docs.salla.dev/twilight/react/web-components/salla-gifting), [`<salla-product-options>`](https://docs.salla.dev/twilight/react/web-components/salla-product-options), [`<salla-user-profile>`](https://docs.salla.dev/twilight/react/web-components/salla-user-profile).