Date pickers

Date pickers let people choose a day from a calendar rather than typing one. Reach for one when the day of the week, the position in the month or the distance from today matters, like a delivery slot, a holiday or an appointment. For a date the person already knows by heart, such as a birthday, the text field alone is usually faster. That is why every picker here keeps its input editable.

Three components cover the Material 3 variants: DockedDatePicker anchors a calendar under a text field, DatePickerDialog opens the same calendar as a modal, and DateRangePicker selects a start and an end day.

Every picker uses the same value shape: an ISO YYYY-MM-DD string built from local calendar fields, so it never slips a day across a timezone boundary. The docked and the modal picker also keep a hidden input in sync, so passing name submits the value with the surrounding form.

Usage#

value is bindable. Typing in the field and picking a day stay in sync; inside the calendar the selection is provisional until OK confirms it, and Cancel discards it.

The field stays yours while you type: a half-finished date is never rewritten, and value simply holds nothing until the text describes a real, selectable day. Leaving the field tidies a loose entry, so 8/1/2025 settles as 08/01/2025. It also marks the field invalid if what you typed is not a date it can take.

Value: 2025-08-17

<script lang="ts">
	import { DockedDatePicker } from 'noph-ui'

	let basic = $state<string | undefined>('2025-08-17')
</script>

<DockedDatePicker bind:value={basic} label="Date" />

Anatomy#

The docked container follows the Material 3 measurements exactly, so it lines up with the rest of a Material layout without nudging. Its height is not fixed: a docked picker sizes itself to the month, so it is 460dp for a month that spills into six week rows and 48dp shorter for every row it does not need. The height animates as you move between months.

Reacting to a change#

onchange fires whenever the committed value changes, whether it came from the calendar or from typing. It receives the ISO string, or undefined when the field is cleared.

Last event: none yet

<DockedDatePicker
	bind:value={watched}
	label="Date"
	onchange={(next) => console.log(next)}
/>

Text field variants#

The field is the library's TextField, so variant takes outlined (the default) or filled.

<DockedDatePicker bind:value label="Outlined" />
<DockedDatePicker bind:value label="Filled" variant="filled" />

Localisation#

Month names, weekday names and the numeric input order all come from Intl. Without a locale the runtime's own locale is used; pass one to pin it. The supporting text under the field is generated from the same pattern, so a German picker asks for DD.MM.YYYY and parses 17.08.2025.

<DockedDatePicker bind:value label="Datum" locale="de-DE" />
<DockedDatePicker bind:value label="日付" locale="ja-JP" />

First day of the week#

The first column is derived from the locale through Intl.Locale#getWeekInfo. On an engine that does not implement it the calendar falls back to Sunday, so set firstDayOfWeek explicitly (0 = Sunday … 6 = Saturday) when the week start has to be certain.

<DockedDatePicker bind:value label="Week starts Monday" firstDayOfWeek={1} />

Bounding the selection#

min and max are inclusive ISO days. They grey out the days outside the window, stop the month and year steppers at the edge, and disable the months and years that fall entirely outside it.

<DockedDatePicker
	bind:value={bounded}
	label="Within {thisYear}"
	min="{thisYear}-01-01"
	max="{thisYear}-12-31"
/>

Disabling individual days#

isDateEnabled runs for every rendered day; return false to disable it. Use it for rules a range cannot express, such as weekends, public holidays or days already fully booked.

const weekdaysOnly = (date: Date) => date.getDay() !== 0 && date.getDay() !== 6

<DockedDatePicker
	bind:value={booking}
	label="Appointment"
	min={isoToday}
	isDateEnabled={weekdaysOnly}
/>

Restricting the year menu#

yearRange sets the years offered in the year menu, defaulting to [1900, 2100]. Narrowing it keeps a long scroll from getting in the way. For a date of birth, pair it with a max of today.

<DockedDatePicker
	bind:value={birthday}
	label="Date of birth"
	yearRange={[1920, 2026]}
	max={isoToday}
/>

Days of neighbouring months#

The calendar shows only the days of the displayed month and leaves the surrounding cells empty, the way the Material calendar draws it. The docked specification sheets do fill those cells, so adjacentMonthDays renders the leading and trailing days instead. Keyboard navigation crosses the month boundary either way.

<DockedDatePicker
	bind:value={adjacent}
	label="With adjacent days"
	adjacentMonthDays
/>

Controlling the calendar#

