# Empty

Use the Empty component to display an empty state.

Source: https://webjs.dev/ui/docs/components/empty

```ts
import { html, svg } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
  emptyClass, emptyHeaderClass, emptyMediaClass, emptyTitleClass,
  emptyDescriptionClass, emptyContentClass,
} from '#components/ui/empty.ts';
import { ArrowUpRightIcon } from '#lib/ui/lucide.ts';

// Tabler's folder-code icon, the one shadcn's demo imports from
// @tabler/icons-react.
const IconFolderCode = () =>
  svg`<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" class="tabler-icon tabler-icon-folder-code"><path d="M11 19h-6a2 2 0 0 1 -2 -2v-11a2 2 0 0 1 2 -2h4l3 3h7a2 2 0 0 1 2 2v4"></path><path d="M20 21l2 -2l-2 -2"></path><path d="M17 17l-2 2l2 2"></path></svg>`;

export default function EmptyDemo() {
  return html`
    <div data-slot="empty" class=${emptyClass()}>
      <div data-slot="empty-header" class=${emptyHeaderClass()}>
        <div data-slot="empty-icon" data-variant="icon" class=${emptyMediaClass({ variant: 'icon' })}>
          ${IconFolderCode()}
        </div>
        <div data-slot="empty-title" class=${emptyTitleClass()}>No Projects Yet</div>
        <div data-slot="empty-description" class=${emptyDescriptionClass()}>
          You haven&apos;t created any projects yet. Get started by creating
          your first project.
        </div>
      </div>
      <div data-slot="empty-content" class=${cn(emptyContentClass(), 'flex-row justify-center gap-2')}>
        <button type="button" data-slot="button" data-variant="default" data-size="default" class=${buttonClass()}>Create Project</button>
        <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>Import Project</button>
      </div>
      <a href="#" data-slot="button" data-variant="link" data-size="sm" class=${cn(buttonClass({ variant: 'link', size: 'sm' }), 'text-muted-foreground')}>
        Learn More ${ArrowUpRightIcon()}
      </a>
    </div>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add empty
```

### Copy and paste the following code into your project.

````ts title="components/ui/empty.ts"
/**
 * Empty: the empty state for a list, table, search result, or any region with
 * nothing to show yet. Tier-1 class helpers; compose with `<div>` (or a heading
 * and paragraph) for each subpart.
 *
 * shadcn parity:
 *   Empty                               → emptyClass()
 *   EmptyHeader                         → emptyHeaderClass()
 *   EmptyMedia (variant: default | icon) → emptyMediaClass({ variant })
 *   EmptyTitle                          → emptyTitleClass()
 *   EmptyDescription                    → emptyDescriptionClass()
 *   EmptyContent                        → emptyContentClass()
 *
 * The root carries `border-dashed` but no border width, exactly as shadcn
 * does, so it renders borderless by default. Add `border` beside it for the
 * dashed outline: `class=${cn(emptyClass(), 'border')}`.
 *
 * Design tokens used: --muted, --foreground, --muted-foreground, --primary,
 * --border.
 *
 * A11y (required for accessible output):
 *   Use a REAL HEADING for `emptyTitleClass()`, at the level the surrounding
 *   document wants (`<h2>` under the page `<h1>`, `<h3>` inside a section). The
 *   empty state usually replaces the list a heading already introduces, so the
 *   title is often a level below it.
 *   The media is decorative: put `aria-hidden="true"` on the icon or
 *   illustration, since the title already says what is missing.
 *   The action in `emptyContentClass()` is a real `<a href>` (navigates, e.g.
 *   to the create page) or a real `<button>` (acts in place). A create action
 *   that is a form submit keeps working without JavaScript.
 *   When the empty state appears in response to a user action (a search or a
 *   filter that matched nothing), put `role="status"` on the root so the change
 *   is announced; a page that simply loads empty needs no role.
 *
 * @example
 * ```html
 * <div class=${cn(emptyClass(), 'border')}>
 *   <div class=${emptyHeaderClass()}>
 *     <div class=${emptyMediaClass({ variant: 'icon' })}>
 *       <svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M22 12h-6l-2 3h-4l-2-3H2"/><path d="M5.45 5.11 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z"/></svg>
 *     </div>
 *     <h3 class=${emptyTitleClass()}>No projects yet</h3>
 *     <p class=${emptyDescriptionClass()}>Create your first project to get started.</p>
 *   </div>
 *   <div class=${emptyContentClass()}>
 *     <a class=${buttonClass()} href="/projects/new">Create project</a>
 *   </div>
 * </div>
 * ```
 */

const MEDIA_BASE =
  'mb-2 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:shrink-0';

const MEDIA_VARIANTS = {
  default: 'bg-transparent',
  icon: "flex size-10 shrink-0 items-center justify-center rounded-lg bg-muted text-foreground [&_svg:not([class*='size-'])]:size-6",
} as const;

export type EmptyMediaVariant = keyof typeof MEDIA_VARIANTS;

/** Empty root: centred column with generous padding. Add `border` for the dashed outline. */
export const emptyClass = (): string =>
  'gap-6 rounded-lg border-dashed p-6 md:p-12 flex w-full min-w-0 flex-1 flex-col items-center justify-center text-center text-balance';

/** Empty header: groups the media, title, and description. */
export const emptyHeaderClass = (): string =>
  'gap-2 text-center flex max-w-sm flex-col items-center';

/**
 * Empty media: the icon or illustration above the title. `icon` puts the icon
 * on a muted tile; `default` leaves it bare (for an avatar or an illustration).
 * Set `data-variant="<variant>"` on the same element for shadcn parity.
 */
export function emptyMediaClass(opts: { variant?: EmptyMediaVariant } = {}): string {
  return MEDIA_BASE + ' ' + MEDIA_VARIANTS[opts.variant ?? 'default'];
}

/** Empty title: what is missing, in a few words. */
export const emptyTitleClass = (): string => 'text-lg font-medium tracking-tight';

/** Empty description: the muted line under the title, saying what to do next. */
export const emptyDescriptionClass = (): string =>
  'text-sm/relaxed text-muted-foreground [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary';

/** Empty content: the row for the action button(s) or a small form. */
export const emptyContentClass = (): string =>
  'gap-4 text-sm flex w-full max-w-sm min-w-0 flex-col items-center text-balance';
````

### Update the import paths to match your project setup.

## Usage

```ts
import {
  emptyClass,
  emptyContentClass,
  emptyDescriptionClass,
  emptyHeaderClass,
  emptyMediaClass,
  emptyTitleClass,
} from '#components/ui/empty.ts';
```

```ts
<div data-slot="empty" class=${emptyClass()}>
  <div data-slot="empty-header" class=${emptyHeaderClass()}>
    <div data-slot="empty-icon" data-variant="icon" class=${emptyMediaClass({ variant: 'icon' })}>
      <svg aria-hidden="true">...</svg>
    </div>
    <h3 data-slot="empty-title" class=${emptyTitleClass()}>No data</h3>
    <p data-slot="empty-description" class=${emptyDescriptionClass()}>No data found</p>
  </div>
  <div data-slot="empty-content" class=${emptyContentClass()}>
    <button class=${buttonClass()}>Add data</button>
  </div>
</div>
```

## Composition

Use the following composition to build an empty state:

```text
emptyClass
├── emptyHeaderClass
│   ├── emptyMediaClass
│   ├── emptyTitleClass
│   └── emptyDescriptionClass
└── emptyContentClass
```

## Outline

Use the `border` utility class to create an outline empty state.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
  emptyClass, emptyHeaderClass, emptyMediaClass, emptyTitleClass,
  emptyDescriptionClass, emptyContentClass,
} from '#components/ui/empty.ts';
import { IconCloud } from '#lib/ui/tabler.ts';

