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

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`.

```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.

## Try it

```tsx
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

**cycle mode maps the real lunar phases**

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

## 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
```

Values outside 0–1 clamp instead of overflowing: −0.4 draws a new, dark disc and 1.6 a full, lit one.

## Four homes

**In a sentence**

```tsx
<p>
  Sprint progress{" "}
  <span className="mc-inline">
    <MoonPhase value={0.68} summary={false} />
  </span>{" "}
  — 68% through, waxing past half.
</p>
```

**In a table cell**

```tsx
<td>
  <MoonPhase value={0.68} />
</td>
```

**In a KPI card**

```tsx
<div className="kpi">
  <span className="figure">68%</span>
  <MoonPhase value={0.68} />
</div>
```

**In a tab header**

```tsx
<button className="tab">
  Sprint 12 <MoonPhase value={0.68} />
</button>
```

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