Choose a version:

Date picker

The date picker 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 date spinner instead. For text date entry, use date field.

Support

Targets (12)

Supported targets

Anchor to Use casesUse cases

Visual selection: Provide visual date selection for appointments or scheduling workflows.
Report filtering: Enable quick date selection for filtering reports or analytics.
Touch optimization: Support touch-optimized date input on POS devices.
Calendar context: Allow users to see calendar context like day of week when selecting dates.

Anchor to PropertiesProperties

Configure the following properties on the DatePicker component.

Anchor to id id string: A unique identifier for the element used for targeting with CSS, JavaScript, or accessibility features.
Anchor to value value string Default: "": The currently selected date value in ISO 8601 format (YYYY-MM-DD, for example, "2024-05-15"). An empty string means no date is selected. Other date formats require conversion before setting this property. Validation occurs when the user finishes editing (on blur), rather than on every keystroke, so invalid dates are flagged after completing entry.

Anchor to EventsEvents

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: Called when the element loses focus.
Anchor to change change (event: <"s-date-picker">) => void: Called after editing completes, typically on blur.
Anchor to focus focus (event: <"s-date-picker">) => void: Called when the element receives focus.
Anchor to input input (event: <"s-date-picker">) => void: Called when the user makes any changes in the field.

CallbackEvent

Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior.

bubbles
Whether the event bubbles up through the DOM tree.
```
boolean
```
cancelable
Whether the event can be canceled.
```
boolean
```
composed
Whether the event will trigger listeners outside of a shadow root.
```
boolean
```
currentTarget
The element that the event listener is attached to.
```
HTMLElementTagNameMap[T]
```
detail
Additional data associated with the event.
```
any
```
eventPhase
The current phase of the event flow.
```
number
```
target
The element that triggered the event.
```
HTMLElementTagNameMap[T] | null
```

Anchor to ExamplesExamples

Anchor to Select dates with a calendar pickerSelect dates with a calendar picker

Enable visual date selection using a date picker 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"

/>

Anchor to Control picker visibilityControl picker visibility

Open the date picker from a button by setting the button's command property to --show and its commandFor property to the date picker's id. This example uses an s-button to open the calendar picker and an onChange handler to capture the selected date, 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)}

/>

</>;

Anchor to Handle date selection eventsHandle date selection events

Subscribe to date selection events to respond when merchants pick a date from the calendar. This example handles the onInput, onChange, onFocus, and onBlur events. onChange captures the selected date, enabling validation, scheduling logic, or dynamic updates based on the chosen date, and onFocus and onBlur fire when the picker is revealed and dismissed.

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 date picker when users benefit from seeing a calendar view, like selecting dates relative to today or needing weekday context. Use date spinner for tight spaces or date field 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?