# Light writing

> A welcome that writes itself: one line of light writes the word, then bends into the next word or into your logo.

Handwritten welcomes on the web are usually a video or a Lottie file: one word, one size, one colour, and no way to change what it says. Here the word is drawn live. A glass tube writes it in one continuous line with a white-hot tip, slowing in the loops and running on the straights the way a hand does. Your theme colours flow along it, and where the line crosses itself you see the lower pass through the upper one. Give it several items and the same line squeezes together and unfolds as the next word, or as your logo from any SVG path. Hide it and the tail chases the tip until nothing is left. Any Latin text works, accents included, so it can greet people by name and in their own language.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/light-writing.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): none
- Docs and live preview: https://hairlineui.com/ui/light-writing
- Registry item (source): https://hairlineui.com/r/light-writing.json

## Usage

```tsx
import { LightWriting } from "@/components/light-writing";

<LightWriting text="hello" />
```

## A launch screen that ends on your logo

Your name is written while the app loads; when it is ready, the same line turns into your mark, and the screen goes once the mark is drawn. Any SVG path works as the mark; drawn as one or two lines it morphs best.

```tsx
"use client";
import { LightWriting } from "@/components/light-writing";

// Your logo as an SVG path. One continuous outline morphs best.
const MARK = "M50 128 L23 60 C10 57 8 36 24 31 C24 13 46 6 56 16 C68 8 88 18 82 36 C94 42 90 60 77 60 L50 128";

export function LaunchScreen({ ready, onDone }: { ready: boolean; onDone: () => void }) {
  return (
    <div className="grid h-dvh place-items-center bg-background">
      <LightWriting
        items={["Acme", { path: MARK, label: "Acme" }]}
        index={ready ? 1 : 0}
        onWritten={(i) => {
          if (i === 1) setTimeout(onDone, 700);
        }}
        className="w-[min(90vw,640px)]"
      />
    </div>
  );
}

// Or greet people in their own languages before onboarding.
const HELLO: Record<string, string> = { en: "hello", es: "hola", fr: "bonjour", it: "ciao", pt: "olá", de: "hallo" };

export function Welcome() {
  const words = [...new Set(["en", ...navigator.languages.map((l) => l.slice(0, 2))])].flatMap((l) => HELLO[l] ?? []);
  return <LightWriting items={words.length > 1 ? words : Object.values(HELLO)} />;
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | – | One word or phrase to write. |
| `items` | `Array<string \| { path: string; label: string }>` | – | Several items shown in turn: words, or marks as an SVG path `d` with what they say. Wins over text. |
| `index / defaultIndex / onIndexChange` | `number / number / (index: number) => void` | `— / 0` | The item showing. Pass index to drive it yourself, for example the logo once the app is ready. |
| `autoPlay` | `boolean` | `true with several items and no index` | Move on to the next item after each hold. |
| `loop` | `boolean` | `true` | Go back to the first item after the last. |
| `hold` | `number` | `2000` | How long each item stays once written, in ms. |
| `change` | `"morph" \| "rewrite"` | `"morph"` | Bend the line into the next item, or erase it and write the next. |
| `show` | `boolean` | `true` | false erases it; true writes it again. |
| `speed` | `number` | `1` | Pen speed. At 1, "hello" takes about 1.8s. |
| `weight` | `number` | `0.36` | Tube thickness as a fraction of the letters' x-height. |
| `colors` | `string[]` | `chart-1, chart-2, chart-5` | CSS colours that flow along the line (up to six). Theme variables work; neighbours blend through the hues between them. If the theme's chart colours are all grey (shadcn's neutral theme), the default uses its own blue, pink and orange instead. |
| `glow` | `number` | `1` | Light around the tube, 0 to 1. Lighter on light backgrounds, where light reads as a tint. |
| `onWritten` | `(index: number) => void` | – | Called when an item has been written, or the line has finished turning into it. |
| `label` | `string` | – | What it says, for screen readers. Defaults to the items' words. |

## States

- **writing**: The tip writes the item from its first stroke to its last, burning white as it goes and cooling over 0.35s after each stroke ends. "hello" takes about 1.8s at speed 1.
- **holding**: The item stays for `hold` ms (2000 by default) while the colours keep flowing along the line, about a fifth of a band per second.
- **morphing**: The line pulls in sideways by up to 42% and unfolds as the next item on a spring (about 0.9s). Points near the start of each stroke move first, so the change runs along the line.
- **rewriting**: With change="rewrite", the tail chases the tip 1.5 times faster than it was written, then the next item is written.
- **hidden**: With show={false} the line is erased the same way; set it back to true and the item is written again.
- **reduced motion**: Each item appears whole and still, the colours stop flowing, and items still take turns.

## What it handles

A written-on word looks easy until you need a second one. Videos and Lottie files are fixed to one word and colour, stroke-dash tricks need a single-line font nobody has, and moving from one word to the next means a cut. This writes any text you pass and moves between items in one line.

- **Any text, one line**: Letters come from a single-line script and are joined into the strokes a hand would draw; i-dots and t-crosses come after their word.
- **Written like a hand**: The pen slows in tight curves and speeds up on gentle ones (the two-thirds power law of handwriting), so loops take their time.
- **Word into word, word into logo**: Strokes are paired longest with longest and turned the way that moves them least; leftover strokes melt into the line or grow out of it.
- **Your mark from a path**: Pass any SVG path `d` and it is scaled to the lettering and drawn with the same tube, so a launch screen can end on your logo.
- **Light in glass, from your theme**: A pale fill with glowing rims, passes that show through each other, your chart colours flowing along it, and a glow on dark pages.
- **Sleeps when unseen**: It starts writing when it scrolls into view, stops off screen and in hidden tabs (holds wait too), and shows each item whole under reduced motion.

## Replaces

Lottie handwriting animation, welcome video, stroke-dashoffset SVG trick, single-line font hunt, splash screen GIF, vivus, flubber, framer-motion

## Where it fits

- **First-run welcome**: "hello" in the visitor's languages, each word turning into the next, before onboarding starts.
- **Launch screen**: Your name is written while the app loads, then the line bends into your logo once it is ready.
- **Sign-up done**: "welcome" is erased and the new member's name is written in its place.
- **Thank-you and end screens**: A thank-you after checkout, a signature under a letter, a sign-off at the end of a tour.

## Notes

- The component is role="img", named with its words (or your label); the canvas is hidden from assistive tech.
- It sizes to its container: full width at a 12:5 aspect ratio by default; set a width, height or aspect class to change it. Every word is drawn at one letter size and baseline, so changes don't jump.
- Writing starts when it scrolls into view. It stops off screen and in a hidden tab, and the hold timer waits with it.
- The letters are EMS Allure, a single-line script derived from Allura, under the SIL Open Font License; the notice ships in light-writing-glyphs.ts (about 10 KB gzipped). It covers Latin letters, accents, numbers and common punctuation; other scripts can be passed as paths.
- Rendering is WebGL 2: the line is rebuilt as triangle strips each frame (inner walls stop short in tight turns, and pen reversals end round), a map of which pass is on top lets earlier passes show through later ones without a pass doubling over itself, and the glow is blurred at a quarter and an eighth of the size. Without WebGL 2 it draws the item as a still SVG line in the same colours.
- Under reduced motion, items appear whole and still and the colours stop flowing.

License: MIT (https://hairlineui.com/license#components)
