SDatePicker <s-date-picker>

A calendar for selecting a single date or a date range. SDatePicker is the typed Vue 3 wrapper for Shopify's Polaris <s-date-picker> web component.

import { SDatePicker } from 'polaris-vue-elements'

Best practices

• Start with a sensible date. Pre-fill value so merchants can make their selection faster.
• Offer shortcuts for common picks. Presets such as "Today", "Last 7 days" or "This month" save merchants from clicking through the calendar.
• Use type="range" for start and end dates. Range selection suits reports, analytics and other filters based on a time period.
• Block dates that don't apply. Use allow and disallow so merchants can't pick dates that are invalid for your use case.
• Leave room around the picker. Give it enough space that it doesn't get in the way of on-screen keyboards or other interactive elements.
• Plan for dates far away. Paging month by month gets tedious beyond a few years, so for dates outside roughly a 5–10 year window, offer presets or let merchants enter the year directly.

<SDatePicker type="range" />

See Shopify's best practices for <s-date-picker> for the full guidance.

Example

Selected: (none)

<script setup>
import { ref } from 'vue'
import { SDatePicker } from 'polaris-vue-elements'

const value = ref('')
</script>

<template>
  <SDatePicker type="single" v-model="value" />
  <p>Selected: {{ value }}</p>
</template>

v-model

v-model on <SDatePicker> binds to the value property and listens for the input DOM event.

<SDatePicker v-model="value" />

is equivalent to:

<SDatePicker :value="value" @input="value = $event.target.value" />

Props

Prop	Type	Description
allow	string	Specifies which dates can be selected as a comma-separated list. An empty string (default) allows all dates. Formats:* - YYYY-MM-DD: Single date - YYYY-MM: Whole month - YYYY: Whole year - start--end: Date range (inclusive, unbounded if start/end omitted) Examples:* - 2024-02--2025: February 2024 through end of 2025 - 2024-05-09, 2024-05-11: Only May 9th and 11th, 2024
allowDays	string	Specifies which days of the week can be selected as a comma-separated list. Further restricts dates from allow and disallow. An empty string (default) has no effect. Valid days*: sunday, monday, tuesday, wednesday, thursday, friday, saturday Example:* saturday, sunday (only weekends)
defaultValue	string	The initially selected date(s) when the component first renders. An empty string means no date is initially selected. - Single date in YYYY-MM-DD format when type is set to "single" - Date range in YYYY-MM-DD--YYYY-MM-DD format (inclusive) when type is set to "range"
defaultView	string	The default month to display in YYYY-MM format. Used until the view callback is set by user interaction or programmatically. Defaults to the current month in the user's locale.
disallow	string	Specifies which dates can't be selected as a comma-separated list. These dates are excluded from those specified in allow. An empty string (default) has no effect. Formats:* - YYYY-MM-DD: Single date - YYYY-MM: Whole month - YYYY: Whole year - start--end: Date range (inclusive, unbounded if start/end omitted) Examples:* - --2024-02: All dates before February 2024 - 2024-05-09, 2024-05-11: May 9th and 11th, 2024
disallowDays	string	Specifies which days of the week can't be selected as a comma-separated list. Excludes days from allowDays and intersects with allow and disallow. An empty string (default) has no effect. Valid days*: sunday, monday, tuesday, wednesday, thursday, friday, saturday Example:* saturday, sunday (no weekends)
name	string	An identifier for the field that is unique within the nearest containing form.
type	"single" | "range"	The type of date selection allowed. - single: Select a single date - range: Select a date range
value	string	The currently selected date(s). An empty string means no date is selected. - Single date in YYYY-MM-DD format when type is set to "single" - Date range in YYYY-MM-DD--YYYY-MM-DD format (inclusive) when type is set to "range"
view	string	The currently displayed month in YYYY-MM format. When changed, the viewchange callback is triggered. Defaults to defaultView.
visibleMonths	"auto" | "1" | "2"	Controls how many months are displayed. - 'auto': Context-driven. Today this renders a single month, matching '1'. - '1': Renders one month at a time. - '2': Renders two consecutive months side-by-side.

Events

Event	Type
blur	FocusEvent
change	Event
focus	FocusEvent
input	Event
viewchange	CustomEvent

Listen for these with @blur-style listeners on <SDatePicker>.