# MoonPhase (/docs/charts/moon-phase)

MoonPhase answers "how far through the cycle or period are we?" with a form almost everyone reads without a legend: the
illuminated fraction of a disc. The lit **area** equals the value exactly — a closed-form terminator, not the
phase-angle approximation that under-lights mid-cycle — so 50% genuinely lights half the disc. Progress mode fills
monotonically; cycle mode maps the real lunar sequence.

```tsx
<span className="inline-flex gap-3 items-center">
  <MoonPhase value={0.1} size={24} title="10%" />
  <MoonPhase value={0.35} size={24} title="35%" />
  <MoonPhase value={0.5} size={24} title="50%" />
  <MoonPhase value={0.75} size={24} title="75%" />
  <MoonPhase value={1} size={24} title="full" />
</span>
```

## Install

```tsx
import { MoonPhase } from "@microcharts/react/moon-phase";

<MoonPhase value={0.68} title="Sprint" />
```

Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent.


## When to use it

- **Good for** — sprint or quota progress in a sentence, a billing-period or release-cycle marker, or any 0–1 completion
  that reads at a glance.
- **Avoid for** — exact percentages (Progress), trends (Sparkline), or comparisons (MiniBar).


## Variants

```tsx
<MoonPhase value={0.25} mode="cycle" /> // first quarter
<MoonPhase value={0.5} mode="cycle" />  // full moon
```

## Edge cases

```tsx
<MoonPhase value={-0.4} title="Below zero" /> // clamps to 0 — new, dark disc
<MoonPhase value={1.6} title="Above one" />    // clamps to 1 — full, lit disc
```


## Why this default

Progress mode is the default because period-progress is the common need — a sprint or quota filling from new to full,
monotonically. Pretending the real lunar cycle is monotonic would lie (it waxes then wanes), so `mode="cycle"` is a
separate, explicit data-semantic switch, not a preset. The lit area is always exactly the value via the closed form —
never the phase-angle shortcut. Area is a medium-precision channel, so steer exact reads to `Progress`; MoonPhase is for
the glance.

## 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`), 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](/docs/accessibility#one-interaction-contract).

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `value` (required) | `number` | Fraction 0–1 (clamped). |
| `mode` | `"progress" \| "cycle"` | progress = monotonic fill; cycle = true lunar mapping (0 new → 0.5 full → 1 new). |

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](/docs/quickstart#the-shared-grammar).