Back to components
Month Pager React component

What is this?

A white pill month pager: previous, the month and year, next. Changing the month slides the label sideways in the direction you moved, and each button dims at its limit. Swap the range and locale, then drop it above a calendar, billing history, or a report.

Full TSX source. No account needed.

month-pager.tsx

"use client"; import * as React from "react";import { ChevronLeft, ChevronRight } from "lucide-react";import { cn } from "@/lib/utils"; /** A calendar month. `month` is 1–12. */export type MonthPagerValue = { year: number; month: number }; export type MonthPagerProps = Omit<  React.ComponentPropsWithoutRef<"div">,  "onChange" | "defaultValue"> & {  value?: MonthPagerValue;  /** Defaults to the current month. */  defaultValue?: MonthPagerValue;  onValueChange?: (value: MonthPagerValue) => void;  min?: MonthPagerValue;  max?: MonthPagerValue;  /** BCP 47 locale for the month name, e.g. "en-US" or "ja-JP". */  locale?: string;  previousLabel?: string;  nextLabel?: string;  /** Accessible name for the month readout. */  ariaLabel?: string;}; const CSS = `@keyframes month-pager-in-next { from { transform: translateX(70%); opacity: 0; filter: blur(3px); } to { transform: translateX(0); opacity: 1; filter: blur(0); } }@keyframes month-pager-in-prev { from { transform: translateX(-70%); opacity: 0; filter: blur(3px); } to { transform: translateX(0); opacity: 1; filter: blur(0); } }@keyframes month-pager-out-next { from { transform: translateX(0); opacity: 1; } to { transform: translateX(-70%); opacity: 0; filter: blur(3px); } }@keyframes month-pager-out-prev { from { transform: translateX(0); opacity: 1; } to { transform: translateX(70%); opacity: 0; filter: blur(3px); } }.month-pager-label { grid-area: 1 / 1; white-space: nowrap; animation-duration: 420ms; animation-timing-function: cubic-bezier(0.22, 1, 0.36, 1); animation-fill-mode: both; }@media (prefers-reduced-motion: reduce) {  .month-pager-label { animation: none !important; }  .month-pager-label[data-leaving] { display: none; }}`; const toIndex = (v: MonthPagerValue) => v.year * 12 + (v.month - 1);const fromIndex = (i: number): MonthPagerValue => ({  year: Math.floor(i / 12),  month: (((i % 12) + 12) % 12) + 1,}); function thisMonth(): MonthPagerValue {  const now = new Date();  return { year: now.getFullYear(), month: now.getMonth() + 1 };} export const MonthPager = React.forwardRef<HTMLDivElement, MonthPagerProps>(  (    {      value,      defaultValue,      onValueChange,      min,      max,      locale = "en-US",      previousLabel = "Previous month",      nextLabel = "Next month",      ariaLabel = "Month",      className,      ...props    },    ref,  ) => {    const minIndex = min ? toIndex(min) : Number.NEGATIVE_INFINITY;    const maxIndex = max ? toIndex(max) : Number.POSITIVE_INFINITY;    const clamp = (i: number) => Math.min(maxIndex, Math.max(minIndex, i));     const [own, setOwn] = React.useState(() => toIndex(defaultValue ?? thisMonth()));    const current = clamp(value ? toIndex(value) : own);     const format = React.useMemo(      () => new Intl.DateTimeFormat(locale, { month: "long", year: "numeric", timeZone: "UTC" }),      [locale],    );    const labelOf = (i: number) => {      const { year, month } = fromIndex(i);      return format.format(new Date(Date.UTC(year, month - 1, 1)));    };     // Keep the outgoing label for one swap so both slide on the same frame.    const [reel, setReel] = React.useState<{      index: number;      prev: number | null;      direction: "next" | "prev";      key: number;    }>({ index: current, prev: null, direction: "next", key: 0 });    if (reel.index !== current) {      setReel({        index: current,        prev: reel.index,        direction: current > reel.index ? "next" : "prev",        key: reel.key + 1,      });    }     const commit = (next: number) => {      const bounded = clamp(next);      if (bounded === current) return;      if (value === undefined) setOwn(bounded);      onValueChange?.(fromIndex(bounded));    };     const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {      const map: Record<string, number | undefined> = {        ArrowLeft: current - 1,        ArrowDown: current - 1,        ArrowRight: current + 1,        ArrowUp: current + 1,        PageDown: current - 12,        PageUp: current + 12,        Home: Number.isFinite(minIndex) ? minIndex : undefined,        End: Number.isFinite(maxIndex) ? maxIndex : undefined,      };      const next = map[event.key];      if (next === undefined) return;      event.preventDefault();      commit(next);    };     const atMin = current <= minIndex;    const atMax = current >= maxIndex;    const buttonClass = cn(      "grid size-10 shrink-0 cursor-pointer place-items-center rounded-full border-0 bg-zinc-100 text-zinc-900",      "transition-[background-color,transform,opacity] duration-300 motion-reduce:transition-none",      "hover:bg-zinc-200 active:scale-90 motion-reduce:active:scale-100",      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-zinc-900/35 focus-visible:ring-offset-2",      "disabled:cursor-not-allowed disabled:opacity-35 disabled:hover:bg-zinc-100 disabled:active:scale-100",    );    const currentLabel = labelOf(current);     return (      <div        ref={ref}        data-tsuna-id="month-pager"        className={cn(          "inline-flex items-center gap-1 rounded-full bg-white p-[6px]",          "shadow-[0_18px_40px_-18px_rgba(15,23,42,0.28),0_4px_12px_-8px_rgba(15,23,42,0.14)]",          className,        )}        {...props}      >        <style>{CSS}</style>        <button          type="button"          className={buttonClass}          onClick={() => commit(current - 1)}          disabled={atMin}          aria-label={previousLabel}          tabIndex={-1}        >          <ChevronLeft className="size-[18px]" strokeWidth={2.4} aria-hidden />        </button>        <div          role="spinbutton"          tabIndex={0}          aria-label={ariaLabel}          aria-valuenow={current}          aria-valuetext={currentLabel}          aria-valuemin={Number.isFinite(minIndex) ? minIndex : undefined}          aria-valuemax={Number.isFinite(maxIndex) ? maxIndex : undefined}          onKeyDown={onKeyDown}          className={cn(            "grid h-10 min-w-[9.75rem] place-items-center overflow-hidden rounded-xl px-3",            "text-[15px] leading-none font-semibold tracking-[-0.015em] text-zinc-950",            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-zinc-900/35",          )}        >          {reel.prev !== null ? (            <span              key={`out-${reel.key}`}              aria-hidden              data-leaving=""              className="month-pager-label"              style={{ animationName: `month-pager-out-${reel.direction}` }}              onAnimationEnd={() => {                const done = reel.key;                setReel((cur) => (cur.key === done ? { ...cur, prev: null } : cur));              }}            >              {labelOf(reel.prev)}            </span>          ) : null}          <span            key={`in-${reel.key}`}            className="month-pager-label"            suppressHydrationWarning            style={              reel.key > 0 ? { animationName: `month-pager-in-${reel.direction}` } : undefined            }          >            {currentLabel}          </span>        </div>        <button          type="button"          className={buttonClass}          onClick={() => commit(current + 1)}          disabled={atMax}          aria-label={nextLabel}          tabIndex={-1}        >          <ChevronRight className="size-[18px]" strokeWidth={2.4} aria-hidden />        </button>      </div>    );  },); MonthPager.displayName = "MonthPager";
Component

Month Pager

A white pill month pager: previous, the month and year, next. Changing the month slides the label sideways in the direction you moved, and each button dims at its limit. Swap the range and locale, then drop it above a calendar, billing history, or a report.

Live Preview

Verified Technical Spec

Animation
CSS / Tailwind
Reduced motion
Verified
Keyboard focus
Verified
Compatibility
Tailwind CSS v3.4 + v4 · React 19 / Next.js 15 App Router + Vite / Remix compatible

Included

  • Copy source into Cursor or Claude for agent install
  • Finished React · TypeScript · Tailwind CSS · Lucide UI

Dependencies

  • React 19.0.0
  • Typescript 5.7.2
  • Tailwindcss 3.4.16
  • Lucide-react 1.23.0

Tech Stack

  • React
  • TypeScript
  • Tailwind CSS
  • Lucide

Version 1.0.0