export default function EmptyOutline() {
  return html`
    <div data-slot="empty" class=${cn(emptyClass(), 'border border-dashed')}>
      <div data-slot="empty-header" class=${emptyHeaderClass()}>
        <div data-slot="empty-icon" data-variant="icon" class=${emptyMediaClass({ variant: 'icon' })}>
          ${IconCloud()}
        </div>
        <div data-slot="empty-title" class=${emptyTitleClass()}>Cloud Storage Empty</div>
        <div data-slot="empty-description" class=${emptyDescriptionClass()}>
          Upload files to your cloud storage to access them anywhere.
        </div>
      </div>
      <div data-slot="empty-content" class=${emptyContentClass()}>
        <button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${buttonClass({ variant: 'outline', size: 'sm' })}>
          Upload Files
        </button>
      </div>
    </div>
  `;
}
```

## Background

Use the `bg-*` and `bg-gradient-*` utilities to add a background to the empty state.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
  emptyClass, emptyHeaderClass, emptyMediaClass, emptyTitleClass,
  emptyDescriptionClass, emptyContentClass,
} from '#components/ui/empty.ts';
import { IconBell } from '#lib/ui/tabler.ts';
import { RefreshCcwIcon } from '#lib/ui/lucide.ts';

export default function EmptyMuted() {
  return html`
    <div data-slot="empty" class=${cn(emptyClass(), 'h-full bg-muted/30')}>
      <div data-slot="empty-header" class=${emptyHeaderClass()}>
        <div data-slot="empty-icon" data-variant="icon" class=${emptyMediaClass({ variant: 'icon' })}>
          ${IconBell()}
        </div>
        <div data-slot="empty-title" class=${emptyTitleClass()}>No Notifications</div>
        <div data-slot="empty-description" class=${cn(emptyDescriptionClass(), 'max-w-xs text-pretty')}>
          You&apos;re all caught up. New notifications will appear here.
        </div>
      </div>
      <div data-slot="empty-content" class=${emptyContentClass()}>
        <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>
          ${RefreshCcwIcon()}
          Refresh
        </button>
      </div>
    </div>
  `;
}
```

