- DUnavailable
- DAvailable
<DatePicker
today="2026-10-14"
month="2026-10"
value="2026-10-21"
unavailable={["2026-10-06", "2026-10-07", "2026-10-16", "2026-10-27"]}
/>Installation
npx @vds-testing/cli add date-pickerbunx @vds-testing/cli add date-pickerpnpm dlx @vds-testing/cli add date-pickeryarn dlx @vds-testing/cli add date-pickerpnpm install @vds-testing/react @vds-testing/stylespnpm install @vds-testing/elements @vds-testing/stylesPackages 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.
- DUnavailable
- DAvailable
<DatePicker today="2026-10-14" month="2026-10" min="2026-10-19" max="2026-10-30" />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.
- DUnavailable
- DAvailable
<DatePicker allowPast today="2026-10-14" month="2026-10" value="2026-10-05" />In a form
Set name to submit the selected date with the form. The component keeps a hidden input in sync with the selection.
<form method="get" class="space-y-4">
<DatePicker name="visit-date" today="2026-10-14" month="2026-10" />
<Button type="submit">Book visit</Button>
</form>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
--borderdivider - 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.