Xzero UI · Components, blocks and MCP

A delete transition that pulls the chosen items into a tiny singularity while the rest of the list bends around it; undo spins them back out.

Type: Component (special)
Access: Xzero Pro
Page: https://ui.xzero.co.uk/components/black-hole
Markdown: https://ui.xzero.co.uk/components/black-hole/markdown
Source file: registry/components/black-hole/black-hole.tsx
Dependencies: motion
Keywords: special, motion, webgl, new, delete animation, archive transition, black hole, singularity, gravitational lensing, spiral, undo, remove items, list delete

When to use

Deleting or archiving a handful of selected rows, cards, or files, with an Undo right after.
Emptying a trash, clearing notifications, or dismissing a batch where the removal should feel final.

When not to use

High frequency deletes such as clearing a single chip or tag. Use a quick height collapse instead.
Irreversible actions without undo. The spectacle should not stand in for a confirmation.
Very long lists that scroll; the effect paints the visible wrapper, so wrap only the scrolling viewport.

Installation

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui-pro/black-hole

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { useLayoutEffect, useRef, useState } from "react";
import { BlackHole } from "@/components/xzero/black-hole/black-hole";
import type { BlackHoleHandle } from "@/components/xzero/black-hole/black-hole";

export function Inbox({ initial }: { initial: Mail[] }) {
  const hole = useRef<BlackHoleHandle>(null);
  const rows = useRef(new Map<string, HTMLLIElement>());
  const [items, setItems] = useState(initial);
  const [selected, setSelected] = useState<string[]>([]);

  async function remove() {
    await hole.current?.swallow(selected.map(id => rows.current.get(id)!));
    setItems(current => current.filter(item => !selected.includes(item.id)));
    setSelected([]);
  }

  return (
    <BlackHole ref={hole}>
      <ul>
        {items.map(item => (
          <li key={item.id} ref={el => { if (el) rows.current.set(item.id, el); }}>{item.subject}</li>
        ))}
      </ul>
    </BlackHole>
  );
}

API reference

BlackHole

Wraps a list or grid. Its ref exposes swallow and release, which run a GPU transition: the chosen items spiral into a tiny singularity while the rest of the content is gravitationally lensed around it, then the hole collapses with a soft shockwave.

Prop	Type	Default	Description
`children` (required)	`ReactNode`	–	The content that holds the items you remove. It is painted to a texture for the length of the effect.
`ref`	`Ref<BlackHoleHandle>`	–	Gives access to `swallow` and `release`.
`className`	`string`	–	Extra class on the root.
`style`	`CSSProperties`	–	Inline styles on the root.

BlackHoleHandle

Imperative methods on the ref. Calls queue, so a release requested during a swallow waits its turn.

Prop	Type	Default	Description
`swallow`	`(targets: Element[], options?: BlackHoleOptions) => Promise<void>`	–	Pulls the elements in. They stay hidden afterwards; remove them from your data when the promise resolves so the list closes the gap.
`release`	`(targets: Element[], options?: BlackHoleOptions) => Promise<void>`	–	The reverse. Call it in a layout effect right after the items are back in the DOM: they are hidden at once, the list makes room, then they spiral out into place.

BlackHoleOptions

Prop	Type	Default	Description
`origin`	`{ x: number; y: number }`	–	Where the hole opens, in viewport coordinates. Defaults to the centre of the targets. Pass the delete button's centre to pull items toward it.
`duration`	`number`	`1.3`	Length of the effect in seconds. The reverse runs a little faster.

Keyboard interactions

Keys	Action
None of its own	The component has no controls. Wire Delete or Backspace to your own selection, as the demo does.

Accessibility

The canvas is aria-hidden and only covers the content while the effect runs; the real DOM is back in place the moment it ends.
Announce the result yourself (for example "2 conversations deleted" with an Undo button in a live region). The effect is visual only.
Pointer events are not blocked on the rest of the page; disable the trigger while a transition runs to avoid double deletes.

Motion

Items fall along a logarithmic spiral. Points nearer the hole start earlier, so the inner edge falls faster than the outer one and rows stretch into arms.
The rest of the content is lensed with the Einstein ring relation, so text near the hole bends and briefly mirrors around it.
The hole opens with a slight overshoot, grows a little as it eats, then collapses and sends out one soft shockwave ring. Undo plays the same path backwards.
With reduced motion, or without WebGL2, the items fade out in 200ms and fade back in on release.

Responsive behavior

Measures the wrapper at the start of every run, so it works at any width including 320px.
The hole and lensing scale with device pixel ratio, capped at 2x.

Performance

Painting the wrapper to two textures takes a few milliseconds for a typical list; the shaders and context are prepared while the page is idle.
Drawing is three passes on the GPU per frame (lensed content, a 5px mesh for the falling items, and the hole), well within a frame at 120Hz.
Textures and buffers are released after each run; one WebGL2 context is kept per instance.

Notes for AI

Use for destructive or archive actions on a list, grid, or board where a moment of drama is welcome and undo is offered.
Keep refs to the item elements (a Map keyed by id works well) and pass the selected ones to swallow. Remove the data only after the promise resolves.
For undo, restore the data, then call release with the re-inserted elements in useLayoutEffect so they never flash. Pair the list with height exit and enter animations so gaps close and reopen smoothly.
The painter handles backgrounds, borders, radii, text, images and inline SVG icons. Box shadows, gradients, pseudo elements and cross origin images are not painted.

Swipe actions: Reveal row actions with a swipe, or from the same actions in a menu.
Toast stack: Stack short results at the edge until you reach for them.

Also in loaders

Stretch refresh: Pull a feed down and a line stretches to tell you when to let go.
Morph loader: Tiny loaders that morph between shapes and fold into a check or a cross when done.
Skeleton morph: Loading skeletons that grow into the real content, block by block, instead of swapping.

Guidance for AI tools

Black hole: A delete transition that pulls the chosen items into a tiny singularity while the rest of the list bends around it; undo spins them back out. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt

Black holePro