salla-datetime-picker
A date and time input backed by the Flatpickr library, which is loaded on demand.
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
In HTML or JSX, use the tag <salla-datetime-picker> with the Attribute names below. In React, the wrapper takes the Property names (camelCase).
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
Example
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" />
);
}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/ 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 | 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 | 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/ | "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 | boolean | false |
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
Used inside: <salla-gifting>, <salla-product-options>, <salla-user-profile>.