Month PickerNew

A month or a year picked in a field, for monthly and yearly reports, billing periods and card expiry.

$ pnpm dlx shadcn@latest add @dashral/month-picker

Report month

Installation

$ pnpm dlx shadcn@latest add @dashral/month-picker

Adds the component, the components it builds on, its npm packages and the theme tokens it uses. Or by its full URL: https://dashral.com/r/month-picker.json

When to use

A month or a year rather than a day: a monthly or yearly report, a billing period, a card's expiry, a fiscal year (view="year").

When not to use

A day: Date Picker.
A start and an end: Date Range Picker.
Fixed periods such as 7D, 30D or 12M: Segmented Control.

Usage

The month in state, as its 1st; min and max limit what can be picked.

example.tsx

1"use client"
2
3import { useState } from "react"
4import { MonthPicker } from "@/components/dashral/month-picker"
5
6export default function ReportMonth() {
7  const [month, setMonth] = useState<Date | undefined>()
8
9  return <MonthPicker label="Report month" value={month} onValueChange={setMonth} max={new Date()} />
10}

Using the npm package? Import from @dashral/ui/components/month-picker instead, here and in the examples; the rest is the same.

Examples

A year

view="year" picks from a page of twelve years.

Fiscal year

Billing statement

min and max keep it to the last twelve months; the download names the month.

Statement

Statements are kept for twelve months.

API reference

MonthPicker

Prop	Type	Default
`view`	`"month" \| "year"` What it picks: a month of a year, or a year.	`"month"`
`value / defaultValue`	`Date` The 1st of the month picked (January 1st for a year), controlled or initial.	—
`onValueChange`	`(value: Date \| undefined) => void` Called with the new value.	—
`placeholder`	`string` Shown before anything is picked.	`"Pick a month" / "Pick a year"`
`min / max`	`Date` The earliest and latest month (or year) that can be picked; the rest are greyed out.	—
`locale / formatOptions`	`string / Intl.DateTimeFormatOptions` The month names and how the button writes the value.	`LocaleProvider's / the month and year`
`disabled`	`boolean` The whole picker can't be used.	`false`
`label`	`ReactNode` Shown above, linked to the control.	—
`description`	`ReactNode` A hint under the control.	—
`error`	`boolean \| ReactNode` true shows the error style; a message also shows under the control.	—
`labelAction`	`ReactNode` At the end of the label's row, e.g. a “Forgot password?” link or the current value.	—
`withAsterisk`	`boolean` Marks the label with an asterisk, e.g. alongside required.	`false`
`classNames`	`{ root, label, description, error, trigger, content }` Classes for each part.	—

Keyboard

Keys	Action
`Enter`or`Space`	Open the panel
`Arrow keys`	Move through the months or years (left and right swap in right-to-left)
`Home`or`End`	The first or last month (or year)
`Enter`	Pick and close
`Escape`	Close

Accessibility

The picked month (or this month when nothing is picked) takes the focus when the panel opens, and the focus goes back to the button when it closes.
Each month is read in full ("March 2026"); the picked one is pressed and this month is marked as the current date.

Motion

Opens with a fade, a scale from 95%, a 2px blur clearing and a 4px slide from its trigger's side, on the spring (--duration-standard); closes faster (--duration-fast, --ease-exit). No blur with reduced motion.