Skip to main content

useYearPicker

The headless hook behind <YearPicker>. Exposes a 12-year decade block and navigation.

:::info /headless entry Exported from @kalyx/react/headless (adapter-agnostic). See Date adapters & the /headless entry. :::

import { useYearPicker } from '@kalyx/react/headless';

Signature​

function useYearPicker(options?: UseYearPickerOptions): UseYearPickerReturn;

Options​

FieldTypeDefaultDescription
valueISODateString | null—Controlled year (stored as Jan 1 ISO).
defaultValueISODateString—Uncontrolled initial year.
onChange(value: ISODateString | null) => void—Fires when the year changes.
disabledDisabledRule[][]A year is disabled only when fully excluded.
adapterDateAdapter—Date adapter (required on /headless).
displayTimezonestring—IANA zone for civil-day comparison.

Return​

FieldTypeDescription
valueISODateString | nullCurrent selected year.
isOpenbooleanPopover state.
open / close / toggle() => voidPopover controls.
selectYear(iso: ISODateString) => voidCommit a year (pass a cell's isoString).
decadeStartnumberFirst year of the displayed 12-year block.
previousDecade / nextDecade() => voidMove the grid one decade block.
yearsYearCell[]The 12 year cells for the current block.
pickerIdstringStable ID for ARIA wiring.
adapterDateAdapterThe resolved adapter.

YearCell​

type YearCell = {
  isoString: ISODateString; // Jan 1, UTC midnight
  year: number;
  isSelected: boolean;
  isCurrent: boolean;       // current year (today)
  isDisabled: boolean;
};

Example​

import { useYearPicker } from '@kalyx/react/headless';
import { DateFnsAdapter } from '@kalyx/adapter-date-fns';

export function MiniYearGrid() {
  const { years, decadeStart, previousDecade, nextDecade, selectYear } =
    useYearPicker({ adapter: DateFnsAdapter });

  return (
    <div>
      <header>
        <button onClick={previousDecade} aria-label="Previous decade">◀</button>
        <span>{decadeStart}–{decadeStart + 11}</span>
        <button onClick={nextDecade} aria-label="Next decade">▶</button>
      </header>
      <div className="grid grid-cols-3">
        {years.map((y) => (
          <button
            key={y.isoString}
            aria-selected={y.isSelected}
            disabled={y.isDisabled}
            onClick={() => selectYear(y.isoString)}>
            {y.year}
          </button>
        ))}
      </div>
    </div>
  );
}