modenoFuturedisabledimport { useState } from "react"
import { type DateRange } from "@/components/ui/calendar"
import { MonthPicker } from "@/components/ui/month-picker"
export function BillingPeriod() {
const [period, setPeriod] = useState<DateRange>({ from: null, to: null })
return (
<MonthPicker
aria-label="Billing period"
mode="range"
max={new Date()}
value={period}
onValueChange={setPeriod}
/>
)
}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
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()} />;
}import { useState } from 'react';
import { type DateRange } from '@/components/ui/calendar';
import { MonthPicker } from '@/components/ui/month-picker';
export function Example() {
const [span, setSpan] = useState<DateRange>({ from: null, to: null });
return <MonthPicker aria-label="Reporting period" mode="range" className="w-72" value={span} onValueChange={setSpan} 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.details.cancel() refuses the change.YYYY-MM, or YYYY-MM/YYYY-MM for a range.Agent
Inside an AgentProvider, it appears in agent.snapshot() as date.
Reads
labelThe aria-label, "Month" or "Months" by default.
valueYYYY-MM, or [from, to] in range mode, [from] while the end is still to pick. Absent when empty.
multipleTrue in range mode.
invalidTrue 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.