Skip to content
Shaken UI
Sign in

Empty

Save

An empty state with an icon or illustration slot, a title, a description, and actions, plus a compact row variant for tables and lists.

Category
Feedback
Version
0.1.0
Frameworks
Next.js, Vite + React
Styling
Tailwind CSS v4

Preview

Empty preview

No deployments yet

Push to the main branch or deploy from the command line. Every build shows up here with its logs.

API keysLast used

No API keys

Create a key to call the API from your servers.

Installation

npx @shakenui/cli add empty

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add empty --dry-run

Usage

empty-example.tsx
import { Button } from "@/components/shaken/ui/button";
import { Empty, EmptyActions, EmptyDescription, EmptyMedia, EmptyTitle } from "@/components/shaken/ui/empty";

function CubeIcon() {
  return (
    <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round">
      <path d="M10 2.25 17 6.1v7.8l-7 3.85-7-3.85V6.1Z" />
      <path d="M3 6.1 10 10l7-3.9M10 10v7.75" />
    </svg>
  );
}

function KeyIcon() {
  return (
    <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round">
      <circle cx="6.5" cy="13.5" r="3.75" />
      <path d="m9.2 10.8 7.8-7.8M14.8 5.2l2.2 2.2M12.2 7.8l1.8 1.8" />
    </svg>
  );
}

export default function EmptyExample() {
  return (
    <div className="grid w-full max-w-xl gap-6">
      <div className="rounded-xl border border-zinc-950/10 dark:border-white/10">
        <Empty>
          <EmptyMedia>
            <CubeIcon />
          </EmptyMedia>
          <EmptyTitle>No deployments yet</EmptyTitle>
          <EmptyDescription>
            Push to the main branch or deploy from the command line. Every build shows up here with its logs.
          </EmptyDescription>
          <EmptyActions>
            <Button size="sm">Import repository</Button>
            <Button size="sm" variant="secondary">
              Read the CLI guide
            </Button>
          </EmptyActions>
        </Empty>
      </div>

      <div className="overflow-hidden rounded-xl border border-zinc-950/10 dark:border-white/10">
        <div className="grid grid-cols-[1fr_auto] border-b border-zinc-950/[0.07] px-4 py-2.5 text-xs font-medium text-zinc-500 dark:border-white/[0.08]">
          <span>API keys</span>
          <span>Last used</span>
        </div>
        <Empty size="compact">
          <EmptyMedia>
            <KeyIcon />
          </EmptyMedia>
          <EmptyTitle>No API keys</EmptyTitle>
          <EmptyDescription>Create a key to call the API from your servers.</EmptyDescription>
          <EmptyActions>
            <Button size="sm" variant="secondary">
              Create key
            </Button>
          </EmptyActions>
        </Empty>
      </div>
    </div>
  );
}

API

PropTypeDefaultDescription
size"default" | "compact""default"default is a centered block for pages and panels; compact is one left-aligned row for table bodies, lists, and sidebars, with actions on the right from the sm breakpoint.
borderedbooleanfalseDraws a dashed hairline around the empty state, for drop zones and panels without their own border.
EmptyMedia variant"icon" | "illustration""icon"icon places a 20px icon on a hairline tile over a still dot field; illustration is a bare slot for your own SVG or image.
EmptyTitle level2 | 3 | 43Heading level of the title, so it fits the page outline.

Accessibility

  • The title is a real heading (h3 by default, adjustable with level), so the empty state appears in the page outline.
  • EmptyMedia is aria-hidden: the icon and dot field are decorative and the title carries the meaning.
  • Actions are your own buttons or links and keep their native keyboard behavior and focus rings.
  • No motion; the dot field is a still background.

Files

Installed into src/components/shaken, or components/shaken when the project has no src directory.

  • src/components/shaken/ui/empty.tsxempty
  • Also installs button@0.2.1registry dependency
  • npm packages: noneReact and Tailwind CSS v4 required

Source

The exact source the CLI installs, from /r/items/react/empty/0.1.0.json.

ui/empty.tsxShow
ui/empty.tsx
import type { ComponentProps } from "react";

function cx(...classes: (string | false | null | undefined)[]) {
  return classes.filter(Boolean).join(" ");
}

export interface EmptyProps extends ComponentProps<"div"> {
  /**
   * `default` is a centered block for pages and panels. `compact` is a single left-aligned row
   * for table bodies, lists, and sidebars.
   */
  size?: "default" | "compact";
  /** Draws a dashed hairline around it, for drop zones and empty panels without their own border. */
  bordered?: boolean;
}

/**
 * An empty state: what is missing, why, and what to do next.
 * Compose it with `EmptyMedia`, `EmptyTitle`, `EmptyDescription`, and `EmptyActions`.
 */
