Empty

A centered empty-state layout for when there’s nothing to show — a list with no rows, a search with no matches, or a screen the user has fully cleared. Reach for it instead of leaving a blank panel: a glyph, a one-line title, and a sentence of guidance turn dead space into a next step.

Compose the parts: Empty (the centered, dashed-border container), EmptyHeader (groups the media + text, capped at max-w-sm), EmptyMedia (the icon tile), EmptyTitle, EmptyDescription, and EmptyContent (where actions live). Every part is a vertical Stack under the hood, so gap, align, and justify are props — no className wrestling.

Basic

The full pattern: an icon media tile, a title, a description, and a call-to-action in EmptyContent. This is the “no shipments yet” first-run screen.

No shipments yet

Once you buy a label or hand off an order to a carrier, it'll show up here.

import {
  Button,
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@vesyl/ui-next";
import { InboxIcon, TruckIcon } from "lucide-react";

export default function EmptyBasic() {
  return (
    <Empty className="max-w-md">
      <EmptyHeader>
        <EmptyMedia variant="icon">
          <InboxIcon />
        </EmptyMedia>
        <EmptyTitle>No shipments yet</EmptyTitle>
        <EmptyDescription>
          Once you buy a label or hand off an order to a carrier, it'll show up here.
        </EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        <Button>
          <TruckIcon />
          Quick ship
        </Button>
      </EmptyContent>
    </Empty>
  );
}

Without an action

Drop EmptyContent when there’s nothing for the user to do — an error or informational state. Just the EmptyHeader (media + title + description) stands on its own.

Couldn't load your account

We hit an error fetching your profile. Refresh the page or try again in a moment.

import {
  Empty,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@vesyl/ui-next";
import { AlertTriangleIcon } from "lucide-react";

export default function EmptyNoAction() {
  return (
    <Empty className="max-w-md">
      <EmptyHeader>
        <EmptyMedia variant="icon">
          <AlertTriangleIcon />
        </EmptyMedia>
        <EmptyTitle>Couldn't load your account</EmptyTitle>
        <EmptyDescription>
          We hit an error fetching your profile. Refresh the page or try again in a moment.
        </EmptyDescription>
      </EmptyHeader>
    </Empty>
  );
}

No results

A search or filter that returned nothing. EmptyMedia variant="icon-muted" reads quieter than a first-run prompt, and the action resets the query rather than starting something new.

No results

No orders match "1Z999AA10123456784". Check the tracking number or clear your filters.

import {
  Button,
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@vesyl/ui-next";
import { SearchIcon } from "lucide-react";

export default function EmptySearch() {
  return (
    <Empty className="max-w-md">
      <EmptyHeader>
        <EmptyMedia variant="icon-muted">
          <SearchIcon />
        </EmptyMedia>
        <EmptyTitle>No results</EmptyTitle>
        <EmptyDescription>
          No orders match "1Z999AA10123456784". Check the tracking number or clear your filters.
        </EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        <Button variant="outline">Clear filters</Button>
      </EmptyContent>
    </Empty>
  );
}

Resolved state

EmptyMedia variant="icon-success" tints the tile green for an “all caught up” outcome — a queue the user has emptied on purpose, not a screen that’s empty because nothing exists yet.

All caught up

Every order in this batch has been picked, packed, and shipped. Nothing left to do.

import {
  Empty,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@vesyl/ui-next";
import { CheckIcon } from "lucide-react";

export default function EmptySuccess() {
  return (
    <Empty className="max-w-md">
      <EmptyHeader>
        <EmptyMedia variant="icon-success">
          <CheckIcon />
        </EmptyMedia>
        <EmptyTitle>All caught up</EmptyTitle>
        <EmptyDescription>
          Every order in this batch has been picked, packed, and shipped. Nothing left to do.
        </EmptyDescription>
      </EmptyHeader>
    </Empty>
  );
}

Media variants

EmptyMedia ships four variants. default is a bare, unstyled wrapper; the three icon-* variants render a 48px tile that auto-sizes an unsized leading svg. Pick by tone: icon for neutral, icon-muted for low-emphasis (no-results), icon-success for resolved.

icon

Solid muted tile, rounded corners.

icon-muted

Muted circle, lower-contrast glyph.

icon-success

Green tile for resolved states.

import {
  Empty,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
  HStack,
} from "@vesyl/ui-next";
import { CheckIcon, PackageIcon, SearchIcon } from "lucide-react";

export default function EmptyMediaVariants() {
  return (
    <HStack gap={4} className="flex-wrap items-stretch justify-center">
      <Empty className="max-w-xs">
        <EmptyHeader>
          <EmptyMedia variant="icon">
            <PackageIcon />
          </EmptyMedia>
          <EmptyTitle>icon</EmptyTitle>
          <EmptyDescription>Solid muted tile, rounded corners.</EmptyDescription>
        </EmptyHeader>
      </Empty>
      <Empty className="max-w-xs">
        <EmptyHeader>
          <EmptyMedia variant="icon-muted">
            <SearchIcon />
          </EmptyMedia>
          <EmptyTitle>icon-muted</EmptyTitle>
          <EmptyDescription>Muted circle, lower-contrast glyph.</EmptyDescription>
        </EmptyHeader>
      </Empty>
      <Empty className="max-w-xs">
        <EmptyHeader>
          <EmptyMedia variant="icon-success">
            <CheckIcon />
          </EmptyMedia>
          <EmptyTitle>icon-success</EmptyTitle>
          <EmptyDescription>Green tile for resolved states.</EmptyDescription>
        </EmptyHeader>
      </Empty>
    </HStack>
  );
}

Reference

Empty

The centered container. Extends VStack props (minus direction); defaults to gap={4}, centered on both axes, with a dashed border, p-12, and balanced center text.

Prop	Type	Default	Description
`gap`	`number`	`4`	Vertical gap between children
`align`	`"start" \| "center" \| "end" \| "stretch"`	`"center"`	Cross-axis alignment
`justify`	`"start" \| "center" \| "end" \| "between"`	`"center"`	Main-axis alignment
`className`	`string`	—	Merged onto the container

EmptyHeader

Groups the media, title, and description. Extends VStack props (minus direction); capped at max-w-sm, gap={2}, centered.

Prop	Type	Default	Description
`gap`	`number`	`2`	Vertical gap between children
`align`	`string`	`"center"`	Cross-axis alignment
`className`	`string`	—	Merged onto the header

EmptyMedia

The icon tile. Extends <div> props.

Prop	Type	Default	Description
`variant`	`"default" \| "icon" \| "icon-muted" \| "icon-success"`	`"default"`	`default` is an unstyled wrapper; `icon-*` render a 48px tile and auto-size an unsized leading `svg`
`className`	`string`	—	Merged onto the tile

EmptyTitle

The heading line (text-lg font-medium). Extends <div> props.

Prop	Type	Default	Description
`className`	`string`	—	Merged onto the title

EmptyDescription

The supporting copy (text-sm muted). Nested <a> elements get underline + hover styling for free. Extends <p> props.

Prop	Type	Default	Description
`className`	`string`	—	Merged onto the description

EmptyContent

Holds the action(s) below the header. Extends VStack props (minus direction); gap={4}, centered, capped at max-w-sm. Wrap multiple buttons in an HStack to lay them out in a row.

Prop	Type	Default	Description
`gap`	`number`	`4`	Vertical gap between children
`align`	`string`	`"center"`	Cross-axis alignment
`className`	`string`	—	Merged onto the content