# Eclipse

A dark disc with a glowing rim and a soft corona that breathes slowly, for launch pages and event heroes.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. The dithercn agent skill, for building any dither on the engine, is at [/.well-known/agent-skills/dithercn/SKILL.md](/.well-known/agent-skills/dithercn/SKILL.md).

> **This is an example, not the only option.** It is one component built on the dithercn engine. Install it when it is what you were asked for. For any other look, don't stretch its props to fit: write your own field on `DitherShader` ([Write your own dither](/docs/engine/write-your-own.md)), and read this example's source for technique. Its full source is in [https://dithercn.dev/r/eclipse.json](https://dithercn.dev/r/eclipse.json), under `files[].content`.

## Installation [#installation]

```bash
npx shadcn@latest add https://dithercn.dev/r/eclipse.json
```

## Usage [#usage]

```tsx
import { Eclipse } from "@/components/dithercn/eclipse";

export function Hero() {
  return (
    <section className="relative isolate min-h-[480px]">
      <Eclipse className="absolute inset-0 -z-10" />
      <h1>Your headline</h1>
    </section>
  );
}
```

A disc in `skyColor` sits in front of a light in `rimColor`. A thin rim hugs the edge and is brightest on the `light` side, like the crescent of a real eclipse. Around it, a halo fades outwards with slow variations in strength, and the whole glow breathes on a slow ten-second cycle.

## Examples [#examples]

### Beside a headline [#beside-a-headline]

The disc sits in the top right with a short corona, lit from the lower left, and the text sits in the clear space below it. This layout holds from phone to desktop widths.

```tsx title="examples/eclipse-headline.tsx"
import { Eclipse } from "@/components/dithercn/eclipse";

export default function EclipseHeadline() {
  return (
    <section className="relative isolate flex size-full flex-col justify-end p-8 sm:p-12">
      <Eclipse
        center={[0.78, 0.28]}
        size={0.3}
        corona={0.35}
        light={225}
        className="absolute inset-0 -z-10"
      />
      <div className="flex max-w-xs flex-col gap-3">
        <h3 className="text-3xl font-medium tracking-[-0.03em] text-balance">
          Totality, on 12 August
        </h3>
        <p className="text-muted-foreground text-sm text-pretty">
          The disc sits high on the right and is lit from the lower left, so the
          brightest edge of the rim faces the text below it.
        </p>
      </div>
    </section>
  );
}
```

### Amber on warm black [#amber-on-warm-black]

Explicit colours instead of theme tokens, a smaller disc, a wider corona and the full `pulse`. The 8×8 matrix gives a finer texture.

```tsx title="examples/eclipse-amber.tsx"
import { Eclipse } from "@/components/dithercn/eclipse";

export default function EclipseAmber() {
  return (
    <Eclipse
      size={0.18}
      corona={0.7}
      pulse={1}
      light={20}
      rimColor="oklch(0.8 0.15 65)"
      skyColor="oklch(0.14 0.02 60)"
      matrix="bayer8"
      className="absolute inset-0"
    />
  );
}
```

## Props [#props]

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `center` | `[x: number, y: number]` | `[0.5, 0.5]` | Centre of the disc, as fractions of the box from the top left. |
| `size` | `number` | `0.24` | Radius of the disc as a share of the box height. |
| `corona` | `number` | `0.5` | How far the halo reaches past the rim, from 0 to 1. |
| `light` | `number` | `315` | Where the rim is brightest, in degrees as in CSS: 0 is the top. |
| `pulse` | `number` | `0.5` | How much the glow breathes, from 0 (steady) to 1. |
| `rimColor` | `DitherColor` | `"--dither-ink"` | Colour of the rim and halo: a palette name such as "orange", a CSS variable name, or any CSS colour. |
| `skyColor` | `DitherColor` | `"--dither-paper"` | Colour of the sky and the disc. |
| `matrix` | `"bayer2" \| "bayer4" \| "bayer8" \| "blue-noise"` | `"bayer4"` | The threshold pattern. See Dither engine. |
| `cell` | `number` | `--dither-cell` | Size of one dither cell in CSS pixels. |
| `speed` | `number` | `1` | How fast the halo shifts and breathes. |
| `animate` | `boolean` | `true` | false stops the motion: a still frame if it starts off, the current frame if it was moving. |
| `className` | `string` | `–` | Size and position. The eclipse fills this box. |

## Notes [#notes]

* The eclipse is decorative and hidden from assistive technology. Put real text on top of it, not inside it.
* With reduced motion turned on, it draws one still frame and stops.
* It pauses when scrolled out of view or when the tab is hidden, and releases its WebGL context when far offscreen. Without WebGL it shows a CSS disc and ring.
* The disc is the sky colour, so on a light theme it reads as a pale disc with a coloured ring. Pass a dark `skyColor` for a dark disc on any theme.