Month Picker

A date picker that opens a calendar popover for selecting a month and year.

Overview

MonthPicker renders a trigger element that opens a Dropdown containing a month-year grid. It is a controlled component; pass value and onValueChange to manage the selected month. Navigation arrows move by year rather than by month. The calendar is localized to English by default. Use MonthPicker when the use case requires month-level granularity rather than a specific day — for example, billing periods, report ranges, or subscription cycles. For day-level selection, use DayPicker instead.

Accessibility

The month grid supports keyboard navigation between months.
Escape closes the dropdown and returns focus to the trigger.
Year navigation arrows allow moving forward and backward through years.
Months outside the minDate–maxDate range are visually dimmed and non-selectable.

Import

import { MonthPicker } from "@cocso-ui/react";

Default

Control the selected month with the value and onValueChange props. The returned Date represents the first day of the selected month.

"use client";

import { MonthPicker } from "@cocso-ui/react";
import { useState } from "react";

export default function MonthPickerDefault() {
  const [value, setValue] = useState<Date | null>(null);

  return (
    <div className="p-4">
      <MonthPicker onValueChange={setValue} value={value ?? undefined} />
      {value && <p className="mt-2 text-sm text-neutral-500">Selected: {value.toLocaleDateString("en-US", { year: "numeric", month: "long" })}</p>}
    </div>
  );
}

API Reference

Prop	Type	Default	Description
`value`	`Date`	-	The currently selected month, represented as a `Date` (first day of the month). Pass `undefined` for no selection.
`onValueChange`	`(value: Date \| null) => void`	-	Callback invoked when the user selects a month. Receives a `Date` representing the first day of the selected month, or `null`.
`disabled`	`boolean`	-	Disables the trigger button and prevents the month picker from opening.
`minDate`	`Date`	-	The earliest selectable month. Months before this date are visually dimmed and cannot be selected.
`maxDate`	`Date`	-	The latest selectable month. Months after this date are visually dimmed and cannot be selected.
`trigger`	`ReactElement`	-	Custom trigger element replacing the default button. Use to integrate with form input fields or custom UI.