export function Empty({ size = "default", bordered = false, className, ...props }: EmptyProps) {
  const compact = size === "compact";
  return (
    <div
      data-size={size}
      className={cx(
        "group/empty text-zinc-950 dark:text-white",
        compact
          ? "grid grid-cols-[auto_minmax(0,1fr)] items-start gap-x-3 gap-y-0.5 px-4 py-4 text-left sm:items-center sm:has-[>[data-slot=empty-actions]]:grid-cols-[auto_minmax(0,1fr)_auto]"
          : "flex flex-col items-center gap-1.5 px-6 py-12 text-center",
        bordered && "rounded-xl border border-dashed border-zinc-950/15 dark:border-white/15",
        className,
      )}
      {...props}
    />
  );
}

export interface EmptyMediaProps extends ComponentProps<"div"> {
  /**
   * `icon` puts a 20px icon on a hairline tile over a faint dot field.
   * `illustration` is a bare slot for your own SVG or image.
   */
  variant?: "icon" | "illustration";
}

/** The icon or illustration slot. Decorative: it is hidden from screen readers. */
export function EmptyMedia({ variant = "icon", className, children, ...props }: EmptyMediaProps) {
  if (variant === "illustration") {
    return (
      <div
        aria-hidden="true"
        className={cx("mb-3 flex items-center justify-center group-data-[size=compact]/empty:row-span-2 group-data-[size=compact]/empty:mb-0", className)}
        {...props}
      >
        {children}
      </div>
    );
  }
  return (
    <div
      aria-hidden="true"
      className={cx(
        "relative isolate flex items-center justify-center",
        "mb-4 size-12 group-data-[size=compact]/empty:row-span-2 group-data-[size=compact]/empty:mb-0 group-data-[size=compact]/empty:size-9",
        className,
      )}
      {...props}
    >
      {/* A still field of dots fading out from the tile: the agent marks' dot language, at rest. */}
      <span
        className={cx(
          "pointer-events-none absolute -inset-10 -z-10 group-data-[size=compact]/empty:hidden",
          "bg-[radial-gradient(circle,rgb(9_9_11/0.16)_1px,transparent_1.2px)] bg-size-[10px_10px] bg-center",
          "dark:bg-[radial-gradient(circle,rgb(255_255_255/0.16)_1px,transparent_1.2px)]",
          "[mask-image:radial-gradient(closest-side,black,transparent)]",
        )}
      />
      <span
        className={cx(
          "flex size-full items-center justify-center rounded-xl border border-zinc-950/10 bg-white text-zinc-500 shadow-[0_1px_2px_rgb(0_0_0/0.05)]",
          "dark:border-white/12 dark:bg-black dark:text-zinc-400 dark:shadow-[inset_0_1px_0_rgb(255_255_255/0.07)]",
          "[&_svg]:size-5 group-data-[size=compact]/empty:rounded-lg group-data-[size=compact]/empty:[&_svg]:size-4",
        )}
      >
        {children}
      </span>
    </div>
  );
}

export interface EmptyTitleProps extends ComponentProps<"h3"> {
  /** Heading level. Defaults to 3; use the level that fits your page outline. */
  level?: 2 | 3 | 4;
}

/** What is empty, in plain words ("No deployments yet"). */
export function EmptyTitle({ level = 3, className, ...props }: EmptyTitleProps) {
  const Tag = `h${level}` as const;
  return (
    <Tag
      className={cx(
        "text-sm leading-5 font-semibold text-balance text-zinc-950 dark:text-white",
        "group-data-[size=compact]/empty:col-start-2 group-data-[size=compact]/empty:font-medium",
        className,
      )}
      {...props}
    />
  );
}

/** Why it is empty, or what will appear here once it is not. */
export function EmptyDescription({ className, ...props }: ComponentProps<"p">) {
  return (
    <p
      className={cx(
        "max-w-[42ch] text-sm leading-relaxed text-pretty text-zinc-600 dark:text-zinc-400",
        "group-data-[size=compact]/empty:col-start-2 group-data-[size=compact]/empty:max-w-none group-data-[size=compact]/empty:leading-5",
        "[&_a]:font-medium [&_a]:text-zinc-950 [&_a]:underline [&_a]:decoration-zinc-950/25 [&_a]:underline-offset-[3px] dark:[&_a]:text-white dark:[&_a]:decoration-white/30",
        className,
      )}
      {...props}
    />
  );
}

/** The next step: one primary action and at most one secondary one. */
export function EmptyActions({ className, ...props }: ComponentProps<"div">) {
  return (
    <div
      data-slot="empty-actions"
      className={cx(
        "mt-4 flex flex-wrap items-center justify-center gap-2",
        "group-data-[size=compact]/empty:col-start-2 group-data-[size=compact]/empty:mt-2 group-data-[size=compact]/empty:justify-start",
        "sm:group-data-[size=compact]/empty:col-start-3 sm:group-data-[size=compact]/empty:row-span-2 sm:group-data-[size=compact]/empty:row-start-1 sm:group-data-[size=compact]/empty:mt-0",
        className,
      )}
      {...props}
    />
  );
}