Choose a version:

DatePicker

The datePicker component allows merchants to select dates using a calendar interface. Use it when merchants benefit from seeing dates in context of the full month, such as selecting dates relative to today or needing weekday context.

The component supports single dates, multiple dates, and date ranges. For tight spaces, consider using dateSpinner instead. For text date entry, use dateField.

Support

Targets (18)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the datePicker component.

Configure the following properties on the date picker component.

Anchor to id id string: A unique identifier for the element.
Anchor to value value string 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 in YYYY-MM-DD format.

If type="multiple", this is a comma-separated list of dates in YYYY-MM-DD format.

If type="range", this is a range in YYYY-MM-DD--YYYY-MM-DD format. The range is inclusive.

Anchor to EventsEvents

The datePicker component provides event callbacks for handling user interactions. Learn more about handling events.

The date picker component provides event callbacks for handling user interactions. Learn more about handling events.

Anchor to blur blur (event: <"s-date-picker">) => void: Callback when the date picker is dismissed.
Anchor to change change (event: <"s-date-picker">) => void: Callback when the user selects a date from the picker that is different to the current value.
Anchor to focus focus (event: <"s-date-picker">) => void: Callback when the date picker is revealed.
Anchor to input input (event: <"s-date-picker">) => void: Callback when the user selects a date from the picker.

Anchor to ExamplesExamples

Examples

Select dates with a calendar picker

<s-button command="--show" commandFor="date-picker">

Show

</s-button>

<s-date-picker

id="date-picker"

value="2025-10-08"

Preview

Examples

Description
Enable visual date selection using a datePicker component with a calendar interface. This example shows a basic date picker with month view and date selection.
Select dates with a calendar picker
```
<s-button command="--show" commandFor="date-picker">
  Show
</s-button>
<s-date-picker 
  id="date-picker" 
  value="2025-10-08"
/>
```
Description
Control datePicker visibility programmatically using the command system with `show` and `hide` methods. This example demonstrates using button commands to display or dismiss the calendar picker, enabling custom trigger patterns for date selection workflows.
Control picker visibility
```
<>
  <s-button command="--show" commandFor="date-picker">
    Select Date
  </s-button>
  <s-date-picker
    id="date-picker"
    value="2024-10-26"
    onChange={(event) => console.log('Date selected:', event.currentTarget.value)}
  />
</>;
```
Description
Subscribe to date selection events to respond when merchants pick a date from the calendar. This example shows how to handle `onChange` events to capture selected dates, enabling validation, scheduling logic, or dynamic updates based on the chosen date.
Handle date selection events
```
<s-date-picker 
  value="2024-10-26"
  onInput={(event) => console.log('Input:', event.currentTarget.value)}
  onChange={(event) => console.log('Change:', event.currentTarget.value)}
  onFocus={(event) => console.log('Focus')}
  onBlur={(event) => console.log('Blur')}
/>
```

Anchor to Best practicesBest practices

Choose for calendar-based selection: Use datePicker when users benefit from seeing a calendar view, like selecting dates relative to today or needing weekday context. Use dateSpinner for tight spaces or dateField when users know the exact date.
Provide adequate space: Ensure sufficient spacing around the picker to avoid interfering with on-screen keyboards or other interactive elements.

Was this page helpful?

Supported targets

Supported targets

Anchor to PropertiesProperties

Anchor to EventsEvents

CallbackEvent

Anchor to ExamplesExamples

Anchor to Best practicesBest practices