## Avatar

Use `emptyMediaClass()` to display an avatar in the empty state.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { avatarClass, avatarImageClass, avatarFallbackClass } from '#components/ui/avatar.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
  emptyClass, emptyHeaderClass, emptyMediaClass, emptyTitleClass,
  emptyDescriptionClass, emptyContentClass,
} from '#components/ui/empty.ts';

export default function EmptyAvatar() {
  return html`
    <div data-slot="empty" class=${emptyClass()}>
      <div data-slot="empty-header" class=${emptyHeaderClass()}>
        <div data-slot="empty-icon" data-variant="default" class=${emptyMediaClass({ variant: 'default' })}>
          <span data-slot="avatar" data-size="default" class=${cn(avatarClass(), 'size-12')}>
            <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="" class=${cn(avatarImageClass(), 'grayscale')}>
            <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
          </span>
        </div>
        <div data-slot="empty-title" class=${emptyTitleClass()}>User Offline</div>
        <div data-slot="empty-description" class=${emptyDescriptionClass()}>
          This user is currently offline. You can leave a message to notify them
          or try again later.
        </div>
      </div>
      <div data-slot="empty-content" class=${emptyContentClass()}>
        <button type="button" data-slot="button" data-variant="default" data-size="sm" class=${buttonClass({ size: 'sm' })}>Leave Message</button>
      </div>
    </div>
  `;
}
```

## Avatar Group

Use `emptyMediaClass()` to display an avatar group in the empty state.

```ts
import { html } from '@webjsdev/core';
import { avatarClass, avatarImageClass, avatarFallbackClass } from '#components/ui/avatar.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
  emptyClass, emptyHeaderClass, emptyMediaClass, emptyTitleClass,
  emptyDescriptionClass, emptyContentClass,
} from '#components/ui/empty.ts';
import { PlusIcon } from '#lib/ui/lucide.ts';

