Month Picker

Months a year at a time, for billing and reporting periods.

Source
$npx @dinachi/cli@latest add month-picker
2026

mode
noFuture
disabled

Usage

import { useState } from "react"
import { MonthPicker } from "@/components/ui/month-picker"

export function BillingMonth() {
  const [month, setMonth] = useState<Date | null>(null)
  return <MonthPicker aria-label="Billing month" value={month} onValueChange={setMonth} max={new Date()} />
}

Examples

2026
One billing month, nothing after this one.
import { useState } from 'react';
import { MonthPicker } from '@/components/ui/month-picker';

export function Example() {
  const [month, setMonth] = useState<Date | null>(null);
  return <MonthPicker aria-label="Billing month" className="w-72" value={month} onValueChange={setMonth} max={new Date()} />;
}

Notes

Server rendering

Pass today when the page renders on a server, so the server and the browser agree on which month it is.

Picking a span

The first pick starts the span and the second ends it. A third pick, or one before the start, starts again. The readout names both years only when the span crosses one.

API

mode"single" | "range" = "single"
One month, or a from and to.
value
agent
Date | null | DateRange
Controlled value. A month is the first of the month. Its type follows mode.
defaultValueDate | null | DateRange
Starting value when uncontrolled.
onValueChange
agent
(value, details) => void
Runs on every pick, for people and agents. details.cancel() refuses the change.
min
agent
Date
The earliest month that can be picked.
max
agent
Date
The latest month that can be picked. Set it to today for reports.
isMonthDisabled
agent
(month: Date) => boolean
Blocks single months. Called with the first of the month.
disabled
agent
boolean = false
Blocks people and agents.
localeLocale
A date-fns locale for month names.
dir"ltr" | "rtl"
Reading direction. Arrow keys follow it.
todayDate
Overrides the current day. Its month carries a ring.
namestring
Submits YYYY-MM, or YYYY-MM/YYYY-MM for a range.
requiredboolean = false
Fails form validation with no month.

Agent

Inside an AgentProvider, it appears in agent.snapshot() as date.

Reads

label

The aria-label, "Month" or "Months" by default.

value

YYYY-MM, or [from, to] in range mode, [from] while the end is still to pick. Absent when empty.

multiple

True in range mode.

invalid

True when a value set from outside names a month that can't be picked, with the reason in errors.

Actions

setValue("2026-03")

Picks a month. "mar 2026" and "march" work too.

setValue(["2026-06", "2026-11"])

Picks a span in range mode. "jun to nov 2026" works too.

clear()

Empties the value.

An agent's change runs through onValueChange like anyone's. isAgentChange(details) is true for it; details.cancel() refuses it. A month outside min and max, a blocked month, or a span that ends before it starts is refused with the reason.

await agent.act({
  steps: [{ ref: "Billing month", action: "setValue", args: ["2026-10"] }],
})

Accessibility

  • Each month is a toggle button named with its year, such as March 2026; picked months have aria-pressed.
  • This month has aria-current="date". Blocked months have aria-disabled and stay focusable. A value set from outside on a blocked month shows in the destructive color, its name ends "can't be picked", and the root carries data-invalid.
  • Only one month is in the tab order. The year above the grid follows focus and is announced when it changes. It is not a heading, so it never breaks the page's outline.
  • The range readout is a live region.