MoonPhase
MoonPhase lights a fraction of a disc, with the lit area exactly equal to the value.
- encodes
- illuminated area fraction of the disc
- precision
- medium
- nodes
- 3
- collection
- Expressive
MoonPhase lights a fraction of a disc, a form most people read without a legend. The lit area equals the value
exactly, via a closed-form terminator rather than the phase-angle approximation that under-lights mid-cycle, so 50%
lights half the disc. Progress mode is the default and fills monotonically, the way a sprint, quota, or billing period
does. The real lunar cycle waxes and then wanes, so mode="cycle" is a separate, explicit data-semantic switch rather
than a preset. Area is a medium-precision channel: for exact reads use Progress.
Install
import { MoonPhase } from "@microcharts/react/moon-phase";<MoonPhase value={0.68} title="Sprint" />Try it
- hover · click · Enter…
Tap to advance the phase — the lit region cross-fades to its new area (reduced-motion → it swaps), hover reveals the percent, and each change is announced through a polite live region.
import { MoonPhase } from "@microcharts/react/moon-phase/interactive";<MoonPhase value={0.68}/>When to use it
Use it for sprint or quota progress in a sentence, a billing-period or release-cycle marker, or any 0–1 completion. For exact percentages use Progress, for trends use Sparkline, and for comparisons use MiniBar.
Sizing
Variants
Edge cases
Values outside 0–1 clamp instead of overflowing: −0.4 draws a new, dark disc and 1.6 a full, lit one.
Four homes
Sprint progress — 68% through, waxing past half.
| Sprint 12 | 68% | |
| Sprint 11 | 100% | |
| Sprint 10 | 82% |
Preview uses the public chart API only. When an interactive twin exists, it swaps in with the same props and no entrance motion - code samples stay on the static import. Placement recipes: Composition, Sizing.
Accessibility
The accessible name states the fraction: "0% of the cycle complete." in progress mode, or "0% through the cycle." in
cycle mode. The interactive entry fades the lit region back in on change with a slight bloom — opacity plus a small
scale, never a path interpolation, and skipped entirely under prefers-reduced-motion. It reveals the exact percent on
hover or focus, and announces changes through a polite live region throttled to at most once a second.
This chart is a single unit, so there is nothing to rove between: a click, tap, Enter or Space selects it
and fires onSelect, and no selection stays pinned. That is the scalar half of the shared
interaction contract.
Hover or focus also reveals the reading itself in a floating chip, for the sizes and label modes where the mark
does not print it; readout={false} drops the chip and keeps everything else.
Props
| Prop | Type | Notes |
|---|---|---|
| value* | number | Fraction 0–1 (clamped). |
| mode | "progress" | "cycle" | progress = monotonic fill; cycle = true lunar mapping (0 new → 0.5 full → 1 new). |
| size | number | Disc box edge in viewBox units (default 16). |
Plus the shared grammar — data, domain, color, title, summary, format — and the layout props (width, height, className, style) that every chart accepts. Interactive entries also share animate and live, and — wherever a chart has more than one navigable unit — onActive, onSelect, selectedIndex and defaultSelectedIndex; and — wherever the chart shows a hover value — readout. See the shared grammar.