export default function EmptyAvatarGroup() {
  return html`
    <div data-slot="empty" class=${emptyClass()}>
      <div data-slot="empty-header" class=${emptyHeaderClass()}>
        <div data-slot="empty-icon" data-variant="default" class=${emptyMediaClass()}>
          <div class="flex -space-x-2 *:data-[slot=avatar]:size-12 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background *:data-[slot=avatar]:grayscale">
            <span data-slot="avatar" data-size="default" class=${avatarClass()}>
              <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${avatarImageClass()}>
              <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
            </span>
            <span data-slot="avatar" data-size="default" class=${avatarClass()}>
              <img data-slot="avatar-image" src="https://github.com/maxleiter.png" alt="@maxleiter" class=${avatarImageClass()}>
              <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>LR</span>
            </span>
            <span data-slot="avatar" data-size="default" class=${avatarClass()}>
              <img data-slot="avatar-image" src="https://github.com/evilrabbit.png" alt="@evilrabbit" class=${avatarImageClass()}>
              <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>ER</span>
            </span>
          </div>
        </div>
        <div data-slot="empty-title" class=${emptyTitleClass()}>No Team Members</div>
        <div data-slot="empty-description" class=${emptyDescriptionClass()}>
          Invite your team to collaborate on this project.
        </div>
      </div>
      <div data-slot="empty-content" class=${emptyContentClass()}>
        <button type="button" data-slot="button" data-variant="default" data-size="sm" class=${buttonClass({ size: 'sm' })}>
          ${PlusIcon()}
          Invite Members
        </button>
      </div>
    </div>
  `;
}
```

## InputGroup

You can add an [Input Group](https://webjs.dev/ui/docs/components/input-group) to the element with `emptyContentClass()`.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  emptyClass, emptyHeaderClass, emptyTitleClass, emptyDescriptionClass, emptyContentClass,
} from '#components/ui/empty.ts';
import {
  inputGroupClass, inputGroupAddonClass, inputGroupInputClass,
} from '#components/ui/input-group.ts';
import { kbdClass } from '#components/ui/kbd.ts';
import { SearchIcon } from '#lib/ui/lucide.ts';

export default function EmptyInputGroup() {
  return html`
    <div data-slot="empty" class=${emptyClass()}>
      <div data-slot="empty-header" class=${emptyHeaderClass()}>
        <div data-slot="empty-title" class=${emptyTitleClass()}>404 - Not Found</div>
        <div data-slot="empty-description" class=${emptyDescriptionClass()}>
          The page you&apos;re looking for doesn&apos;t exist. Try searching for
          what you need below.
        </div>
      </div>
      <div data-slot="empty-content" class=${emptyContentClass()}>
        <div data-slot="input-group" role="group" class=${cn(inputGroupClass(), 'sm:w-3/4')}>
          <input data-slot="input-group-control" id="empty-input-group-search" placeholder="Try searching for pages..." aria-label="Search pages" class=${inputGroupInputClass()}>
          <label data-slot="input-group-addon" data-align="inline-start" for="empty-input-group-search" class=${inputGroupAddonClass()}>
            ${SearchIcon()}
          </label>
          <label data-slot="input-group-addon" data-align="inline-end" for="empty-input-group-search" class=${inputGroupAddonClass({ align: 'inline-end' })}>
            <kbd data-slot="kbd" class=${kbdClass()}>/</kbd>
          </label>
        </div>
        <div data-slot="empty-description" class=${emptyDescriptionClass()}>
          Need help? <a href="#">Contact support</a>
        </div>
      </div>
    </div>
  `;
}
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
  emptyClass, emptyHeaderClass, emptyMediaClass, emptyTitleClass,
  emptyDescriptionClass, emptyContentClass,
} from '#components/ui/empty.ts';
import { IconFolderCode } from '#lib/ui/tabler.ts';
import { ArrowUpRightIcon } from '#lib/ui/lucide.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      title: 'No Projects Yet',
      description:
        "You haven't created any projects yet. Get started by creating your first project.",
      createProject: 'Create Project',
      importProject: 'Import Project',
      learnMore: 'Learn More',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      title: 'لا توجد مشاريع بعد',
      description: 'لم تقم بإنشاء أي مشاريع بعد. ابدأ بإنشاء مشروعك الأول.',
      createProject: 'إنشاء مشروع',
      importProject: 'استيراد مشروع',
      learnMore: 'تعرف على المزيد',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      title: 'אין פרויקטים עדיין',
      description:
        'עדיין לא יצרת פרויקטים. התחל על ידי יצירת הפרויקט הראשון שלך.',
      createProject: 'צור פרויקט',
      importProject: 'ייבא פרויקט',
      learnMore: 'למד עוד',
    },
  },
};

export default function EmptyRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <div data-slot="empty" dir=${dir} lang=${lang} class=${emptyClass()}>
      <div data-slot="empty-header" class=${emptyHeaderClass()}>
        <div data-slot="empty-icon" data-variant="icon" class=${emptyMediaClass({ variant: 'icon' })}>
          ${IconFolderCode()}
        </div>
        <div data-slot="empty-title" class=${emptyTitleClass()}>${t.title}</div>
        <div data-slot="empty-description" class=${emptyDescriptionClass()}>${t.description}</div>
      </div>
      <div data-slot="empty-content" class=${cn(emptyContentClass(), 'flex-row justify-center gap-2')}>
        <button type="button" data-slot="button" data-variant="default" data-size="default" class=${buttonClass()}>${t.createProject}</button>
        <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>${t.importProject}</button>
      </div>
      <a href="#" data-slot="button" data-variant="link" data-size="sm" class=${cn(buttonClass({ variant: 'link', size: 'sm' }), 'text-muted-foreground')}>
        ${t.learnMore} ${ArrowUpRightIcon('rtl:rotate-270')}
      </a>
    </div>
  `;
}
```

## API Reference

Every part is a class helper you put on a native element. None takes options except `emptyMediaClass()`; merge your own classes with `cn()`.

### emptyClass

The root of the empty state. Wraps the header and the content. It carries `border-dashed` but no border width, so it renders borderless until you add `border`. When the empty state appears in response to a search or a filter, put `role="status"` on it so the change is announced.

```ts
<div data-slot="empty" class=${emptyClass()}>
  <div data-slot="empty-header" class=${emptyHeaderClass()}>...</div>
  <div data-slot="empty-content" class=${emptyContentClass()}>...</div>
