Siteplane UI

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.

Markdown
"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

pnpm dlx shadcn@4.18.0 add @siteplane/illustration

Complete the one-time setup first. Registry JSON lists source files and dependencies.

For this page’s examples, also install:

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

Usage

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.

"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.

"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.

"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 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.

Your payment failed
We could not charge the card ending in 4242. Update your payment method to keep your plan.
"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.

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

API reference

Component properties
PropTypeDefaultDescription
Illustration.typecloud | box | credit-card | documentsrequiredThe drawing: a cloud, a box, a credit card or a few documents, on a soft disc.
Illustration.sizesm | md | lglgThe 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.childrenReactNodeunsetThe glyph in the frosted disc over the drawing, such as an icon with aria-hidden. Without it, no disc renders.
Illustration.aria-labelstringunsetNames the drawing and makes it an image (role img). Without it, the illustration is hidden from assistive technology.
Illustration.classNamestringunsetClasses 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.

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 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.