useDateSegmentNavigation
Turns a single text input into a segmented day/month/year date field with arrow-key stepping and smart auto-advance.
Overview
useDateSegmentNavigation makes one <input type="text"> behave like a native date input split into day, month and year segments. Clicking or arrowing selects a whole segment, Up/Down step it, and typing fills it and moves on to the next one. Unlike the native input, the value stays fully under your control: the year is capped at four digits, the browser never shifts digits between segments, and a Date is only emitted once all three segments form a real calendar day.
It is built for DatePicker's text field. Use it directly when you need a typed date field without the calendar dropdown, or a custom date input that should behave the same way.
Import
import { useDateSegmentNavigation } from '@unflowio/ui/hooks/useDateSegmentNavigation';Parameters
| Param | Type | Default | Description |
|---|---|---|---|
value | Date | null | — | Required. The committed date |
onChange | (date: Date | null, source?) => void | — | Required. Called on every edit with the date, or null while the field is incomplete or invalid. source is the keyboard or change event that caused it, if any |
onBlur | (e: FocusEvent<HTMLInputElement>) => void | — | Called after the field snaps back to value on blur |
format | string | 'dd/MM/yyyy' | Segment order and separator, using the dd, MM and yyyy tokens, e.g. 'MM/dd/yyyy', 'dd.MM.yyyy' or 'yyyy-MM-dd'. A format without exactly those three tokens falls back to day, month, year |
Return value
| Field | Type | Description |
|---|---|---|
inputProps | object | Spread on the <input type="text">: ref, value, inputMode="numeric", autoComplete="off" and the onKeyDown, onMouseUp, onFocus, onBlur and onChange handlers |
Don't pass your own value, onChange or ref to the input; the hook owns them. Add id, name, aria-* and styling as usual.
Usage
import { useState } from 'react';
import { useDateSegmentNavigation } from '@unflowio/ui/hooks/useDateSegmentNavigation';
export function BirthDateField() {
const [date, setDate] = useState<Date | null>(null);
const { inputProps } = useDateSegmentNavigation({ value: date, onChange: setDate, format: 'dd/MM/yyyy' });
return (
<label className="flex flex-col gap-1">
Date of birth
<input type="text" aria-describedby="birth-date-format" {...inputProps} />
<span id="birth-date-format">Day, month, year</span>
</label>
);
}While a segment is empty it shows its placeholder (dd, mm, yyyy), so the input always displays the full pattern.
Keyboard behavior
| Key | Behavior |
|---|---|
0–9 | Fills the active segment. A full segment, or a day/month digit that can't take a second digit (e.g. 4 for a day), pads and moves to the next segment |
ArrowLeft / ArrowRight | Previous / next segment, padding the one you leave (4 → 04) |
ArrowUp / ArrowDown | Steps the active segment and wraps at its bounds. An empty year starts at the current year |
Backspace / Delete | Clears the active segment |
| Click | Selects the segment under the caret |
Days are bounded by the typed month and year, so 31/02 is never emitted. Paste, autofill and IME input go through onChange: the digits fill the segments left to right.
Behaviour on focus and blur
- On focus, the first segment that isn't filled is selected, or the first segment if all are.
- While the input is focused, a new
valuefrom outside doesn't overwrite what's being typed. - On blur, the display snaps back to
value, dropping an incomplete edit or one you rejected (e.g. an end date before the start date), thenonBlurruns.
Accessibility
- The field is a plain text input, so give it a visible label and describe the expected order (e.g. "Day, month, year"), since the placeholder alone is not announced reliably.
inputMode="numeric"brings up the number keyboard on touch devices.
useCalendarNavigation
Keyboard navigation for a calendar grid, driven by the focused date so it crosses months, years and dual calendars.
useNativeFieldSync
Re-renders a component whenever a native form element's value changes, including form library writes and form resets, without copying the value into state.