displayMonth is the month on screen. It follows the selection until the person navigates, and binding it lets you park the calendar somewhere useful, such as the start of a booking season. You can also read back where they browsed to while the calendar is open: closing it restores whatever you set, so the picker reopens where you put it rather than three years away.

Showing: 2025-08-01

<DockedDatePicker
	bind:value={steered}
	bind:displayMonth={steeredMonth}
	bind:open={steeredOpen}
	label="Season"
/>
<Button
	onclick={() => {
		steeredMonth = '2026-12-01'
		steeredOpen = true
	}}
>
	Show December
</Button>

Opening it yourself#

open is bindable, so the calendar can be opened from anywhere and read back when the person dismisses it. Clicking outside still closes it, so drive it with a plain open button rather than a toggle.

Open: false

<DockedDatePicker bind:value bind:open={isOpen} label="Date" />
<Button onclick={() => (isOpen = true)}>Open the calendar</Button>

Forms and validation#

Passing a name submits the ISO value with the surrounding form through a hidden input, so no JavaScript is needed to read it back. The constraints stay on the visible field rather than that hidden one, so a blocked submit reports against a control the browser can focus and point at, and the picker validates the way a native <input type="date"> does.

That means :user-invalid switches on at a submit attempt, which browsers do even for a form marked novalidate, and never while a date is still being typed. The field is additionally marked on blur, which the platform only does in Firefox, so the feedback is the same everywhere. invalidDateMessage sets the text the browser reports.

issues replaces the supporting text with your own messages and turns the field red, so it pairs with whatever validation library the form already uses.

Nothing submitted yet.

<form onsubmit={handleSubmit} novalidate>
	<DockedDatePicker
		bind:value={formValue}
		label="Delivery date"
		name="deliveryDate"
		issues={formIssues}
		min={isoToday}
		required
	/>
	<Button type="submit" variant="filled">Submit</Button>
</form>

Modal#

DatePickerDialog is the same calendar in a modal, with the selection echoed in a headline and a three-column year grid behind the month button. Prefer it on small screens, or when choosing the date is the whole point of the step rather than one field among many.

Value: 2025-08-17

<Button onclick={() => (dialogOpen = true)}>Pick a date</Button>
<DatePickerDialog bind:open={dialogOpen} bind:value={dialogValue} />

Keyboard entry and custom wording#

modeToggle adds the header button that swaps the calendar for a text field, for people who would rather type. title replaces the supporting line above the headline, and headline overrides the formatted date itself. onconfirm fires on the confirm button, and oncancel on every other way out: the cancel button, Escape, a click on the scrim, or setting open back to false yourself.

<DatePickerDialog
	bind:open={entryOpen}
	bind:value={entryValue}
	title="Arrival date"
	modeToggle
	min={isoToday}
	onconfirm={(next) => console.log(next)}
/>

Range#

DateRangePicker scrolls through months continuously and fills the days between the two ends. The first tap sets the start, the second the end; tapping before the start restarts the range. value is a { start, end } object of ISO days.

The month list is a window rather than the whole year range: it opens on a few months either side of the start day and grows as you scroll, and each month is only as tall as the week rows it needs. The seven grids share one tab stop, so the list is one stop in the tab order and the arrow keys carry focus from one month into the next.

The picker takes the presentation the window allows. Below 600dp it fills the screen, square cornered and flat, and confirms from the top bar. From 600dp up it is an ordinary modal instead: a dialog the width of the calendar, sitting in the scrim with rounded corners, the month list scrolling inside it and Cancel and Save at the bottom. The switch is a media query, so it costs nothing to render and the server sends what the browser shows. Narrow the window to see it change.

Value: undefined → undefined

<script lang="ts">
	import { DateRangePicker } from 'noph-ui'
	import type { DateRange } from 'noph-ui/types'

	let range = $state<DateRange>({})
	let rangeOpen = $state(false)
</script>

<Button onclick={() => (rangeOpen = true)}>Pick a range</Button>
<DateRangePicker bind:open={rangeOpen} bind:value={range} title="Select stay" />

Two fields#

A booking form usually shows the range as two fields rather than a button, and the calendar is what opens behind them. DateRangePicker is only the popup, so the pair of fields stays yours: bind the same { start, end } to both, and the range is the single place the two edges live.

The calendar is the only editor, so the fields are read-only and simply read the range back through formatDate. That is the whole example: nothing mirrors the text and nothing has to be kept in sync, because the two edges only ever change in one place. Clicking a field opens the picker, and the calendar button does the same for the keyboard.

