Skip to content
Nana UI

Forms & Inputs

Date Picker

A form field for one date — a move-in date, a due date — that opens a calendar under the field. The value is yyyy-mm-dd and is what the form submits.

View .md Download

The calendar takes focus when it opens, so the arrow keys work at once; Escape or a click outside closes it and returns focus to the field.

The month and year at the top of the calendar are lists: choose a year to jump straight to it. Without bounds the years run from a hundred years back to twenty ahead; set min and max to narrow them.

min and max put days out of reach entirely. isDateDisabled refuses days by rule — here weekends — while still letting the keyboard move across them.

document.getElementById("viewing").isDateDisabled = (iso) =>
[0, 6].includes(new Date(`${iso}T00:00`).getDay());
npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add date-picker --framework web-components
npx @nana-tec/ui add date-picker --framework svelte

Lands in src/lib/components/ui/date-picker/, one file per part. See Svelte setup for Tailwind and the theme.

Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and each component downloads only the first time a page uses it:

import "@nana-tec/ui-components/autoloader";
import "@nana-tec/ui-components/theme";

The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.

Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:

import "@nana-tec/ui-components/date-picker";

Copied in with npx @nana-tec/ui add date-picker? Import your project's own @/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.

<nana-date-picker label="Move-in date" name="moveIn" min="2026-03-01" required></nana-date-picker>
const el = document.querySelector("nana-date-picker");
el.addEventListener("nana-change", (e) => console.log(e.detail));
el.addEventListener("nana-focus", (e) => console.log(e.detail));
el.addEventListener("nana-blur", (e) => console.log(e.detail));

The calendar opens below the field, or above with placement="top-start". When the preferred side has no room it flips to the other, the same way the select and combobox do, so a field near the bottom of the screen still shows the whole month.

<script lang="ts">
import { DatePicker } from '$lib/components/ui/date-picker';
let value = $state('');
</script>
<DatePicker.Root bind:value locale="en-GB" name="moveIn">
<DatePicker.Label>Move-in date</DatePicker.Label>
<DatePicker.Control>
<DatePicker.Input />
<DatePicker.Trigger>Open</DatePicker.Trigger>
<DatePicker.ClearTrigger>Clear</DatePicker.ClearTrigger>
</DatePicker.Control>
<DatePicker.HiddenInput />
<DatePicker.Positioner>
<DatePicker.Content>
<DatePicker.View view="day">
<DatePicker.Context>
{#snippet children(api)}
<DatePicker.ViewControl>
<DatePicker.PrevTrigger>‹</DatePicker.PrevTrigger>
<DatePicker.ViewTrigger><DatePicker.RangeText /></DatePicker.ViewTrigger>
<DatePicker.NextTrigger>›</DatePicker.NextTrigger>
</DatePicker.ViewControl>
<DatePicker.Table>
<DatePicker.TableHead>
<DatePicker.TableRow>
{#each api.weekDays as day, i (i)}
<DatePicker.TableHeader>{day.short}</DatePicker.TableHeader>
{/each}
</DatePicker.TableRow>
</DatePicker.TableHead>
<DatePicker.TableBody>
{#each api.weeks as week, i (i)}
<DatePicker.TableRow>
{#each week as day, j (j)}
<DatePicker.TableCell value={day}>
<DatePicker.TableCellTrigger>{day.getDate()}</DatePicker.TableCellTrigger>
</DatePicker.TableCell>
{/each}
</DatePicker.TableRow>
{/each}
</DatePicker.TableBody>
</DatePicker.Table>
{/snippet}
</DatePicker.Context>
</DatePicker.View>
</DatePicker.Content>
</DatePicker.Positioner>
</DatePicker.Root>

DatePicker.Root owns the state. Bind value (an ISO yyyy-mm-dd string, '' when cleared) and open, or listen with onValueChange(value) and onOpenChange(open). Setting either from outside moves the calendar with it. min, max and isDateUnavailable limit what can be picked, locale and firstDayOfWeek shape the grid, and HiddenInput submits the value under name.

A typed date is read leniently: ISO, the locale’s own order, month names in the locale or English, two-digit years, and words such as “today” or “tomorrow”. format chooses how the picked date is shown back — 'short', 'medium' (the default), 'long', 'full', or your own Intl.DateTimeFormat options.

Add a View with view="month" or view="year" and render api.getMonthsGrid() or api.getYearsGrid() in it; the view trigger climbs from days to months to years.

The rules — which day is focused, what each key does, how a typed date is read — live in core/date-picker; these files only render the parts.

Properties

PropertyAttributeTypeDefaultDescription
clearableclearablebooleanfalseOffer a control that clears the date
disableddisabledbooleanfalseBlocks interaction and leaves the value out of form submission.
errorMessageerror-messagestring''Error under the field while it is invalid, in the error part with role="alert".
errorTexterror-textstring—Deprecated: use error-message with invalid. Setting it also sets invalid.
firstDayOfWeekfirst-day-of-weeknumber1Which weekday starts the week; 0 is Sunday
helperTexthelper-textstring''Help below the field
invalidinvalidbooleanfalseMarks the field invalid and shows error-message in place of the helper text.
isDateDisabled—CalendarDateDisabled | undefined—Refuses dates by rule, such as weekends; receives yyyy-mm-dd
labellabelstring''Label above the field
localelocale——BCP 47 tag for the date on the field and the calendar's names
maxmaxstring''Latest date that can be picked, yyyy-mm-dd
minminstring''Earliest date that can be picked, yyyy-mm-dd
namenamestring''Name the value is submitted under in a form.
openopenbooleanfalseWhether the calendar is open
placementplacementPopupPlacement'bottom-start'Where the calendar opens
requiredrequiredbooleanfalseThe form will not submit while this has no value.
sizesizeDatePickerSize'md'Size preset.
valuevaluestring''The picked date, yyyy-mm-dd

Methods

MethodDescription
clear(): voidClear the date

Events

EventDescription
nana-changeA date was picked or cleared (detail.value)
nana-focusThe field gained focus
nana-blurThe field lost focus

Slots

SlotDescription
placeholderShown on the field when no date is picked

CSS parts

PartDescription
::part(base)The field
::part(trigger)The button that opens the calendar; carries invalid
::part(panel)The panel the calendar opens in
::part(calendar)The calendar
::part(label)The label
::part(req)The required marker
::part(trigger-label)The trigger label
::part(clear)The clear
::part(help)The helper text
::part(error)The error message
::part(lead)The calendar icon on the field
::part(clear-icon)The icon in the clear control

CSS custom properties

PropertyDescription
--nana-date-picker-bgField and panel background
--nana-date-picker-accentFocus colour of the field

NanaDatePickerRoot

PropTypeDefault
valuebind:string''
openbind:booleanfalse
onValueChange(value: string) => void
onOpenChange(open: boolean) => void
minstring
maxstring
localestring
formatDateFormat
firstDayOfWeeknumber
isDateUnavailable(iso: string) => boolean
disabledboolean
readOnlyboolean
namestring
placementPlacement'bottom-start'
childrenSnippet

Also accepts HTMLAttributes<HTMLDivElement>.