Choose a version:

Date field

The date field component captures date input with a consistent interface for date selection and proper validation. Use it to collect date information in forms, scheduling interfaces, or data entry workflows.

The component supports manual text entry. For visual calendar-based selection, consider using date picker or date spinner components.

Support

Targets (9)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the DateField component.

Anchor to details details string: The additional text to provide context or guidance for the field. This text is displayed along with the field and its label to offer more information or instructions to the user. This will also be exposed to screen reader users.
Anchor to disabled disabled boolean Default: false: Whether the field is disabled, preventing user interaction. Use when the field is temporarily unavailable due to application state, permissions, or dependencies.
Anchor to error error string: An error message to indicate a problem to the user. The field will be given specific stylistic treatment to communicate issues that must be resolved immediately.
Anchor to id id string: A unique identifier for the element used for targeting with CSS, JavaScript, or accessibility features.
Anchor to label label string: The content to use as the field label that describes the date information being requested.
Anchor to value value string: 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 field component provides event callbacks for handling user interactions. Learn more about handling events.

Anchor to blur blur (event: <"s-date-field">) => void: Called when the element loses focus.
Anchor to change change (event: <"s-date-field">) => void: Called after editing completes, typically on blur.
Anchor to focus focus (event: <"s-date-field">) => void: Called when the element receives focus.
Anchor to input input (event: <"s-date-field">) => 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 Capture date input with a date fieldCapture date input with a date field

Capture date input using a date field component with built-in validation and picker integration. This example shows a basic date field with label and placeholder text.

Capture date input with a date field

<s-date-field

label="Date"

value="2025-10-08"

Anchor to Handle date selection eventsHandle date selection events

Subscribe to date input events to respond when merchants select or enter dates. This example shows how to handle onChange events to capture date selections, enabling real-time validation, date range checks, or dynamic scheduling behavior based on merchant input.

Handle date selection events

<s-date-field

label="Order date"

value="2024-10-26"

onInput={(event) => console.log('Input:', event.currentTarget.value)}

onChange={(event) => console.log('Change:', event.currentTarget.value)}

onFocus={(event) => console.log('Focused with:', event.currentTarget.value)}

onBlur={(event) => console.log('Blurred with:', event.currentTarget.value)}

Anchor to Best practicesBest practices

Choose for direct text input: Use date field when users know the exact date and can type it efficiently. Use date picker for calendar selection or date spinner for space-constrained layouts.
Explain date constraints: Use details to clarify requirements like "Select a date within the next 30 days" or "Must be a future date."
Write actionable error messages: Provide clear validation messages for invalid dates that help users correct their input.

Was this page helpful?