Value: undefined → undefined

<script lang="ts">
	import { DateRangePicker, formatDate, IconButton, parseISODate, TextField } from 'noph-ui'
	import { CalendarToday } from 'noph-ui/icons'
	import type { DateRange } from 'noph-ui/types'

	let open = $state(false)
	let stay = $state<DateRange>({})

	const asText = (iso?: string) => {
		const date = parseISODate(iso)
		return date ? formatDate(date) : ''
	}
</script>

{#snippet calendarButton(edge: string)}
	<IconButton
		type="button"
		aria-label="Open the calendar for the {edge} date"
		aria-haspopup="dialog"
		aria-expanded={open}
		onclick={() => (open = true)}
	>
		<CalendarToday />
	</IconButton>
{/snippet}
{#snippet startButton()}{@render calendarButton('start')}{/snippet}
{#snippet endButton()}{@render calendarButton('end')}{/snippet}

<TextField
	label="Start"
	readonly
	value={asText(stay.start)}
	onclick={() => (open = true)}
	end={startButton}
/>
<TextField
	label="End"
	readonly
	value={asText(stay.end)}
	onclick={() => (open = true)}
	end={endButton}
/>

<DateRangePicker bind:open bind:value={stay} title="Select stay" />

Theming#

Colours and shapes come from the theme, and every part exposes a custom property for the cases the theme cannot reach. Set them on the picker itself; they inherit into the calendar.

Example#

<DockedDatePicker
	bind:value
	label="Date"
	--np-date-picker-date-selected-container-color="var(--np-color-tertiary)"
	--np-date-picker-date-selected-label-color="var(--np-color-on-tertiary)"
	--np-date-picker-date-today-outline-color="var(--np-color-tertiary)"
	--np-date-picker-date-today-label-color="var(--np-color-tertiary)"
	--np-date-picker-date-container-shape="var(--np-shape-corner-small)"
/>

Motion and gestures#

Movement follows the Material 3 motion scheme, using the theme's own motion tokens: travel runs on the spatial tokens, fades on the effects tokens.

Swipe horizontally across the calendar to move between months, and scroll the year picker vertically to move between years. Every transition above is wrapped in prefers-reduced-motion: no-preference, so the picker resizes and swaps views instantly for anyone who has asked for less motion.

Accessibility#

The grid is a role="grid" table named after the month it shows, with the weekday names as column headers and a single roving tab stop, so the calendar is one stop in the tab order rather than forty-two. Each day is labelled with its full date, today carries aria-current="date", and the selected day is aria-selected on its cell and names itself "…, selected" so the state is announced on the day that has focus. selectedDateLabel translates that suffix.

Navigating past the edge of the month moves to the neighbouring one and keeps focus on the day it lands on, in the range picker too. A key that would leave the min and max window stops on the bound instead. The label strings are all props, including cancelLabel, confirmLabel, openCalendarLabel, selectedDateLabel and the month and year navigation labels, so a localised app can translate the whole control.

The modal picker opens with focus on the grid rather than on the dialog, so the arrow keys work straight away, and it names itself with its title.

API#

DockedDatePicker#

Anything not listed here is forwarded to the picker's root element.

Bindables#

DatePickerDialog#

Takes the same locale, firstDayOfWeek, min, max, yearRange, isDateEnabled, adjacentMonthDays, label, supportingText, name, form, cancelLabel, confirmLabel, previousMonthLabel, nextMonthLabel, selectYearLabel, selectedDateLabel and onchange props as DockedDatePicker. It has no year steppers or month menu, so those labels do not apply, and it validates by disabling confirm rather than through the field, so required and invalidDateMessage do not either. On top of the shared props:

Bindable: value, displayMonth, open and element. Calendar navigation is not kept: the dialog reopens on the month it was given, or on the month of value.

DateRangePicker#

Takes the same locale, firstDayOfWeek, min, max, yearRange, isDateEnabled, adjacentMonthDays and selectedDateLabel props as the other pickers. It has no text field and no month or year navigation, so none of those labels apply, and it does not submit with a form.

Bindable: value (a DateRange), open and element.

Calendar and YearGrid#

The two grids the pickers are built from are exported as well, for a layout none of the three covers, such as a calendar sitting permanently on a page. They are lower level than the pickers: they hold no value, take Date objects rather than ISO strings, and leave the month on screen, the selection and the keyboard entry points to the caller.

Date helpers#

The date maths behind the pickers is exported too, so an app can share the same timezone-safe handling.