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.
Installation
pnpm dlx shadcn@4.18.0 add @siteplane/illustrationComplete 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-stateUsage
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.
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.
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.
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.
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
| Prop | Type | Default | Description |
|---|---|---|---|
Illustration. | cloud | box | credit-card | documents | required | The drawing: a cloud, a box, a credit card or a few documents, on a soft disc. |
Illustration. | 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. | ReactNode | unset | The glyph in the frosted disc over the drawing, such as an icon with aria-hidden. Without it, no disc renders. |
Illustration. | string | unset | Names the drawing and makes it an image (role img). Without it, the illustration is hidden from assistive technology. |
Illustration. | 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.
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.