@leaderty/react-month-selector

React month picker with a clearer layout than <input type="month">, optional min/max bounds, inline or expanded layout, and form-friendly hidden input values in YYYY-MM.

Setup

npm install @leaderty/react-month-selector

Peer dependencies (install in your app):

• react ^18 or ^19
• react-dom ^18 or ^19

Component

MonthSelector

Accessible month control: previous/next month, optional year navigation and month grid (variant="expanded"), keyboard support (ArrowLeft / ArrowRight when the group is focused), and a hidden <input> for native forms when name is set.

Behavior:

• Values passed to onChange and the hidden input are always YYYY-MM (or an empty string when nothing is selected in uncontrolled mode).
• min / max (also YYYY-MM) clamp navigation and grid choices.
• Styling: pass className / style, or theme with CSS variables on the root (for example --rms-accent, --rms-bg, --rms-border, --rms-radius, --rms-muted, --rms-month-grid-gap).
• locale is forwarded to Intl for month labels.

Parameters (highlights):

• value / defaultValue — selected month as YYYY-MM (controlled vs uncontrolled).
• onChange — (value: string) => void with YYYY-MM or "".
• min / max — optional inclusive bounds.
• variant — "inline" (compact row) or "expanded" (year steppers + 12-month grid).
• name — if set, renders a hidden input with that name for form posts.
• required / disabled — forwarded to the hidden input and buttons as appropriate.
• ref — forwarded to the hidden input (useful with form libraries).

Returns: A React element (no additional return value).

Examples:

import { useState } from "react"
import { MonthSelector } from "@leaderty/react-month-selector"

function BillingPeriod() {
  const [month, setMonth] = useState("2026-01")
  return (
    <MonthSelector
      value={month}
      onChange={setMonth}
      min="2024-01"
      max="2027-12"
      variant="expanded"
      locale="es-AR"
      name="billingMonth"
    />
  )
}

Utilities

The package also exports small helpers (parseYearMonth, formatYearMonth, clampYearMonth, isYearMonthInRange, etc.) for working with YYYY-MM strings in plain TypeScript. See src/month-utils.ts for the full list.