Month Picker React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Month Picker is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import MonthPicker from @/components/ui/month-picker.

import { useState } from "react";
import { MonthPicker, type DateRange } from "@/components/ui/month-picker";

export function SalesReport() {
  const [period, setPeriod] = useState<DateRange>({ from: new Date(2026, 6, 1), to: new Date(2026, 8, 30) });
  const [month, setMonth] = useState<Date | null>(new Date(2026, 8, 1));
  return (
    <div className="flex flex-col gap-4">
      <MonthPicker
        mode="range"
        label="Period"
        presets
        max={new Date()}
        value={period}
        onValueChange={setPeriod}
        name="period"
        labels={{ apply: "Done" }}
      />
      <MonthPicker label="Billing month" value={month} onValueChange={setMonth} min={new Date(2024, 0, 1)} max={new Date()} />
    </div>
  );
}

Props

• modedefault "single"
  "single" | "range"

  single picks one month (value: its first day at 00:00); range picks a span of months (value: from the first day of the first month to the last day of the last one, ready for a query).

• value
  Date | null (single) | DateRange (range)

  The month or range, controlled. A date in the middle of a month shows as its month and is not rewritten; a value outside min / max or on a disabled month shows as given and flags the field invalid.

• defaultValuedefault "null / { from: null, to: null }"
  Date | null (single) | DateRange (range)

  The starting value while uncontrolled. A form reset returns to it.

• onValueChange
  (value: MonthPickerValue<mode>) => void

  Called with the new month (single) or the complete range (range: on the second click, a quarter or a preset; on phones on Apply). A half-picked range never reaches it. null or { from: null, to: null } when cleared.

• labeldefault ""
  ReactNode

  The field label. Plain text also titles the phone sheet and names the panel.

• descriptiondefault ""
  ReactNode

  Helper text under the field, linked with aria-describedby.

• errordefault ""
  ReactNode

  Replaces the description with the error and marks the field invalid.

• placeholderdefault ""
  string

  The empty trigger text. Empty uses "Pick a month" (single) or "Pick months" (range).

• presetsdefault false
  boolean | MonthPreset[]

  true: This month, Last month, Last 3 / 6 / 12 months, This year and Last year in range mode (This month and Last month in single), clamped to min / max and off when they break maxMonths or touch a disabled month. Or your own list of { label, value: Date | DateRange | () => Date | DateRange, key? }. A column on the left from 640px, a chip rail on phones.

• localedefault ""
  string

  Month names, the trigger text and the quarter letter (Q in English, T in Romanian, French, Spanish, Italian, Portuguese). Empty uses the nearest LocaleProvider, else the page's language.

• sheetTitledefault ""
  string

  The phone sheet title when the label is not plain text. Empty uses labels.dialog ("Choose month").

• displayFormatdefault "{ month: "long", year: "numeric" } (single), { month: "short", year: "numeric" } (range)"
  Intl.DateTimeFormatOptions

  The trigger text through Intl: "septembrie 2026"; ranges through formatRange, the shared year folded ("iul. - sept. 2026", across years "nov. 2025 - feb. 2026").

• formatValue
  (value: MonthPickerValue<mode>, locale: string) => string

  Your own trigger text, for formats Intl does not write, like a card expiry "09/28".

• icondefault "<CalendarDays />"
  ReactNode

  The leading icon of the trigger.

• labelsdefault "DEFAULT_MONTH_PICKER_LABELS"
  Partial<MonthPickerLabels>

  Every string: previousYear, nextYear, previousYears, nextYears, chooseYear, quarter(q), quarters, presets, the preset names (thisMonth, lastMonth, last3Months, last6Months, last12Months, thisYear, lastYear), months(count) for the summary, pickStart, pickEnd, apply, cancel, clear, dialog.

• sizedefault "md"
  "sm" | "md" | "lg"

  The field height: 32 / 40 / 48px (44px on touch for md), matching inputs and selects.

• variantdefault "soft"
  "soft" | "outline" | "underline" | "ghost"

  The field box: a soft fill, a hairline outline, a bottom line, or nothing until hover.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  The field corners, per size like the button.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The selected months, the range band, the quarter chips and Apply.

• colordefault ""
  string

  Any CSS color for the selection; replaces the tone.

• monthFormatdefault "short"
  "short" | "long"

  The month cells: "Sept." or "Septembrie".

• classNames
  Partial<Record<MonthPickerSlot, string>>

  Classes per part: field, label, description, error, box, trigger, icon, value, clear, chevron, content, panel, header, title, nav, grid, month, years, year, quarters, quarter, presets, preset, footer, summary.

• min
  Date

  The first month that can be picked; earlier months are disabled and the year arrows stop there.

• max
  Date

  The last month that can be picked. A max before min is ignored.

• quartersdefault false
  boolean

  The Q1 to Q4 chips under the grid. Left unset they show in range mode (three months at once) and hide in single mode, where true adds them and a quarter picks its first month.

• maxMonthsdefault 0
  number

  The longest range in months; while you pick the end, months farther away are disabled. 0 = no limit.

• clearabledefault false
  boolean

  A clear button inside the field while it has a value.

• closeOnSelectdefault true
  boolean

  Single mode closes after a pick. Range mode always stays open until Escape, Enter or a click outside.

• now
  Date | number

  What this month means: the current-month dot and the presets. Left out, the live clock (useNow); pin it for screenshots.

• namedefault ""
  string

  Hidden inputs for forms: single submits YYYY-MM, range submits name.from and name.to as ISO dates.

• disableddefault false
  boolean or (month: Date) => boolean

  true dims the whole field and never opens it. A test disables single months instead (closed accounting periods): it gets each month's first day.

• readOnlydefault false
  boolean

  The value stays visible but the panel never opens.

• requireddefault false
  boolean

  The mark after the label and aria-required on the trigger.

• invaliddefault false
  boolean

  The invalid look and aria-invalid without a message.

• open
  boolean

  The panel, controlled. Pair it with onOpenChange.

• defaultOpendefault false
  boolean

  Opens the panel on mount while uncontrolled.

• onOpenChange
  (open: boolean) => void

  Called when the panel or sheet opens or closes.

• inlinedefault false
  boolean

  The panel sits on the page without a trigger (a raised surface with the grid, quarters, presets and the range summary).

• responsivedefault true
  boolean

  A bottom sheet below 768px instead of the popover.

• sidedefault "bottom"
  "top" | "right" | "bottom" | "left"

  Where the popover opens; it flips when there is no room.

• aligndefault "start"
  "start" | "center" | "end"

  How the popover lines up with the field.

• container
  HTMLElement | null

  The portal target of the popover and the sheet (default document.body).

• id
  string

  The trigger's id; the label points at it.

• fieldProps
  Partial<FieldProps>

  Anything else for the Field wrapper: optional, labelAction, orientation, hideLabel.

• ref
  Ref<HTMLButtonElement> (a useRef object or an (el) => void callback)

  The trigger button (a regular prop in React 19).

Parts

FAQ

More React input components