</div>
```

### emptyHeaderClass

Wraps the empty media, title, and description.

```ts
<div data-slot="empty-header" class=${emptyHeaderClass()}>
  <div data-slot="empty-icon" class=${emptyMediaClass()}>...</div>
  <h3 data-slot="empty-title" class=${emptyTitleClass()}>...</h3>
  <p data-slot="empty-description" class=${emptyDescriptionClass()}>...</p>
</div>
```

### emptyMediaClass

Displays the media of the empty state, such as an icon or an image. You can also use it to display other components such as an avatar. Set `data-variant` to the same variant. The media is decorative, so mark the icon `aria-hidden="true"`.

| Option | Type | Default |
| --- | --- | --- |
| `variant` | `"default" \| "icon"` | `"default"` |

```ts
<div data-slot="empty-icon" data-variant="icon" class=${emptyMediaClass({ variant: 'icon' })}>
  <svg aria-hidden="true">...</svg>
</div>
```

```ts
<div data-slot="empty-icon" data-variant="default" class=${emptyMediaClass()}>
  <span data-slot="avatar" class=${avatarClass()}>
    <img data-slot="avatar-image" src="..." alt="" class=${avatarImageClass()}>
    <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>CN</span>
  </span>
</div>
```

### emptyTitleClass

Displays the title of the empty state. Put it on a real heading, at the level the surrounding document wants.

```ts
<h3 data-slot="empty-title" class=${emptyTitleClass()}>No data</h3>
```

### emptyDescriptionClass

Displays the description of the empty state. A link inside it is underlined.

```ts
<p data-slot="empty-description" class=${emptyDescriptionClass()}>You do not have any notifications.</p>
```

### emptyContentClass

Displays the content of the empty state, such as a button, an input or a link.

```ts
<div data-slot="empty-content" class=${emptyContentClass()}>
  <button class=${buttonClass()}>Add Project</button>
</div>
```
