Solar Terms Timeline (React)

A content component for tea, produce, wellness and calendar-style sites. The 24 solar terms sit in order on a horizontally scrollable track, split into four seasonal colour bands (spring green, summer vermilion, autumn gold, winter blue); the component locates the current term from date (defaults to today, resolved after mount) — that node scales up, breathes with a soft glow and is scrolled into view automatically. A summary card above shows today's term, how many days remain until the next one, and a one-line phenology / seasonal-food note (24 built-in Traditional Chinese lines, each overridable). Term dates are computed with the common 21st-century approximation (the "Shouxing" formula), which is occasionally off by ±1 day, so almanac values can be passed in as overrides; getSolarTerms() and currentSolarTerm() are exported separately for use elsewhere.

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

<SolarTermsTimeline />

Installation

npx shadcn@latest add https://webberui.com/r/solar-terms-timeline.json

Usage

import {
  SolarTermsTimeline,
  getSolarTerms,
  currentSolarTerm,
} from "@/components/ui/solar-terms-timeline";

// Simplest form: with no date it locates "today" after mount
<SolarTermsTimeline onSelect={(term) => console.log(term.name, term.date)} />

// Fixed date, horizontal term names, almanac override for the formula's ±1-day error, custom note
<SolarTermsTimeline
  date="2026-02-18"
  orientation="horizontal"
  terms={[{ name: "雨水", date: "2026-02-18" }]}
  descriptions={{ 雨水: "春茶預購開跑，濕冷天請多喝溫熱的茶。" }}
/>

// The helpers can be used on their own
getSolarTerms(2026);
// [{ index: 0, name: "小寒", en: "Minor Cold", season: "winter", date: 2026-01-05 }, … 24 entries]

const { current, next, daysUntilNext } = currentSolarTerm(new Date(2026, 7, 18));
// current.name === "立秋" (Start of Autumn), next.name === "處暑" (End of Heat), daysUntilNext === 5

Props

SolarTerm

SolarTermOverride

SolarTermStatus

Return value of currentSolarTerm(date, terms?):

SolarTermsTimelineLabels

Strings overridable through labels; fields containing {name}, {days} or {n} placeholders are filled in at render time:

getSolarTerms(year, overrides?)

getSolarTerms(year: number, overrides?: SolarTermOverride[]): SolarTerm[] — returns the 24 terms of that year (from 小寒 to 冬至), computed with the Shouxing formula, most accurate for 2001–2100. Pass overrides to replace specific dates with almanac values.

currentSolarTerm(date, terms?)

currentSolarTerm(date: Date, terms?: SolarTerm[]): SolarTermStatus — finds the term a date falls in, the next term and the distances in days. terms may be the (already overridden) term list for that year; when omitted the formula is used. The cross-year values — last year's 冬至 and next year's 小寒 — are always computed by the formula.

The constants SOLAR_TERM_NAMES (the 24 names in year order) and SOLAR_TERM_DESCRIPTIONS (the 24 built-in notes keyed by term name), plus the SolarTermSeason type, are also named exports.

How it works

• Date formula: day = int(Y × 0.2422 + C) − L. Y is the last two digits of the year (2001–2100 → 1–100), C is each term's 21st-century constant (小寒 5.4055, 大寒 20.12, 立春 3.87, 雨水 18.73, 驚蟄 5.63, 春分 20.646, 清明 4.81, 穀雨 20.1, 立夏 5.52, 小滿 21.04, 芒種 5.678, 夏至 21.37, 小暑 7.108, 大暑 22.83, 立秋 7.5, 處暑 23.13, 白露 7.646, 秋分 23.042, 寒露 8.318, 霜降 23.438, 立冬 7.438, 小雪 22.36, 大雪 7.18, 冬至 21.94). L is the leap-year correction: the January / February terms (小寒, 大寒, 立春, 雨水) use int((Y − 1) / 4), the rest use int(Y / 4) — in January and February that year's 29 February has not happened yet, so one fewer accumulated leap day counts; using a single L for all terms would shift a whole batch of them by a day in every leap year
• ±1-day error: the approximation occasionally differs from the almanac by one day (known cases include 雨水 2026, 小暑 2016 and 冬至 2021); for production, override with almanac values via terms. The demo and playground show formula values
• Year boundary: the timeline is cyclic — in early January the "current term" is really last year's 冬至, and the component still highlights this year's 冬至 node; after 冬至 the "next term" is next year's 小寒 and the countdown crosses the year correctly
• Selection and summary card: with nothing selected the card shows today's term and "N days until the next term"; after picking another node it shows that term, how many days before / after today it falls, and a "Back to today" button. A value of null means "follow today's term" — in controlled mode, sync it inside onSelect
• Auto-scroll: only the track's own horizontal scrollbar moves (it computes offsetLeft and calls scrollTo on the track) rather than scrollIntoView — the latter also scrolls the whole page, so the page would jump whenever the component sits off-screen
• SSR: without a date, the server and the first render list the 24 term names only, with no dates and a placeholder in the summary card; today is resolved after mount and the dates fill in without layout shift because the node height is reserved

Accessibility

• The outer wrapper is role="region" named by a visually hidden heading (labels.timeline); the track is role="radiogroup" and the 24 nodes are native type="button" elements with role="radio" — aria-checked marks the user's selection, aria-current="date" marks today's term, and each aria-label contains the term name, date and a "current term" note
• Keyboard: roving tabindex — only the current node is in the Tab order; the arrow keys (left / right, up / down) move through the 24 nodes cyclically and select as they go, Home / End jump to 小寒 / 冬至, and the track scrolls along with focus
• The summary-card note lives in an aria-live="polite" region, so switching terms is announced by screen readers; the track points at the card via aria-describedby
• Seasonal bands and the glow are aria-hidden decoration; seasons are not conveyed by colour alone — each band starts with the season name and the summary-card chip carries text and an icon
• When the user has "reduce motion" enabled at the system level, the breathing glow on the current node is replaced by a static faint halo, node scaling and note fades switch instantly, and the auto-scroll uses behavior: "auto" to jump straight to the position