# Burn away

> One call for the delete that is final: a glowing edge eats across the element and every grain rises as an ember.

A removal that looks as final as it is. Call burnAway on the image, file or row being destroyed: a burning edge starts at the bottom corner and eats across to the top, and each grain glows hot the moment it lets go, its own colour heating towards orange, then rises and fades as an ember. Use it where the action can’t be taken back on the server (purge, empty trash, delete forever), so the motion is louder than an everyday delete and people notice what they did. The promise resolves and you remove the item from your state. undoAway still plays it back for the few seconds your app allows.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/burn-away.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/burn-away
- Registry item (source): https://hairlineui.com/r/burn-away.json

## Usage

```tsx
import { burnAway } from "@/components/burn-away";

await burnAway(rowRef.current);
await fetch(`/api/files/${file.id}?forever=1`, { method: "DELETE" });
setFiles((list) => list.filter((f) => f.id !== file.id));
```

## Behind a hold, in the trash

Hold to delete forever: when the hold completes, the row burns, then your API deletes it for good.

```tsx
"use client";
import * as React from "react";
import { HoldToConfirm } from "@/components/hold-to-confirm";
import { burnAway } from "@/components/burn-away";

export function TrashRow({ file, onPurged }: { file: { id: string; name: string }; onPurged: (id: string) => void }) {
  const row = React.useRef<HTMLDivElement>(null);
  return (
    <div ref={row} className="flex items-center justify-between rounded-xl border p-3">
      <span>{file.name}</span>
      <HoldToConfirm
        labels={{ idle: "Hold to delete forever", holding: "Keep holding", pending: "Deleting" }}
        onConfirm={async () => {
          await burnAway(row.current);
          await fetch(`/api/trash/${file.id}`, { method: "DELETE" });
          onPurged(file.id);
        }}
      />
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `burnAway(element, options?)` | `Promise<boolean>` | – | Burns the element away. Resolves true once it has gone (it stays hidden in place until you remove it), or false if undoAway brought it back first. |
| `undoAway(element)` | `Promise<boolean>` | – | Plays the burn back and shows the element again. Resolves true once it is back. |
| `isAway(element)` | `boolean` | – | True while the element is removed or being removed and not brought back. |
| `options.duration` | `number` | `1250 (750 on rows)` | Milliseconds for the whole removal. |

## States

- **burning**: The edge travels from the bottom-right corner to the top-left in the first 58% of the run. Each grain glows for the first half of its life (its colour heated towards orange, scaled up by 30%), drifts 17px either way and rises 34 to 118px as it fades. About 1.25s on a picture, 0.75s on a row.
- **gone**: The last ember fades. burnAway resolves true; the element stays hidden in place until you remove it.
- **undoing**: undoAway plays it back 30% quicker: the embers fall back and cool into the picture.
- **reduced motion**: The element fades out and back in, in 160ms.

## What it handles

A permanent delete usually looks exactly like an everyday one, so nothing tells people this one can’t be undone.

- **Reads as final**: A hot edge and rising embers say this one is gone for good, where sand or a fold would say it can come back.
- **One call, any element**: burnAway(element) works on an image, a card or a row; your state, toast and API stay yours.
- **Its own colours, heated**: Each grain starts as the picture’s real colour and heats towards orange as it lets go, so the burn is of this picture.
- **Pairs with a hold**: Put it behind hold-to-confirm and the hold’s end is the spark.
- **Undo while you can**: undoAway plays it back from wherever it is, for the seconds before your server deletes it.
- **Pictures from anywhere**: Without CORS the element burns behind a moving mask with grains in its own colours, instead of failing.

## Replaces

fire animation, burn effect css, delete forever animation, framer-motion exit animation

## Where it fits

- **Trash**: Delete forever, or empty the trash, and see each item burn.
- **AI image history**: Purge a generation from storage, not just from the grid.
- **Secrets and keys**: Revoke a key or destroy a backup with a removal that reads as final.
- **Exports**: Remove a rendered master after a hold-to-confirm.

## Notes

- The heat is the grain’s own colour mixed towards orange in four steps worked out once per grain, so a frame only picks a step; nothing glows outside the grains.
- Pictures are drawn from their pixels in a canvas over the page while the element is hidden in place; serve pictures from other origins with CORS and crossOrigin="anonymous" for their real colours.
- Announce a permanent delete in your own status line; the element leaves the accessibility tree once hidden.
- Under reduced motion the element fades out and in instead.

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