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.
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.
Preview
Section titled “Preview”<div style="min-height: 24rem">
<nana-date-picker
label="Move-in date"
helper-text="The tenancy starts on this day."
clearable
></nana-date-picker>
</div> | M | T | W | T | F | S | S |
|---|---|---|---|---|---|---|
<script lang="ts">
import { NanaIcon } from '$lib/components/ui/icon';
import { calendarIcon, chevronLeftIcon, chevronRightIcon } from '@nana-tec/ui-core/heroicons';
import { DatePicker } from '$lib/components/ui/date-picker';
let value = $state('');
</script>
<DatePicker.Root bind:value locale="en-GB" class="w-72">
<DatePicker.Label>Move-in date</DatePicker.Label>
<DatePicker.Control>
<DatePicker.Input />
<DatePicker.Trigger><NanaIcon icon={calendarIcon} class="size-4" /></DatePicker.Trigger>
</DatePicker.Control>
<DatePicker.Positioner>
<DatePicker.Content>
<DatePicker.View view="day">
<DatePicker.Context>
{#snippet children(api)}
<DatePicker.ViewControl>
<DatePicker.PrevTrigger
><NanaIcon icon={chevronLeftIcon} class="size-4" /></DatePicker.PrevTrigger
>
<DatePicker.ViewTrigger><DatePicker.RangeText /></DatePicker.ViewTrigger>
<DatePicker.NextTrigger
><NanaIcon icon={chevronRightIcon} class="size-4" /></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.View view="month">
<DatePicker.Context>
{#snippet children(api)}
<DatePicker.ViewTrigger><DatePicker.RangeText /></DatePicker.ViewTrigger>
<DatePicker.Table>
<DatePicker.TableBody>
{#each api.getMonthsGrid({ columns: 4, format: 'short' }) as row, i (i)}
<DatePicker.TableRow>
{#each row as month, j (j)}
<DatePicker.TableCell value={month.value}>
<DatePicker.TableCellTrigger>{month.label}</DatePicker.TableCellTrigger>
</DatePicker.TableCell>
{/each}
</DatePicker.TableRow>
{/each}
</DatePicker.TableBody>
</DatePicker.Table>
{/snippet}
</DatePicker.Context>
</DatePicker.View>
<DatePicker.View view="year">
<DatePicker.Context>
{#snippet children(api)}
<DatePicker.ViewControl>
<DatePicker.PrevTrigger
><NanaIcon icon={chevronLeftIcon} class="size-4" /></DatePicker.PrevTrigger
>
<DatePicker.RangeText />
<DatePicker.NextTrigger
><NanaIcon icon={chevronRightIcon} class="size-4" /></DatePicker.NextTrigger
>
</DatePicker.ViewControl>
<DatePicker.Table>
<DatePicker.TableBody>
{#each api.getYearsGrid({ columns: 4 }) as row, i (i)}
<DatePicker.TableRow>
{#each row as year, j (j)}
<DatePicker.TableCell value={year.value}>
<DatePicker.TableCellTrigger>{year.label}</DatePicker.TableCellTrigger>
</DatePicker.TableCell>
{/each}
</DatePicker.TableRow>
{/each}
</DatePicker.TableBody>
</DatePicker.Table>
{/snippet}
</DatePicker.Context>
</DatePicker.View>
</DatePicker.Content>
</DatePicker.Positioner>
</DatePicker.Root> Months and years far away
Section titled “Months and years far away”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.
<div style="min-height: 24rem">
<nana-date-picker
label="Tenant's date of birth"
max="2008-12-31"
value="1990-07-15"
></nana-date-picker>
</div> Bounds and refused days
Section titled “Bounds and refused days”min and max put days out of reach entirely. isDateDisabled refuses days by
rule — here weekends — while still letting the keyboard move across them.
<div style="min-height: 24rem">
<nana-date-picker
id="viewing"
label="Viewing day"
min="2026-03-02"
max="2026-04-30"
value="2026-03-11"
></nana-date-picker>
</div> document.getElementById("viewing").isDateDisabled = (iso) => [0, 6].includes(new Date(`${iso}T00:00`).getDay());Installation
Section titled “Installation”npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add date-picker --framework web-componentsnpx @nana-tec/ui add date-picker --framework svelteLands 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
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
clearable | clearable | boolean | false | Offer a control that clears the date |
disabled | disabled | boolean | false | Blocks interaction and leaves the value out of form submission. |
errorMessage | error-message | string | '' | Error under the field while it is invalid, in the error part with role="alert". |
errorText | error-text | string | — | Deprecated: use error-message with invalid. Setting it also sets invalid. |
firstDayOfWeek | first-day-of-week | number | 1 | Which weekday starts the week; 0 is Sunday |
helperText | helper-text | string | '' | Help below the field |
invalid | invalid | boolean | false | Marks 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 |
label | label | string | '' | Label above the field |
locale | locale | — | — | BCP 47 tag for the date on the field and the calendar's names |
max | max | string | '' | Latest date that can be picked, yyyy-mm-dd |
min | min | string | '' | Earliest date that can be picked, yyyy-mm-dd |
name | name | string | '' | Name the value is submitted under in a form. |
open | open | boolean | false | Whether the calendar is open |
placement | placement | PopupPlacement | 'bottom-start' | Where the calendar opens |
required | required | boolean | false | The form will not submit while this has no value. |
size | size | DatePickerSize | 'md' | Size preset. |
value | value | string | '' | The picked date, yyyy-mm-dd |
Methods
| Method | Description |
|---|---|
clear(): void | Clear the date |
Events
| Event | Description |
|---|---|
nana-change | A date was picked or cleared (detail.value) |
nana-focus | The field gained focus |
nana-blur | The field lost focus |
Slots
| Slot | Description |
|---|---|
placeholder | Shown on the field when no date is picked |
CSS parts
| Part | Description |
|---|---|
::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
| Property | Description |
|---|---|
--nana-date-picker-bg | Field and panel background |
--nana-date-picker-accent | Focus colour of the field |
NanaDatePickerRoot
| Prop | Type | Default |
|---|---|---|
valuebind: | string | '' |
openbind: | boolean | false |
onValueChange | (value: string) => void | |
onOpenChange | (open: boolean) => void | |
min | string | |
max | string | |
locale | string | |
format | DateFormat | |
firstDayOfWeek | number | |
isDateUnavailable | (iso: string) => boolean | |
disabled | boolean | |
readOnly | boolean | |
name | string | |
placement | Placement | 'bottom-start' |
children | Snippet |
Also accepts HTMLAttributes<HTMLDivElement>.