Date Picker
What it does
Date filters in Dirigible plugins (such as a From and To date on a search page) show a button with the chosen date, or Pick a date when none is chosen. Pressing it opens a small month calendar in your site's colors. It looks and works the same in Safari, Chrome, Firefox and on phones, where each browser's own date field looks different and Safari's is hard to use.
- Today jumps to today's date and Clear removes the date.
- Today is circled, and the chosen date is filled with your Primary color.
- Dates a filter doesn't allow (before its first or after its last date) are greyed out and can't be picked.
- The week starts on the day set under Settings → General → Week Starts On, and "today" follows your site's time zone there, even on pages served from the cache.
- Month and day names follow your site's language.
Keyboard and screen readers
Visitors can use it without a mouse: Enter or Space opens the calendar on the chosen date (or today), the arrow keys move by day and week (left and right follow the page's reading direction), Home and End go to the start and end of the week, Page Up and Page Down change the month, and Enter or Space picks a date. Esc closes the calendar and leaves any panel around it open. Screen readers hear the field's label and the date on the button, each day's full date in the calendar, and the new month's name when it changes.
Things to know
- There's nothing to set up: it's part of the theme, and a plugin uses it on its own date filters.
- If the page can't run scripts, visitors see the browser's own date field, which still works.
For plugin developers
The theme registers (doesn't enqueue) a script and a style, both with the handle ds-date-picker. Enqueue both only when the handle is registered, so an older theme keeps the native field:
if (wp_script_is('ds-date-picker', 'registered')) {
wp_enqueue_script('ds-date-picker');
wp_enqueue_style('ds-date-picker');
}
Mark each field with data-ds-date-picker and give it a <label>:
<label for="from">From</label>
<input type="date" id="from" name="from" min="2026-01-01" data-ds-date-picker>
- Every marked field is enhanced on
DOMContentLoaded. For fields added later (content swapped in after a fetch), callwindow.dsDatePicker.enhance(root); enhancing a field twice does nothing. - The native field stays in the form, hidden, and is what submits. Picking or clearing a date sets its value and fires bubbling
inputandchangeevents. Setting its value from a script and firingchange, or resetting the form, updates the button.minandmaxare respected. - The calendar opens in the page right after its button, not moved to the end of the page, so it works inside a
popoverpanel or a modal drawer with a focus trap. Tab stays inside the calendar while it's open, and Esc closes only the calendar (the keydown is cancelled and stopped). - It floats over the content below it, except inside a
[popover], a<dialog>or an[aria-modal="true"]panel, where it opens in the flow and pushes the content down, so the panel isn't clipped. There it's as wide as its column but never narrower than the week needs (15rem), so in a narrow column it overhangs, leftward from a column at the panel's right edge. Setdata-ds-date-picker="overlay"or"inline"to choose. - Don't rely on
required: browsers can't show their "fill in this field" message on the hidden field (the button gets focus, with no message). Check the value in your own script instead. - Nothing changes until the stylesheet has applied, so a late stylesheet never shows an unstyled button. The button is drawn like the theme's form fields at the same size, so the swap doesn't move anything. Without the stylesheet the native field stays.