Spring Calendar
A month calendar where the selection flows from day to day and the month slides in from the side it came from.
Preview
"use client";
import { useState } from "react";
import { useAutoplay } from "../demo-context";
import { SpringCalendar } from "./SpringCalendar";
const path = [
[2026, 10, 4],
[2026, 10, 12],
[2026, 10, 27],
[2026, 11, 3],
[2026, 11, 18],
[2026, 10, 18],
];
export default function Demo() {
const [value, setValue] = useState<Date | null>(new Date(2026, 10, 18));
const [turn, setTurn] = useState(0);
useAutoplay(() => {
const [y, m, d] = path[turn % path.length];
setValue(new Date(y, m, d));
setTurn((t) => t + 1);
}, 1300);
return <SpringCalendar value={value} onChange={setValue} locale="en-US" />;
}Installation
npx @usefluid/cli add spring-calendarpnpm dlx @usefluid/cli add spring-calendaryarn dlx @usefluid/cli add spring-calendarbunx @usefluid/cli add spring-calendarInstall the engine.
Terminal npm i @usefluid/motionCopy these files into your project.
components/fluid/spring-calendar/SpringCalendar.tsx "use client"; import { useSpring } from "@usefluid/motion/react"; import { type KeyboardEvent, useEffect, useMemo, useRef, useState } from "react"; import { monthGrid, moveDate, sameDay } from "./calendar"; import styles from "./SpringCalendar.module.css"; type Props = { value: Date | null; onChange(date: Date): void; locale?: string; weekStart?: 0 | 1; previousLabel?: string; nextLabel?: string; }; const iso = (d: Date) => `${d.getFullYear()}-${d.getMonth() + 1}-${d.getDate()}`; export function SpringCalendar({ value, onChange, locale, weekStart = 1, previousLabel = "Previous month", nextLabel = "Next month" }: Props) { const start = value ?? new Date(); const [view, setView] = useState({ year: start.getFullYear(), month: start.getMonth() }); const [focus, setFocus] = useState(start); const grid = useRef<HTMLDivElement>(null); const days = useRef<HTMLDivElement>(null); const pill = useRef<HTMLSpanElement>(null); const typed = useRef(false); const placed = useRef(false); const today = useMemo(() => new Date(), []); const cells = monthGrid(view.year, view.month, weekStart); const title = new Intl.DateTimeFormat(locale, { month: "long", year: "numeric" }).format(new Date(view.year, view.month, 1)); const weekday = new Intl.DateTimeFormat(locale, { weekday: "narrow" }); const long = new Intl.DateTimeFormat(locale, { dateStyle: "full" }); const index = view.year * 12 + view.month; const picked = cells.findIndex((c) => sameDay(c.date, value)); const shown = picked >= 0; const valueKey = value ? iso(value) : ""; useEffect(() => { if (!value) return; setView((v) => (v.year === value.getFullYear() && v.month === value.getMonth() ? v : { year: value.getFullYear(), month: value.getMonth() })); setFocus(value); }, [valueKey]); useSpring( { s: index }, ({ s }) => { if (!days.current) return; const offset = Math.max(-1, Math.min(1, index - s)); days.current.style.transform = `translateX(${offset * 36}px)`; days.current.style.opacity = `${1 - Math.abs(offset) * 0.7}`; }, { w: 14, z: 0.8 }, ); useSpring( { x: shown ? picked % 7 : 0, y: shown ? Math.floor(picked / 7) : 0 }, ({ x, y }) => { if (pill.current) pill.current.style.transform = `translate(${x * 100}%, ${y * 100}%)`; }, { w: 17, z: 0.7, immediate: !placed.current }, ); useEffect(() => { if (shown) placed.current = true; }, [shown]); useEffect(() => { if (!typed.current) return; typed.current = false; grid.current?.querySelector<HTMLElement>(`[data-date="${iso(focus)}"]`)?.focus(); }, [focus]); const show = (date: Date) => { if (date.getMonth() !== view.month || date.getFullYear() !== view.year) setView({ year: date.getFullYear(), month: date.getMonth() }); }; const turn = (months: number) => { const next = new Date(view.year, view.month + months, 1); setView({ year: next.getFullYear(), month: next.getMonth() }); }; const choose = (date: Date) => { onChange(date); setFocus(date); show(date); }; const key = (e: KeyboardEvent) => { const next = moveDate(focus, e.key, weekStart); if (!next) return; e.preventDefault(); typed.current = true; setFocus(next); show(next); }; const focusable = cells.some((c) => sameDay(c.date, focus)) ? focus : cells.find((c) => c.inMonth)?.date; return ( <div className={styles.root}> <div className={styles.head}> <span className={styles.title} aria-live="polite"> {title} </span> <button type="button" className={styles.nav} aria-label={previousLabel} onClick={() => turn(-1)}> <svg viewBox="0 0 24 24" width={18} height={18} aria-hidden> <path d="M15 5l-7 7 7 7" fill="none" stroke="currentColor" strokeWidth={2.2} strokeLinecap="round" strokeLinejoin="round" /> </svg> </button> <button type="button" className={styles.nav} aria-label={nextLabel} onClick={() => turn(1)}> <svg viewBox="0 0 24 24" width={18} height={18} aria-hidden> <path d="M9 5l7 7-7 7" fill="none" stroke="currentColor" strokeWidth={2.2} strokeLinecap="round" strokeLinejoin="round" /> </svg> </button> </div> <div ref={grid} role="grid" aria-label={title} className={styles.grid}> <div role="row" tabIndex={-1} className={styles.week}> {cells.slice(0, 7).map((c) => ( <span key={c.date.getDay()} role="columnheader" tabIndex={-1} className={styles.weekday}> {weekday.format(c.date)} </span> ))} </div> <div ref={days} className={styles.days}> <span ref={pill} className={styles.pill} data-on={shown ? "" : undefined} aria-hidden /> {Array.from({ length: 6 }, (_, row) => ( <div role="row" tabIndex={-1} key={row} className={styles.row}> {cells.slice(row * 7, row * 7 + 7).map((c) => ( <button key={iso(c.date)} type="button" role="gridcell" data-date={iso(c.date)} data-out={c.inMonth ? undefined : ""} data-today={sameDay(c.date, today) ? "" : undefined} aria-selected={sameDay(c.date, value)} aria-label={long.format(c.date)} tabIndex={sameDay(c.date, focusable) ? 0 : -1} className={styles.day} onClick={() => choose(c.date)} onKeyDown={key} > {c.date.getDate()} </button> ))} </div> ))} </div> </div> </div> ); }components/fluid/spring-calendar/calendar.test.ts import { describe, expect, it } from "vitest"; import { monthGrid, moveDate, sameDay } from "./calendar"; describe("monthGrid", () => { it("fills six full weeks that start on the chosen weekday", () => { const cells = monthGrid(2026, 10, 1); expect(cells).toHaveLength(42); expect(cells[0].date.getDay()).toBe(1); expect(cells.filter((c) => c.inMonth)).toHaveLength(30); expect(cells.find((c) => c.inMonth)?.date.getDate()).toBe(1); }); it("starts on Sunday when asked", () => { const cells = monthGrid(2026, 1, 0); expect(cells[0].date.getDay()).toBe(0); expect(cells[0].inMonth).toBe(true); }); }); describe("moveDate", () => { const day = new Date(2026, 0, 31); it("moves by day, week and month like a date grid", () => { expect(sameDay(moveDate(day, "ArrowRight", 1), new Date(2026, 1, 1))).toBe(true); expect(sameDay(moveDate(day, "ArrowUp", 1), new Date(2026, 0, 24))).toBe(true); expect(sameDay(moveDate(day, "PageDown", 1), new Date(2026, 1, 28))).toBe(true); expect(sameDay(moveDate(new Date(2026, 10, 18), "Home", 1), new Date(2026, 10, 16))).toBe(true); expect(sameDay(moveDate(new Date(2026, 10, 18), "End", 1), new Date(2026, 10, 22))).toBe(true); }); it("returns null for keys it does not handle", () => { expect(moveDate(day, "a", 1)).toBeNull(); }); });components/fluid/spring-calendar/calendar.ts export type Cell = { date: Date; inMonth: boolean }; export const sameDay = (a: Date | null | undefined, b: Date | null | undefined) => !!a && !!b && a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate(); export function monthGrid(year: number, month: number, weekStart = 1): Cell[] { const first = new Date(year, month, 1); const back = (first.getDay() - weekStart + 7) % 7; return Array.from({ length: 42 }, (_, i) => { const date = new Date(year, month, 1 - back + i); return { date, inMonth: date.getMonth() === month }; }); } const addMonths = (date: Date, months: number) => { const target = new Date(date.getFullYear(), date.getMonth() + months, 1); const last = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate(); return new Date(target.getFullYear(), target.getMonth(), Math.min(date.getDate(), last)); }; const addDays = (date: Date, days: number) => new Date(date.getFullYear(), date.getMonth(), date.getDate() + days); export function moveDate(date: Date, key: string, weekStart = 1): Date | null { const offset = (date.getDay() - weekStart + 7) % 7; switch (key) { case "ArrowRight": return addDays(date, 1); case "ArrowLeft": return addDays(date, -1); case "ArrowDown": return addDays(date, 7); case "ArrowUp": return addDays(date, -7); case "PageDown": return addMonths(date, 1); case "PageUp": return addMonths(date, -1); case "Home": return addDays(date, -offset); case "End": return addDays(date, 6 - offset); default: return null; } }components/fluid/spring-calendar/SpringCalendar.module.css .root { display: grid; gap: 14px; width: min(100%, 340px); padding: 20px; border-radius: 24px; background: var(--fluid-surface); color: var(--fluid-text); font-family: var(--fluid-font); overflow: hidden; } .head { display: flex; align-items: center; gap: 4px; } .title { flex: 1; padding-left: 6px; font-size: 17px; font-weight: 600; text-transform: capitalize; } .nav { display: grid; place-items: center; width: 40px; height: 40px; border: 0; border-radius: 999px; background: none; color: var(--fluid-text); cursor: pointer; } .nav:hover { background: color-mix(in srgb, var(--fluid-text) 7%, transparent); } .nav:focus-visible, .day:focus-visible { outline: 2px solid var(--fluid-focus); outline-offset: 1px; } .grid { display: grid; gap: 4px; } .week, .row { display: grid; grid-template-columns: repeat(7, 1fr); } .weekday { color: var(--fluid-text-2); font-size: 12px; font-weight: 500; text-align: center; } .days { position: relative; display: grid; isolation: isolate; } .pill { position: absolute; z-index: -1; top: 0; left: 0; width: calc(100% / 7); height: calc(100% / 6); border-radius: 999px; background: var(--fluid-accent); opacity: 0; transition: opacity 200ms ease; } .pill[data-on] { opacity: 1; } .day { height: 42px; padding: 0; border: 0; border-radius: 999px; background: none; color: var(--fluid-text); font: 500 15px / 1 var(--fluid-font); font-variant-numeric: tabular-nums; cursor: pointer; transition: color 200ms ease; } .day:hover:not([aria-selected="true"]) { background: color-mix(in srgb, var(--fluid-text) 7%, transparent); } .day[data-out] { color: var(--fluid-text-2); opacity: 0.55; } .day[data-today]:not([aria-selected="true"]) { box-shadow: inset 0 0 0 1.5px color-mix(in srgb, var(--fluid-accent) 60%, transparent); } .day[aria-selected="true"] { color: var(--fluid-on-accent); opacity: 1; }Import the theme once, then point its variables at your own tokens.
layout.tsx import "@usefluid/motion/theme.css";
Usage
import { SpringCalendar } from "./SpringCalendar";
const [date, setDate] = useState<Date | null>(null);
<SpringCalendar value={date} onChange={setDate} />API reference
| Prop | Type | Default | Description |
|---|---|---|---|
value | Date | null | — | The chosen day. The calendar opens on its month, or on today. |
onChange | (date) => void | — | Called with the day that was chosen. |
locale | string | the browser's | Language of the month and weekday names. |
weekStart | 0 | 1 | 1 | 1 starts weeks on Monday, 0 on Sunday. |
previousLabel | string | "Previous month" | Accessible name of the back button. |
nextLabel | string | "Next month" | Accessible name of the forward button. |
Keyboard and screen readers
A date grid: Tab reaches one day, the arrow keys move by day and week, Page Up and Page Down by month, Home and End to the start and end of the week, and Enter or Space chooses. Each day is read as a full date, the chosen one as selected, and the month name is announced when it changes. With reduced motion nothing slides.
Notes
monthGrid and moveDate in calendar.ts hold the date logic, if you want it for a range picker of your own. Every colour comes from the --fluid-* variables, and the piece is yours to change.
How it is made
The selection is one pill on two springs, across and down the grid, so it travels between days instead of blinking. Changing month moves the days a short way on a spring from the side you came from. It is a date grid: arrows move by day and week, Page Up and Page Down by month, and each day is read as a full date.
For your agent
For your agent
Add Spring Calendar to my project with the Fluid library. Use SpringCalendar for the date fields of my product, in my language and with my first day of the week. Read my project first. Use my logo, my colours and my font through the --fluid-* variables. Keep 44px touch targets, visible focus and reduced motion. If I have no SVG logo, ask before making one up.