# Date & time
Four date/time controls built on a shared, framework-free date engine
(`date-core`, `date-format`, `date-selection`, `date-restrict`). They are the
rich-by-default editors for `date`, `datetime` and `time` grid columns, and work
standalone.
## Installation
Add any component with the CLI (drops a ready-to-edit starter into your app) - or
add the whole family at once:
Prefer to see them first? `npx @svgrid/ui try date-time` opens the whole family in a sandbox - no project needed.
The controls all ship free in the `@svgrid/grid` package - they are the **same
components SvGrid mounts to edit `date`, `datetime` and `time` cells**, so you can
also just install the grid and import them directly:
## The family at a glance
Each component has its own tutorial with a live Preview / Code example, the full
props table and accessibility notes:
- [SvCalendar](https://svgrid.com/docs/help/ui-components/sv-calendar/) - a month/year/decade calendar with every selection mode (single, range, week, multi, event cells + recurrence).
- [SvTimePicker](https://svgrid.com/docs/help/ui-components/sv-time-picker/) - an analog clock-dial time picker (12/24-hour, minute snapping).
- [SvDateTimePicker](https://svgrid.com/docs/help/ui-components/sv-date-time-picker/) - a masked text field with DATE / TIME dropdown tabs.
- [SvDateRangeInput](https://svgrid.com/docs/help/ui-components/sv-date-range-input/) - a compact start-to-end range field with preset shortcuts.
## SvCalendar
A month / year / decade calendar with every selection mode.
The examples on this page import from `@svgrid/grid`:
```svelte
```
```svelte
(value = dates)}
/>
```
Key props: `value` (Date | Date[] | string), `selectionMode`
(`one` `zeroOrOne` `many` `zeroOrMany` `oneOrMany` `oneExtended` `week` `range`),
`min` / `max`, `restrictedDates` (list or predicate), `importantDates`,
`firstDayOfWeek` (0-6), `weeks`, `weekNumbers`, `months` (multi-panel),
`displayMode` (`month` `year` `decade`), `hideDayNames`, `hideOtherMonthDays`,
`dayNameFormat` / `monthNameFormat`, `footer`, `locale`, `disabled`, `readonly`.
Emits `onChange(dates)` and `onNavigate(viewDate, displayMode)`.
Keyboard: arrows move by day, PageUp/Down by month (Shift = year), Home/End to
week ends, Enter/Space selects, the title button drills up the view.
### Rich cells + recurrence (event calendars)
Two props turn the picker into a full event scheduler:
- **`day`** - a snippet rendered inside each day cell, receiving `(date, state)`.
Providing it switches the month grid to a taller, top-aligned layout with room
for event chips / badges.
- **`recurrence`** - a repeat rule (or array). Matching days get `state.recurring`
and a "repeats" indicator. Rules: `{ freq: 'daily'|'weekly'|'monthly'|'yearly',
interval?, weekdays?, day?, month?, from?, until? }`.
```svelte
(selected = d[0])}>
{#snippet day(date, state)}
{#each eventsOn(date) as e}
{e.time} {e.title}
{/each}
{/snippet}
```
The pure helpers `matchesRecurrence(date, rules)` and `expandRecurrence(rules,
start, end)` are exported for generating recurring events / agendas without a
calendar. See the **Event calendar** demo.
## SvTimePicker
An analog clock-dial picker (12- or 24-hour).
```svelte
(time = d)} />
```
Key props: `value` (Date | "HH:MM"), `format` (`12-hour` | `24-hour`),
`minuteInterval`, `autoSwitchToMinutes`, `footer` (Now), `selection`
(`hour` | `minute`), `disabled`, `readonly`. Drag the hand or click a number;
arrow keys nudge the active field. Emits `onChange(date)`.
## SvDateTimePicker
A formatted text input plus a portalled dropdown with DATE / TIME tabs
(composes `SvCalendar` + `SvTimePicker`).
```svelte
(value = d)}
/>
```
Key props: `value`, `formatString` (token engine: `d dd M MM MMM MMMM yy yyyy H HH
h hh mm ss fff tt`), `dropDownDisplayMode` (`both` | `calendar` | `time`),
`min` / `max`, `nullable`, `hourFormat`, `minuteInterval`, `spinButtons`,
`stepMinutes`, `firstDayOfWeek`, `weekNumbers`, `locale`, `disabled`, `readonly`.
Typed text is parsed on blur/Enter and reverts if it doesn't fit the mask; the
value is clamped to `min` / `max`. Emits `onChange`, plus `onCommit` / `onCancel`
for grid editing.
See the [component guides above](#the-family-at-a-glance) for each control's full
tutorial, live example and props.
## More examples
### Date-time picker - headless
Styled SvDateTimePicker (portalled dropdown) and a custom masked field, sharing one value.
> Live demo: Date-time picker - headless - https://svgrid.com/demos/278-headless-datetimepicker/
## The three date controls together
A calendar for picking a day, a time picker for a clock value, and the
combined control when you need both. They share the same value contract, so
swapping one for another is a component change and nothing else.
```svelte
(day = dates[0] ?? null)} />
(clock = v)} />
(both = v)} />
```
---
SvGrid is the Svelte 5 data grid (`npm install @svgrid/grid`, MIT). This page: https://svgrid.com/docs/help/ui-components/date-time/ . All docs: https://svgrid.com/llms.txt