Bubble Cluster, animated React component

Contacts packed into one cluster of avatar bubbles sized by how close they are, sitting on a liquid backdrop. Switch groups and everyone springs to new places and sizes while people outside the group shrink away.

Pro
Motion Effects
Spring

Play with it

Move the controls and watch it change. Copy code gives you a snippet with only the props you changed.

MomDadRiyaArjunJoIvy

Props

Prop	Type	Default	What it does
people	ClusterPerson[]	12 sample contacts	Everyone who can appear, as { id, name, hue }; hue (0-360) tints the avatar gradient.
groups	Record<string, Record<string, number>>	Family, Close friends, Work	Group name to { person id: closeness 1-5 }. Closeness sets bubble size; people left out of a group hide in it.
autoplay	boolean	false	Steps through the groups every 2.4s until someone presses the cluster or the switcher.

Add it to your project

Prepare your project

You need Tailwind CSS and the @/import alias. If shadcn isn't set up yet, initialise it once:

npx shadcn@latest init

Then add the Nexus registry to your components.json (the registries key is the part that matters):

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "@nexus-labs": "https://www.nexus-ui.com/api/registry/{name}"
  }
}

2
Add the component
Run this from your project root. It adds the component, the utilities it uses and its packages.
```
npx shadcn@latest add @nexus-labs/bubble-cluster
```
3
Check what was added
With the standard aliases, these files land in your project:
components/
bubble-cluster/
bubble-cluster.tsx
index.ts
4
Copying by hand? Install the packages
Skip this if you used the command above.
```
npm install framer-motion
```

Use it in a page

Import it and render it. The Code tab above has the full example.

// app/page.tsx
import { BubbleCluster } from "@/components/bubble-cluster";

export default function Page() {
  return (
    <main>
      <BubbleCluster />
    </main>
  );
}

BubbleBubble Cluster, animated React component

Play with it

Props

More motion effects

Bubble Cluster, animated React component