UnflowUI
ComponentsHooks

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

ParamTypeDefaultDescription
valueDate | 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
formatstring'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

FieldTypeDescription
inputPropsobjectSpread 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

KeyBehavior
0–9Fills 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 / ArrowRightPrevious / next segment, padding the one you leave (4 → 04)
ArrowUp / ArrowDownSteps the active segment and wraps at its bounds. An empty year starts at the current year
Backspace / DeleteClears the active segment
ClickSelects 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 value from 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), then onBlur runs.

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.