VDS

Date Picker

beta

A calendar grid for choosing a single date, with unavailable days and full keyboard support.

October 2026
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday
Key:
  • Unavailable
  • Available

Installation

npx @vds-testing/cli add date-picker
npx @vds-testing/cli add date-picker
pnpm install @vds-testing/react @vds-testing/styles
pnpm install @vds-testing/elements @vds-testing/styles

Packages are consumed via the workspace locally and are not published yet. See Installation for CSS setup.

Usage

All dates are ISO strings: YYYY-MM-DD for days and YYYY-MM for the visible month. The week starts on Monday.

Astro:

import { DatePicker } from "@/components/vds/date-picker"
<DatePicker value="2026-10-21" unavailable={["2026-10-16"]} />

React:

import { DatePicker } from "@vds-testing/react"
const [date, setDate] = useState("2026-10-21");

<DatePicker value={date} onValueChange={setDate} unavailable={["2026-10-16"]} />

Web Components:

<script type="module">
  import "@vds-testing/elements";
</script>
<vds-date-picker value="2026-10-21" unavailable="2026-10-16,2026-10-27"></vds-date-picker>

Examples

With min and max

Days before min or after max are unavailable. Both bounds are inclusive.

October 2026
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday
Key:
  • Unavailable
  • Available

Allowing past dates

By default, days before today are unavailable and the previous-month button is disabled on the current month. Set allowPast to make past days selectable and let the calendar move back in time.

October 2026
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday
Key:
  • Unavailable
  • Available

In a form

Set name to submit the selected date with the form. The component keeps a hidden input in sync with the selection.

October 2026
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday
Key:
  • Unavailable
  • Available

States

Each day has exactly one state. When more than one applies, the first in this table wins.

State Meaning Token
adjacent Day from the previous or next month that fills a partial week. Not interactive --muted-foreground
unavailable In the past (unless allowPast), listed in unavailable, or outside min / max. Focusable but cannot be selected --muted-foreground with a diagonal strikethrough
selected The current value --color-brand fill, white text
today The current date --color-brand outline
available Any other selectable day --foreground, --color-brand-subtle on hover

Keyboard

Key Action
Tab Moves focus into the grid, to the selected day, else today, else the first available day
Arrow Left / Arrow Right Previous / next day
Arrow Up / Arrow Down Same day in the previous / next week
Home / End First (Monday) / last (Sunday) day of the week
Page Up / Page Down Same day in the previous / next month
Enter / Space Selects the focused day if it is available

Moving past the first or last day of the visible month shows the adjacent month and keeps focus on the target date. Keys that would move into a month before today (unless allowPast) or before min do nothing.

Anatomy

  • Header with previous and next month buttons and a live month label (the month name; the year is announced to screen readers only), above a --border divider
  • Grid with a centred weekday row and one row per week (4 to 6 rows)
  • Key explaining the unavailable and available styles

All text is vds-paragraph-s (0.875rem). Weekday labels are --foreground at medium weight; everything else is regular.

Props

Prop Type Default Description
value string - Selected date, YYYY-MM-DD. Controlled in React
defaultValue string - Initial selected date (React, uncontrolled)
onValueChange (value: string) => void - Called when the user selects a different date (React)
month string Month of value, else of today Visible month, YYYY-MM
today string The local date Date marked as today, YYYY-MM-DD. Pass it when server and client time zones may differ
min string - Earliest selectable date
max string - Latest selectable date
unavailable string[] [] Dates that cannot be selected
allowPast boolean false Make days before today selectable and allow navigating to earlier months. allow-past on vds-date-picker
name string - Form field name for the hidden input
class / className string - Additional CSS classes

Web Components use the same attribute names on vds-date-picker. Pass unavailable as a comma-separated list of dates.

Events

Astro and Web Components dispatch a bubbling vds-date-change event when the selection changes. The new date is in event.detail.value.

document.querySelector("vds-date-picker").addEventListener("vds-date-change", (event) => {
  console.log(event.detail.value);
});

React uses onValueChange instead.