# Illustration

Show a drawing of a cloud, a box, a credit card or a few documents, with an optional glyph, to give an empty state its picture.

A cloud with a magnifier

[Complete TSX file](/examples/illustration/default.tsx)

```tsx
"use client";

import { MagnifyingGlassIcon } from "@phosphor-icons/react/dist/ssr";
import { Illustration } from "@/siteplane/components/illustration";

export default function Example() {
  return (
    <Illustration type="cloud">
      <MagnifyingGlassIcon aria-hidden="true" />
    </Illustration>
  );
}
```

## Installation

Complete [one-time setup](/docs/installation/) first.

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/illustration
```

With npm: `npx shadcn@4.18.0 add @siteplane/illustration`. [Registry JSON](/registry/illustration.json) lists source files and dependencies.

For this page’s examples, also install:

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/button @siteplane/card @siteplane/empty-state
```

## Usage

```tsx
import { MagnifyingGlassIcon } from "@phosphor-icons/react/dist/ssr";

import { Illustration } from "@/siteplane/components/illustration";

<Illustration type="cloud">
  <MagnifyingGlassIcon aria-hidden="true" />
</Illustration>;
```

## Types

`type` picks the drawing: `cloud`, `box`, `credit-card` or `documents`. Each object stands on a soft disc with a few specks around it and casts a soft shadow. The drawing uses the kit's surface and edge tokens, the muted tint for the disc, the card surface for the object and the hairline color for its edge and details, so it follows the theme in Light and Dark.

The cloud, box, credit card and documents

[Complete TSX file](/examples/illustration/types.tsx)

```tsx
"use client";

import {
  MagnifyingGlassIcon,
  PlusIcon,
  UploadSimpleIcon,
  WarningCircleIcon,
} from "@phosphor-icons/react/dist/ssr";
import { Illustration } from "@/siteplane/components/illustration";

export default function Example() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-8">
      <Illustration type="cloud">
        <UploadSimpleIcon aria-hidden="true" />
      </Illustration>
      <Illustration type="box">
        <MagnifyingGlassIcon aria-hidden="true" />
      </Illustration>
      <Illustration type="credit-card">
        <WarningCircleIcon aria-hidden="true" />
      </Illustration>
      <Illustration type="documents">
        <PlusIcon aria-hidden="true" />
      </Illustration>
    </div>
  );
}
```

## Sizes

`size` sets the height: `sm` is 120 px, `md` 128 px and `lg`, the default, 160 px. The width follows the drawing's proportions, 165, 176 and 220 px.

Illustrations at sm, md and lg

[Complete TSX file](/examples/illustration/sizes.tsx)

```tsx
"use client";

import { MagnifyingGlassIcon } from "@phosphor-icons/react/dist/ssr";
import { Illustration } from "@/siteplane/components/illustration";

const sizes = ["sm", "md", "lg"] as const;

export default function Example() {
  return (
    <div className="flex flex-wrap items-end justify-center gap-8">
      {sizes.map((size) => (
        <Illustration key={size} size={size} type="cloud">
          <MagnifyingGlassIcon aria-hidden="true" />
        </Illustration>
      ))}
    </div>
  );
}
```

## Glyph

Children float over the lower middle of the drawing in a frosted disc: a translucent dark disc that blurs what lies behind it, with a white glyph at half its size. The disc is 56 px at `lg` and `md` and 48 px at `sm`. Pass a Phosphor icon with `aria-hidden="true"`; the disc sizes it. Without children, the drawing stands alone.

Documents without and with a glyph

[Complete TSX file](/examples/illustration/glyph.tsx)

```tsx
"use client";

import { FileArrowUpIcon } from "@phosphor-icons/react/dist/ssr";
import { Illustration } from "@/siteplane/components/illustration";

export default function Example() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-8">
      <Illustration type="documents" />
      <Illustration type="documents">
        <FileArrowUpIcon aria-hidden="true" />
      </Illustration>
    </div>
  );
}
```

## In an empty state

Put the illustration in the media of an [Empty State](/docs/components/empty-state/#illustration) with `variant="illustration"`. The media gives it the height of the Empty's size, 160, 128 or 120 px at `lg`, `md` and `sm`. The disc of the glyph is a share of the height of the Illustration's own `size`, so give the Illustration the size of its Empty too.

A failed payment in an empty state

[Complete TSX file](/examples/illustration/empty-state.tsx)

```tsx
"use client";

import { WarningCircleIcon } from "@phosphor-icons/react/dist/ssr";
import { Button } from "@/siteplane/components/button";
import { Card } from "@/siteplane/components/card";
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@/siteplane/components/empty-state";
import { Illustration } from "@/siteplane/components/illustration";

export default function Example() {
  return (
    <div className="w-full max-w-md">
      <Card>
        <Empty className="px-6 py-16" size="md">
          <EmptyHeader>
            <EmptyMedia variant="illustration">
              <Illustration size="md" type="credit-card">
                <WarningCircleIcon aria-hidden="true" />
              </Illustration>
            </EmptyMedia>
            <EmptyTitle>Your payment failed</EmptyTitle>
            <EmptyDescription>
              We could not charge the card ending in 4242. Update your payment
              method to keep your plan.
            </EmptyDescription>
          </EmptyHeader>
          <EmptyContent>
            <Button>Contact billing</Button>
            <Button variant="accent">Update card</Button>
          </EmptyContent>
        </Empty>
      </Card>
    </div>
  );
}
```

## Accessibility

An illustration is decoration: it renders `aria-hidden="true"`, and the title and description of the empty state say what it means. Where the picture itself carries meaning, pass an `aria-label`: the illustration then renders `role="img"` with that name.

```tsx
<Illustration aria-label="A payment failed" type="credit-card">
  <WarningCircleIcon aria-hidden="true" />
</Illustration>
```

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| Illustration.type | cloud \| box \| credit-card \| documents | required | The drawing: a cloud, a box, a credit card or a few documents, on a soft disc. |
| Illustration.size | sm \| md \| lg | lg | The height: 120, 128 or 160 px. The width follows the drawing's proportions. In an Empty State's media, the media sets the height. |
| Illustration.children | ReactNode | unset | The glyph in the frosted disc over the drawing, such as an icon with aria-hidden. Without it, no disc renders. |
| Illustration.aria-label | string | unset | Names the drawing and makes it an image (role img). Without it, the illustration is hidden from assistive technology. |
| Illustration.className | string | unset | Classes for the illustration. |

`IllustrationProps` extends the props of a `div`, except `title` and `children`, which is the glyph here. The root carries `data-slot="illustration"`, `data-type` and `data-size`; the drawing is an `svg` with `data-slot="illustration-svg"`, and the disc of the glyph a span with `data-slot="illustration-badge"`. The types `IllustrationType` and `IllustrationSize` are exported.

[Read the installed source](/source/illustration).

## Usage notes

Use an illustration for an empty state that fills a page, a panel or a large card, such as no files uploaded yet or a failed payment, with one illustration per view. For a compact empty state, such as one in a table or a popover, a [Featured Icon](/docs/components/featured-icon/) takes less room.

The words carry the message. Write the title and the description of the empty state so that they say everything without the picture, and keep the illustration decorative unless the picture adds something the text does not.
