Date Picker
Allow users to select a specific date or date range.
Anchor to datepickerDatePicker
- Anchor to allowallowallowstringstringDefault: ""Default: ""
Dates that can be selected.
A comma-separated list of dates, date ranges. Whitespace is allowed after commas.
The default
''allows all dates.- Dates in
format allow a single date. - Dates in
format allow a whole month. - Dates in
format allow a whole year. - Ranges are expressed as
start--end. - Ranges are inclusive.- If either
startorendis omitted, the range is unbounded in that direction. - If parts of the date are omitted for
start, they are assumed to be the minimum possible value. So2024--is equivalent to2024-01-01--. - If parts of the date are omitted for
end, they are assumed to be the maximum possible value. So--2024is equivalent to--2024-12-31. - Whitespace is allowed either side of
--.
- If either
- Dates in
- Anchor to allowDaysallowDaysallowDaysstringstringDefault: ""Default: ""
Days of the week that can be selected. These intersect with the result of
allowanddisallow.A comma-separated list of days. Whitespace is allowed after commas.
The default
''has no effect on the result ofallowanddisallow.Days are
sunday,monday,tuesday,wednesday,thursday,friday,saturday.- Anchor to defaultValuedefaultValuedefaultValuestringstringDefault: ""Default: ""
Default selected value.
The default means no date is selected.
If the provided value is invalid, no date is selected.
- If
type="single", this is a date informat. - If
type="multiple", this is a comma-separated list of dates informat. - If
type="range", this is a range informat. The range is inclusive.
- If
- Anchor to defaultViewdefaultViewdefaultViewstringstring
Default month to display in
format.This value is used until
viewis set, either directly or as a result of user interaction.Defaults to the current month in the user's locale.
- Anchor to disallowdisallowdisallowstringstringDefault: ""Default: ""
Dates that cannot be selected. These subtract from
allow.A comma-separated list of dates, date ranges. Whitespace is allowed after commas.
The default
''has no effect onallow.- Dates in
format disallow a single date. - Dates in
format disallow a whole month. - Dates in
format disallow a whole year. - Ranges are expressed as
start--end. - Ranges are inclusive.- If either
startorendis omitted, the range is unbounded in that direction. - If parts of the date are omitted for
start, they are assumed to be the minimum possible value. So2024--is equivalent to2024-01-01--. - If parts of the date are omitted for
end, they are assumed to be the maximum possible value. So--2024is equivalent to--2024-12-31. - Whitespace is allowed either side of
--.
- If either
- Dates in
- Anchor to disallowDaysdisallowDaysdisallowDaysstringstringDefault: ""Default: ""
Days of the week that cannot be selected. This subtracts from
, and intersects with the result ofallowanddisallow.A comma-separated list of days. Whitespace is allowed after commas.
The default
''has no effect on.Days are
sunday,monday,tuesday,wednesday,thursday,friday,saturday.- Anchor to namenamenamestringstring
An identifier for the field that is unique within the nearest containing form.
- Anchor to typetypetype"single" | "range""single" | "range"Default: "single"Default: "single"
- Anchor to valuevaluevaluestringstringDefault: ""Default: ""
Current selected value.
The default means no date is selected.
If the provided value is invalid, no date is selected.
Otherwise:
- If
type="single", this is a date informat. - If
type="multiple", this is a comma-separated list of dates informat. - If
type="range", this is a range informat. The range is inclusive.
- If
- Anchor to viewviewviewstringstring
Displayed month in
format.is called when this value changes.Defaults to
.
Anchor to eventsEvents
Learn more about registering events.
- Anchor to blurblurblurCallbackEventListener<typeof tagName> | nullCallbackEventListener<typeof tagName> | null
- Anchor to changechangechangeCallbackEventListener<typeof tagName> | nullCallbackEventListener<typeof tagName> | null
- Anchor to focusfocusfocusCallbackEventListener<typeof tagName> | nullCallbackEventListener<typeof tagName> | null
- Anchor to inputinputinputCallbackEventListener<typeof tagName> | nullCallbackEventListener<typeof tagName> | null
- Anchor to viewchangeviewchangeviewchangeCallbackEventListener<typeof tagName> | nullCallbackEventListener<typeof tagName> | null
CallbackEventListener
(EventListener & {
(event: CallbackEvent<T>): void;
}) | nullCallbackEvent
Event & {
currentTarget: HTMLElementTagNameMap[T];
}Preview
Examples
Code
jsx
<s-date-picker view="2025-05" type="range" value="2025-05-28--2025-05-31" />html
<s-date-picker view="2025-05" type="range" value="2025-05-28--2025-05-31" ></s-date-picker>Single date selection
Description
Demonstrates a date picker configured for selecting a single date with a default value and specific month view.
jsx
<s-date-picker type="single" name="delivery-date" value="2024-01-15" view="2024-01" />html
<s-date-picker type="single" name="delivery-date" value="2024-01-15" view="2024-01" ></s-date-picker>With date restrictions
Description
Illustrates how to restrict date selection to a specific date range, preventing selection of past or future dates outside the allowed period.
jsx
<s-date-picker type="single" name="appointment-date" disallow="past" allow="2024-06-01--2024-06-31" view="2024-06" />html
<!-- Disable past dates and far future dates --> <s-date-picker type="single" name="appointment-date" disallow="past" allow="2024-06-01--2024-06-31" view="2024-06" ></s-date-picker>Handling onChange callbacks
Description
Demonstrates how to handle onChange callbacks for both single and range date pickers, showing how to extract and process the selected values.
jsx
const [dateRange, setDateRange] = useState('2024-01-01--2024-01-31'); const [orderNumber, setOrderNumber] = useState(''); const handleApplyFilters = () => { console.log('Applying filters:', { orderNumber, dateRange }); } return ( <s-stack gap="base"> <s-text-field label="Order number" placeholder="Search orders..." value={orderNumber} onChange={(event) => setOrderNumber(event.currentTarget.value)} /> <s-date-picker type="range" name="order-date-range" value={dateRange} onChange={(event) => setDateRange(event.currentTarget.value)} view="2024-01" /> <s-button onClick={handleApplyFilters}>Apply filters</s-button> </s-stack> )html
<form> <s-text-field label="Order number" placeholder="Search orders..." ></s-text-field> <s-date-picker type="range" name="order-date-range" value="2024-01-01--2024-01-31" view="2024-01" ></s-date-picker> <s-button type="submit">Apply filters</s-button> </form>With quick date selection
Description
Illustrates a date picker with quick preset buttons and onChange callback to capture user selections and update the displayed value.
jsx
const [value, setValue] = useState('2025-01-01--2025-01-31'); const last7Days = () => { setValue('2025-01-07--2025-01-13'); } const last30Days = () => { setValue('2024-12-14--2025-01-13'); } const thisMonth = () => { setValue('2025-01-01--2025-01-31'); } return ( <s-stack gap="base"> <s-button-group> <s-button slot="secondary-actions" onClick={last7Days}>Last 7 days</s-button> <s-button slot="secondary-actions" onClick={last30Days}>Last 30 days</s-button> <s-button slot="secondary-actions" onClick={thisMonth}>This month</s-button> </s-button-group> <s-date-picker type="range" name="analytics-period" id="analytics-picker" view="2025-01" value={value} onChange={(event) => { console.log('Date range changed:', event.currentTarget.value); setValue(event.currentTarget.value); }} /> <s-text>Selected range: {value}</s-text> </s-stack> )html
<!-- Quick date selection with onChange callback --> <s-stack gap="base"> <s-button-group> <s-button slot="secondary-actions" id="last-7-days">Last 7 days</s-button> <s-button slot="secondary-actions" id="last-30-days">Last 30 days</s-button> <s-button slot="secondary-actions" id="this-month">This month</s-button> </s-button-group> <s-date-picker type="range" name="analytics-period" id="analytics-picker" value="2025-01-01--2025-01-31" view="2025-01" onchange="console.log('Date range changed:', event.currentTarget.value)" ></s-date-picker> <s-text id="selected-range"> Selected range: 2025-01-01--2025-01-31 </s-text> </s-stack> <script> const picker = document.getElementById('analytics-picker'); const display = document.getElementById('selected-range'); // Handle picker changes picker.addEventListener('change', (event) => { display.textContent = `Selected range: ${event.currentTarget.value}`; }); // Quick selection buttons document.getElementById('last-7-days').addEventListener('click', () => { picker.value = '2025-01-07--2025-01-13'; display.textContent = 'Selected range: 2025-01-07--2025-01-13'; }); document.getElementById('last-30-days').addEventListener('click', () => { picker.value = '2024-12-14--2025-01-13'; display.textContent = 'Selected range: 2024-12-14--2025-01-13'; }); document.getElementById('this-month').addEventListener('click', () => { picker.value = '2025-01-01--2025-01-31'; display.textContent = 'Selected range: 2025-01-01--2025-01-31'; }); </script>
Anchor to best-practicesBest practices
- Use smart defaults and highlight common selections
- Don't use to enter a date that is many years in the future or the past