# Sand away

> One call on any element: a front crosses it and every grain it reaches blows away in the picture’s own colours. undoAway() blows it back.

The everyday removal, as one line in your own code. Call sandAway on the photo, card or row being deleted: a front crosses it from the left with a ragged edge, and every grain it reaches lifts and blows back behind it, carrying the real colours of the picture, smaller and fainter as it goes. About a second on a picture and 0.6s on a row, so it reads and is done. The promise resolves and you remove the item from your state the way you already do. If your app offers Undo, undoAway plays it all back from wherever it is: the grains blow in and settle where they came from. Your list, your toast and your API stay yours.

## Install

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

## Usage

```tsx
import { sandAway } from "@/components/sand-away";

<button
  onClick={async (event) => {
    await sandAway(event.currentTarget.closest("figure"));
    setImages((list) => list.filter((i) => i.id !== image.id));
  }}
>
  Delete
</button>
```

## With your toast and its Undo

Blow the image away, keep it in your state until your undo window closes, and call undoAway if the visitor presses Undo. This uses sonner, but any toast works.

```tsx
"use client";
import * as React from "react";
import { Trash2 } from "lucide-react";
import { toast } from "sonner";
import { sandAway, undoAway } from "@/components/sand-away";

type Image = { id: string; url: string; prompt: string };

export function GenerationTile({ image, onDeleted }: { image: Image; onDeleted: (id: string) => void }) {
  const tile = React.useRef<HTMLElement>(null);

  async function remove() {
    if (!(await sandAway(tile.current))) return;
    toast("Image deleted", {
      action: { label: "Undo", onClick: () => undoAway(tile.current) },
      onAutoClose: async () => {
        await fetch(`/api/images/${image.id}`, { method: "DELETE" });
        onDeleted(image.id);
      },
    });
  }

  return (
    <figure ref={tile} className="relative aspect-square overflow-hidden rounded-2xl">
      <img src={image.url} alt={image.prompt} crossOrigin="anonymous" className="size-full object-cover" />
      <button onClick={remove} aria-label="Delete image" className="absolute top-2 right-2">
        <Trash2 className="size-4" />
      </button>
    </figure>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sandAway(element, options?)` | `Promise<boolean>` | – | Blows the element away. Resolves true once it has gone (it stays hidden in the page until you remove it), or false if undoAway brought it back first. |
| `undoAway(element)` | `Promise<boolean>` | – | Plays the removal back, from wherever it is, 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` | `1000 (600 on rows)` | Milliseconds for the whole removal. |

## States

- **blowing away**: A ragged front crosses from left to right in the first 58% of the run; each grain it reaches lifts 24 to 84px and drifts 18 to 64px back behind the front, shrinking by 40% and fading. About 1s on a picture, 0.6s on anything under 90px tall.
- **gone**: The last grain fades. sandAway resolves true; the element is still in the page, hidden, until you remove it.
- **undoing**: undoAway plays it back 30% quicker from wherever it is: the grains blow in and settle into place, and the element shows again. If sandAway was still running, it resolves false.
- **reduced motion**: The element fades out and back in, in 160ms.

## What it handles

Most deletes just blink out, and the ones that animate need a layout-animation library wrapped round your list.

- **One call, any element**: sandAway(element) works on whatever you pass it: an image, a card, a row. No wrapper, no list, no provider.
- **The picture’s real colours**: An element showing a picture is read pixel by pixel, so the grains are the photo itself coming apart.
- **Your state stays yours**: It only hides the element and resolves; you remove the item, call your API and show your own toast.
- **Undo from anywhere**: undoAway(element) plays it back, even mid-removal, so your toast’s Undo button just calls it.
- **Pictures from anywhere**: A picture from another origin without CORS can’t be read, so the element keeps itself behind a moving mask and the grains take its colours.
- **Follows the page**: The grains follow the element every frame, so scrolling during the removal never leaves them behind.

## Replaces

framer-motion exit animation, AnimatePresence, thanos snap effect, dust delete animation, confirm dialog

## Where it fits

- **AI image history**: Delete a generation from the grid and watch it blow away in its own colours.
- **Photo library**: Remove a photo from an album or a camera roll, with your own Undo calling undoAway.
- **Upload list**: Clear a file row before it uploads; on a row the grains take the row’s own colours.
- **Moodboards**: Take a card off a board without a confirm dialog, because it can come back.

## Notes

- An element that shows a picture (an img, canvas or video filling most of it) is drawn from its pixels into a canvas over the page, cut into up to 7,000 grains, while the element itself gets visibility: hidden, so the layout does not move until you remove it.
- For pictures from another origin, serve them with CORS and set crossOrigin="anonymous" on the img to get the real colours; without it the element is masked in place and the grains use its own background, text and edge colours.
- Only one canvas draws per removal and it is removed when the run ends; nothing re-renders your React tree.
- Hidden content leaves the accessibility tree; if the delete button had focus, move focus somewhere sensible (the next item, or your toast), and announce the delete in your own status line.
- Under reduced motion the element fades out and in instead.

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