# Image sphere

A shadcn/ui 3D image gallery block for portfolios that want a wow moment: your images on a WebGL globe visitors spin, with groups that open on click.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available for the docs, pricing and about pages: append `.md` to the URL or send an `Accept: text/markdown` header (the home page answers the header too). An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

## At a glance

- **Good for:** Portfolio and gallery pages; Agency and studio websites; Brand, product or campaign image showcases; Event and launch microsites
- **Category:** Marketing, Portfolio · **Type:** Gallery · **Style:** Motion, Dark mode
- **See it:** [Live preview](https://www.craftui.space/docs/blocks/image-sphere) · [Screenshot](https://www.craftui.space/llms.md/preview/image-sphere.cac6a0df.jpg)

![Image sphere](https://www.craftui.space/llms.md/preview/image-sphere.cac6a0df.jpg)

## Install

```bash
pnpm dlx shadcn@latest add https://www.craftui.space/r/image-sphere.json
```

This is a paid item (BLK-0001): the install needs a craftUI plan or a purchase of it. Signed in, the docs page gives your personal install command. Plans: https://www.craftui.space/pricing

## Usage

```tsx
import ImageSphere from "@/components/blocks/image-sphere";

export default function Page() {
  return <ImageSphere />;
}
```

With no props it renders with demo content; pass your own through the props below.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `ImageSphereItem[]` | `built-in demo content` | Your images. Each can belong to a group, which gathers into a pile. |
| `groups` | `ImageSphereGroup[]` | `built-in demo content` | The groups items belong to, by id, with the label shown on hover. |
| `count` | `number` | — | Cards on the sphere; items repeat round it to fill them. Defaults to 240, or 140 on screens narrower than 40rem. Never fewer than items. |
| `autoRotate` | `boolean` | `true` | Turns slowly while nobody's using it and no group is open. |
| `defaultGroup` | `string \| null` | `null` | The group open at first, by id. |
| `group` | `string \| null` | — | The open group, when the parent decides it (e.g. from scroll). Clicks then only report through `onGroupChange`, and the block's own keyboard buttons are left out: the parent's controls take their place. |
| `onGroupChange` | `(group: string \| null) => void` | — | Called when a group opens (its id) or closes (null). |
| `allLabel` | `string` | `"All"` | The keyboard button that closes the open group. |
| `hint` | `ReactNode` | `"Drag to spin · Click an image"` | The line in the top corner, until the first touch. Pass null to hide it. |
| `turnDuration` | `number` | `45` | Seconds the globe takes for one full turn when idle. Defaults to 45. |
| `pileSize` | `number` | `CLUSTER_MAX` | Most images a group's pile shows. Defaults to 12. |
| `pileCurve` | `number` | `0.6` | How curved the pile's images are, from 0 (flat) to 1 (most curved). Defaults to 0.6. |

It also accepts every `<section>` attribute (`className`, `id`, `aria-*` and so on).

### `ImageSphereItem`

| Field | Type | Description |
| --- | --- | --- |
| `src` (required) | `string` | Image URL. The card keeps its shape, cropped only past tall portrait (0.62) or 16:9. |
| `alt` (required) | `string` | Describes the image for screen readers. |
| `group` | `string` | A group's `id`. Items without one stay on the sphere. |

### `ImageSphereGroup`

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` | Unique id that items point at with their `group`. |
| `label` (required) | `string` | The group's name: the tag beside the pointer on hover, and its keyboard button. |

## Files

The install adds:

- `components/blocks/image-sphere.tsx`
- `components/blocks/image-sphere-scene.ts`
- `components/blocks/image-sphere-gl.ts`

No npm dependencies beyond React and Tailwind CSS.