Skip to main content

useMonthPicker

The headless hook behind <MonthPicker>. Exposes the 12-month grid and navigation; you render the DOM and wire focus / keyboard.

:::info /headless entry The Month / Year / Week / DateTime hooks are exported from the @kalyx/react/headless entry, which is adapter-agnostic (no bundled date-fns). See Date adapters & the /headless entry. :::

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

Signature​

function useMonthPicker(options?: UseMonthPickerOptions): UseMonthPickerReturn;

Options​

FieldTypeDefaultDescription
valueISODateString | null—Controlled month (stored as month-start ISO).
defaultValueISODateString—Uncontrolled initial month.
onChange(value: ISODateString | null) => void—Fires when the month changes.
disabledDisabledRule[][]A month is disabled only when fully excluded.
adapterDateAdapter—Date adapter (required on /headless).
displayTimezonestring—IANA zone for civil-day comparison. See Timezone.
localestring'en-US'BCP 47 locale for month names.

Return​

FieldTypeDescription
valueISODateString | nullCurrent selected month.
isOpenbooleanPopover state.
open / close / toggle() => voidPopover controls.
selectMonth(iso: ISODateString) => voidCommit a month (pass a cell's isoString).
viewYearnumberYear currently shown in the grid.
previousYear / nextYear() => voidMove the grid one year.
monthsMonthCell[]The 12 month cells for viewYear.
pickerIdstringStable useId-based ID for ARIA wiring.
adapterDateAdapterThe resolved adapter.

MonthCell​

type MonthCell = {
  isoString: ISODateString; // month-start ISO (UTC)
  monthIndex: number;       // 0 = January
  label: string;            // localized month name
  isSelected: boolean;
  isCurrent: boolean;       // current month (today)
  isDisabled: boolean;
};

Example​

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

export function MiniMonthGrid() {
  const { months, viewYear, previousYear, nextYear, selectMonth } =
    useMonthPicker({ adapter: DateFnsAdapter, onChange: (v) => console.log(v) });

  return (
    <div>
      <header>
        <button onClick={previousYear} aria-label="Previous year">◀</button>
        <span>{viewYear}</span>
        <button onClick={nextYear} aria-label="Next year">▶</button>
      </header>
      <div className="grid grid-cols-3">
        {months.map((m) => (
          <button
            key={m.isoString}
            aria-selected={m.isSelected}
            disabled={m.isDisabled}
            onClick={() => selectMonth(m.isoString)}>
            {m.label}
          </button>
        ))}
      </div>
    </div>
  );
}