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

web-components/salla-datetime-picker

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

PropertyAttributeDescriptionTypeDefault
allowInputallow-inputAllows the user to type a date directly into the input field. Defaults to true.booleantrue
allowInvalidPreloadallow-invalid-preloadAllows the preloading of an invalid date. When disabled, the field will be cleared if the provided date is invalidbooleanfalse
altFormatalt-formatThe date format of the visible input when altInput is true. Uses the same tokens as dateFormat.string"F j, Y"
altInputalt-inputShows the user a readable date in altFormat and keeps a hidden input with the value in dateFormat.booleanfalse
altInputClassalt-input-classThis class will be added to the input element created by the altInput option. Note that altInput already inherits classes from the original input.string
appendToappend-toThe element to append the calendar popup to, instead of body. Set it as a JS property.HTMLElementundefined
ariaDateFormataria-date-formatDefines 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"
autoFillDefaultTimeauto-fill-default-timeWhether the default time should be auto-filled when the input is empty and gains or loses focus.booleantrue
clickOpensclick-opensWhether clicking on the input opens the picker. Defaults to true.booleantrue
closeOnSelectclose-on-selectWhether the calendar closes after a date is selected. Defaults to true.booleantrue
conjunctionconjunctionThe text used to separate dates in the input when mode is multiple.string
dateFormatdate-formatThe 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"
dateParserdate-parserA custom function (dateString, format) => Date used to parse typed or initial date strings. Set it as a JS property.(date: string, format: string) => Date
defaultDatedefault-dateThe 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
defaultHourdefault-hourThe hour (0 to 23) the time picker starts at when no date is selected. Defaults to 12. Used with enable-time.number12
defaultMinutedefault-minuteThe minute (0 to 59) the time picker starts at when no date is selected. Defaults to 0. Used with enable-time.number0
defaultSecondsdefault-secondsThe seconds (0 to 59) the time picker starts at when no date is selected. Defaults to 0. Used with enable-seconds.number0
disabledisableDates 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-datesDateLimit<DateOption>[][]
disableMobiledisable-mobileWhen true, always uses the Flatpickr calendar on mobile devices instead of the native date widget. Defaults to false.booleanfalse
disableddisabledDisables the input.booleanfalse
enableenableOnly 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-fewDateLimit<DateOption>[][(_) => true]
enableSecondsenable-secondsShows a seconds field in the time picker. Used with enable-time.booleanfalse
enableTimeenable-timeShows a time picker next to the calendar so the user also picks a time.booleanfalse
formatDateformat-dateA 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
hourIncrementhour-incrementStep of the hour input, including scrolling. Defaults to 1.number1
inlineinlineShows the calendar permanently below the input instead of in a popup.booleanfalse
localelocaleThe 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"
maxDatemax-dateThe latest date that a user can pick (inclusive), as a Date, timestamp or date string.Date | number | stringnull
maxTimemax-timeThe latest time that a user can pick (inclusive). Used with enable-time.Date | number | stringnull
minDatemin-dateThe earliest date that a user can pick (inclusive), as a Date, timestamp or date string such as today.Date | number | stringnull
minTimemin-timeThe earliest time that a user can pick (inclusive). Used with enable-time.Date | number | stringnull
minuteIncrementminute-incrementStep of the minute input, including scrolling. Defaults to 5.number5
modemodeSelection 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"
monthSelectorTypemonth-selector-typeHow 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"
namenameThe name of the input, used when it is submitted inside a form.string
nextArrownext-arrowHTML of the icon used to go to the next month.string'<span class="sicon-keyboard_arrow_right"></span>'
noCalendarno-calendarHides the day calendar. Use it with enable-time to make a time-only picker.booleanfalse
placeholderplaceholderPlaceholder text of the input. Defaults to the translated "select send date and time" text.stringsalla.lang.get('blocks.buy_as_gift.select_send_date_and_time')
positionpositionWhere 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"
positionElementposition-elementThe element the calendar is positioned against. Defaults to the date input. Set it as a JS property.HTMLElement
prevArrowprev-arrowHTML of the icon used to go to the previous month.string'<span class="sicon-keyboard_arrow_left"></span>'
requiredrequiredMarks the input as required for form validation.boolean
shorthandCurrentMonthshorthand-current-monthWhether to display the current month name in shorthand mode, e.g. "Sep" instead "September"booleanfalse
showMonthsshow-monthsHow many months the calendar shows at the same time. Defaults to 1.number1
staticstaticPlaces the calendar inside the component's wrapper, next to the input, instead of at the end of body.booleanfalse
time_24hrtime_-2-4hrShows the time picker in 24 hour mode without AM/PM. Used with enable-time. The attribute is time_24hr.booleanfalse
valuevalueThe 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.stringnull
weekNumbersweek-numbersShows week numbers in the calendar.booleanfalse
wrapwrapFlatpickr wrap option for external toggle elements. See https://chmln.github.io/flatpickr/examples/#flatpickr-external-elementsbooleanfalse

Events

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

EventDescriptionDetail
invalidInputFires when the input fails validation, for example when it is required and empty on form submit. event.detail is the native invalid event.any
pickedFires when the user picks a date or time. event.detail is the new value as a string in dateFormat.any

Used inside: <salla-gifting>, <salla-product-options>, <salla-user-profile>.

On this page