# Hue Hop

> Every letter hops a hue. `<hue-hop>` colors each letter of a heading or name, one flat color at a time, from a start color to an end color. The text stays text: select it, find it, copy it, read it with a screen reader. One custom element, no dependencies, under 2.5 KB gzipped. Chrome 134+, Firefox 140+, Safari 18+.

This file describes version 0.1.0. Hue Hop is pre-1.0, so pin the version.

## Install

With a bundler:

```bash
npm install hue-hop
```

```js
import 'hue-hop';
```

Without one:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/hue-hop@0.1/dist/hue-hop.js"></script>
```

Add drift only if you use it: `import 'hue-hop/drift.css';`, or a `<link>` to `https://cdn.jsdelivr.net/npm/hue-hop@0.1/dist/drift.css`. Types ship with the package, and the element class is exported as `HueHop`.

## Use

```html
<h1><hue-hop hue="dusk">Midnight Marauders</hue-hop></h1>
```

Rules:

- Headings and names only. Never body copy.
- Use a shipped `hue`, or check your own `start` and `end` against the [lightness table](https://huehop.dev/docs/#keep-them-readable).
- The page needs a `color-scheme` to show the dark side of a `hue`.
- `drift` needs `drift.css`.
- Never set `hops`. The element writes it.
- One tag name per page or shadow root: `hue-hop` or your subclass, not both.
- Keep link underlines on.
- Set `--hop-curve` and `--hop-shift` once, on `:root` or a class. Not per element.
- A `hue` beats inherited values, `--hop-lift` included. To override one, set `start`, `end`, or `--hop-*` on the element, in any CSS layer.
- `display` is for large text only.
- Pin the version.

## Attributes

- `start` (`string`): The color of the first letter, which sets `--hop-start` on this element. Left out, it comes from `hue` if one is set. Otherwise it's picked from the end color.
- `end` (`string`): The color of the last letter, which sets `--hop-end` on this element. Left out, it comes from `hue` if one is set. Otherwise it's picked from the start color.
- `drift` (`boolean`): Slowly sways the hues back and forth, needs `drift.css`, and holds still when the visitor prefers reduced motion.
- `hue` (`'dusk' | 'reef' | 'fern' | 'ember' | 'guava' | 'orchid' | 'honey'`): Picks one of the seven ready-made color pairs.
- `display` (`boolean`): Switches the picked hue to its large-heading version, which passes 3:1 instead of 4.5:1.
- `hops` (`number`): How many color steps the letters use, one per letter up to 64, written by the element itself, so don't set it.

## Properties

- `hops` (`number`, read-only): How many color steps the letters use, one per letter up to 64, or `0` when the element is off the page or the browser lacks support.
- `start` (`string | null`): The color of the first letter, mirroring the `start` attribute, where `null` removes it.
- `end` (`string | null`): The color of the last letter, mirroring the `end` attribute, where `null` removes it.

## CSS

- `--hop-start` (`<color>`): The color of the first letter. Left out, it's picked from `--hop-end`.
- `--hop-end` (`<color>`): The color of the last letter. Left out, it's picked from `--hop-start`.
- `--hop-curve` (`<number>`, default `1`): How the steps are spaced: `1` is even, higher stays near the start color longer, and lower reaches the end color sooner.
- `--hop-lift` (`<number>`, default `0`): How much extra color intensity (OKLCH chroma) the middle letters get, so the blend doesn't go dull halfway.
- `--hop-shift` (`<number>`, default `0`): Turns each letter's hue by this many degrees, written as a plain number (`30`, not `30deg`).
- `--hop-drift-range` (`<number>`, default `24`): How many degrees the hues sway each way when `drift` is on, written as a plain number.
- `--hop-drift-cycle` (`<number>`, default `10`): How many seconds one full sway there and back takes when `drift` is on, written as a plain number.

## Highlights

The colors are highlights named `hue-hop-0` up to `hue-hop-63` in `CSS.highlights`, at priority -1. The names are public and frozen. `CSS.highlights.clear()` removes the colors until the text changes or the element reconnects.

## Docs

- [Get Started](https://huehop.dev/docs/#get-started)
- [Build with AI](https://huehop.dev/docs/#build-with-ai)
- [Hues](https://huehop.dev/docs/#hues)
- [Your Own Colors](https://huehop.dev/docs/#your-own-colors)
- [Light and Dark](https://huehop.dev/docs/#light-and-dark)
- [Drift](https://huehop.dev/docs/#drift)
- [Where It Fits](https://huehop.dev/docs/#where-it-fits)
- [Tuning the Ramp](https://huehop.dev/docs/#tuning)
- [Styling Around It](https://huehop.dev/docs/#styling)
- [Frameworks and Editors](https://huehop.dev/docs/#frameworks-and-editors)
- [Testing Your App](https://huehop.dev/docs/#testing)
- [Before It Loads](https://huehop.dev/docs/#before-it-loads)
- [API](https://huehop.dev/docs/#api)
- [Accessibility](https://huehop.dev/docs/#accessibility)
- [Browser Support](https://huehop.dev/docs/#browser-support)
- [How It Works](https://huehop.dev/docs/#how-it-works)
- [Known Limits](https://huehop.dev/docs/#known-limits)
- [Troubleshooting](https://huehop.dev/docs/#troubleshooting)
- [Inspiration](https://huehop.dev/docs/#inspiration)
- [Support](https://huehop.dev/docs/#support)
- [Colophon](https://huehop.dev/docs/#colophon)

Studio, for checking your own colors: https://huehop.dev/studio/