> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: EmptyState Component

## Article: EmptyState Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/layout/empty-state-component.md

## Article Content:

# EmptyState

_Components/Layout_

Interactive docs page: <https://wix-pages.com/design-system-documentation/#/component/emptystate>

## Overview

```jsx
<EmptyState
  image={
    <Image
      width="120px"
      height="120px"
      src="EmptyState_Stores.svg"
      transparent
    />
  }
  skin="page-no-border"
  title="Add your first product"
  subtitle="Start adding products so customers can shop your online store."
>
  <TextButton prefixIcon={<Icons.Add />}>Add Product</TextButton>
</EmptyState>;
```

An empty state is used when an app, page or section has no data to show.

### Do

- Show it when there's no data to display.
- Use it to give feedback when no search results are available.
- Use it when the page content fails to load or there's a technical error.
- Give an explanation and provide a next action.

### Don't

- Don't overwhelm the user with unnecessary content.
- Don't use it to promote new products or features. Use `<MarketingPageLayout/>` or `<MarketingLayout/>` instead.

### Feature examples

#### Structure

An empty state has 4 optional elements:

- `image`
- `title`
- `subtitle`
- `child container,` which can hold any component but is primarily reserved for CTA buttons.

```jsx
<EmptyState
  image={<Image width="120px" height="120px" />}
  title="Title"
  subtitle="Subtitle"
>
  <StorybookComponents.Placeholder>
    Child container
  </StorybookComponents.Placeholder>
</EmptyState>;
```

#### Align

`align` controls how all `EmptyState` content (title, subtitle, image, and actions) is aligned inside its container.

- `align="start"`: aligns content to the start (left in LTR)
- `align="center"`: centers content (default)
- `align="end"`: aligns content to the end (right in LTR)

```jsx
() => (
  <Box padding="20px" gap="20px" direction="vertical">
    <EmptyState
      align="start"
      title="No products yet"
      subtitle="Add your first product to get started."
    >
      <Button size="small">Add product</Button>
    </EmptyState>

    <EmptyState
      align="center"
      title="No products yet"
      subtitle="Add your first product to get started."
    >
      <Button size="small">Add product</Button>
    </EmptyState>

    <EmptyState
      align="end"
      title="No products yet"
      subtitle="Add your first product to get started."
    >
      <Button size="small">Add product</Button>
    </EmptyState>
  </Box>
);
```

#### Skin

Control an empty state's appearance with the `skin` property. There are 3 types:

- `page` is for full-page empty states where data is displayed in a full-width table or a card.
- `page-no-border` is for full-page empty states where data is displayed in an unknown layout.
- `section` is the default theme for layout elements such as cards, tables or modals.

```jsx
<StorybookComponents.Stack flexDirection="column" gap="48px">
  <EmptyState
    image={<Image width="120px" height="120px" />}
    skin="page"
    title="Page theme"
    subtitle="A subtitle guides users to their next step."
  />
  <EmptyState
    image={<Image width="120px" height="120px" />}
    skin="page-no-border"
    title="Page-no-border theme"
    subtitle="A subtitle guides users to their next step."
  />
  <EmptyState
    image={<Image width="120px" height="120px" />}
    skin="section"
    title="Section theme"
    subtitle="A subtitle guides users to their next step."
  />
</StorybookComponents.Stack>;
```

#### Children

Add 1 or more CTA buttons below the subtitle as child elements of the empty state.

Be sure to give the user clear next actions.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <EmptyState
    skin="page-no-border"
    title="Add your first product"
    subtitle="Start adding products so customers can shop your online store."
  >
    <StorybookComponents.Placeholder height="36px">
      Child elements
    </StorybookComponents.Placeholder>
  </EmptyState>
  <EmptyState
    skin="page-no-border"
    title="Add your first product"
    subtitle="Start adding products so customers can shop your online store."
  >
    <TextButton prefixIcon={<Icons.Add />}>Add Product</TextButton>
  </EmptyState>
  <EmptyState
    skin="page-no-border"
    title="Add your first product"
    subtitle="Start adding products so customers can shop your online store."
  >
    <StorybookComponents.Stack gap="16px">
      <TextButton prefixIcon={<Icons.Add />}>Add New Product</TextButton>
      <TextButton prefixIcon={<Icons.DownloadImport />}>
        Import Products
      </TextButton>
    </StorybookComponents.Stack>
  </EmptyState>
</StorybookComponents.Stack>;
```

### Common use case examples

#### No data on a page

Use the `page` or `page-no-border` skin to tell users what will appear on the page once there's data to display, and if relevant, what they can do to get started.

```jsx
<Page>
  <Page.Header
    title="Tasks and Reminders"
    actionsBar={<Button prefixIcon={<Icons.Add />}>Add Task</Button>}
  />
  <Page.Content>
    <EmptyState
      skin="page"
      image={
        <Image
          width="120px"
          height="120px"
          src="no_categories.png"
          transparent
        />
      }
      title="Add your first task"
      subtitle="Manage tasks and reminders for your site to get more done."
    >
      {<TextButton prefixIcon={<Icons.Add />}>Add Task</TextButton>}
    </EmptyState>
  </Page.Content>
</Page>;
```

#### No data in a card

Use the `section` skin empty state to tell users what will appear on the card once there's data to display and, if relevant, what they can do to get started.

Keep the design minimal and avoid using illustrations.

```jsx
<Page>
  <Page.Header
    title="New Category"
    actionsBar={
      <Box gap="SP2">
        <Button skin="inverted">Cancel</Button>
        <Button>Save</Button>
      </Box>
    }
    breadcrumbs={
      <Breadcrumbs
        activeId="3"
        items={[
          { id: '1', value: 'Categories' },
          { id: '2', value: 'New Category' },
        ]}
      />
    }
    showBackButton
    onBackClicked={() => {}}
  />
  <Page.Content>
    <Layout>
      <Cell>
        <Card>
          <Card.Header title="Category details" />
          <Card.Divider />
          <Card.Content>
            <Layout>
              <Cell span={4}>
                <FormField label="Category name" required>
                  <Input placeholder="e.g., Fitness Classes" />
                </FormField>
              </Cell>
            </Layout>
          </Card.Content>
        </Card>
      </Cell>
      <Cell>
        <Card>
          <Card.Header title="Services" />
          <Card.Divider />
          <Card.Content>
            <EmptyState
              title="Add services to this category"
              subtitle="Choose the services you want included in this category or create new ones."
            >
              <TextButton prefixIcon={<Icons.Add />}>Add Services</TextButton>
            </EmptyState>
          </Card.Content>
        </Card>
      </Cell>
      <Cell>
        <Page.Footer divider>
          <Page.Footer.End>
            <Box gap="SP2">
              <Button priority="secondary">Cancel</Button>
              <Button>Save</Button>
            </Box>
          </Page.Footer.End>
        </Page.Footer>
      </Cell>
    </Layout>
  </Page.Content>
</Page>;
```

#### No search results

Use an empty state when a search doesn't return any results. Explain what happened and what users can do next to adjust their search.

```jsx
() => {
  const [searchTerm, setSearchTerm] = React.useState('');
  const [display, setDisplay] = React.useState('none');
  const [records, setRecords] = React.useState([
    {
      name: `Ballet shoes`,
      SKU: 'BP063001',
      price: '$78',
      inventory: 16,
    },
    {
      name: `Chelsea boots`,
      SKU: 'BP063001',
      price: '$112',
      inventory: 32,
    },
    {
      name: `Desert boots`,
      SKU: 'BP063001',
      price: '$89',
      inventory: 23,
    },
    {
      name: `Platform shoes`,
      SKU: 'BP063001',
      price: '$45',
      inventory: 102,
    },
    {
      name: `Espadrilles`,
      SKU: 'BP063001',
      price: '$96',
      inventory: 4,
    },
    {
      name: `Moccasins`,
      SKU: 'BP063001',
      price: '$104',
      inventory: 45,
    },
  ]);

  const columns = [
    {
      title: 'Name',
      render: (row) => row.name,
      width: '30%',
    },
    {
      title: 'SKU',
      render: (row) => row.SKU,
      width: '20%',
    },
    {
      title: 'Price',
      render: (row) => row.price,
      width: '20%',
    },
    {
      title: 'Inventory',
      render: (row) => row.inventory,
      width: '20%',
    },
  ];

  const clearSearch = () => {
    setSearchTerm('');
  };

  const renderSearch = (expandable) => {
    return (
      <Search
        size="small"
        expandable={expandable}
        placeholder="Search..."
        onChange={(e) => {
          setSearchTerm(e.target.value);
        }}
        value={searchTerm}
        onClear={clearSearch}
      />
    );
  };

  const getFilteredData = () => {
    let data = records;

    if (searchTerm !== '') {
      data = data.filter((row) =>
        row.name.toUpperCase().includes(searchTerm.toUpperCase()),
      );
    }

    return data;
  };

  const filteredData = getFilteredData();

  const renderEmptyState = () => (
    <Table.EmptyState
      title="No results found"
      subtitle="No items matched your search. Try searching for something else."
      image={
        <Image
          width="120px"
          height="120px"
          transparent={true}
          src="EmptyState_Generic1.svg"
        />
      }
    >
      <TextButton onClick={clearSearch}>Clear Search</TextButton>
    </Table.EmptyState>
  );

  return (
    <Card>
      <Table data={filteredData} columns={columns} rowVerticalPadding="medium">
        <TableToolbar>
          <TableToolbar.ItemGroup position="start">
            <TableToolbar.Item>
              <Text size="small" weight="normal">
                6 products
              </Text>
            </TableToolbar.Item>
          </TableToolbar.ItemGroup>
          <TableToolbar.ItemGroup position="end">
            <TableToolbar.Item>{renderSearch(false)}</TableToolbar.Item>
          </TableToolbar.ItemGroup>
        </TableToolbar>
        {filteredData.length ? <Table.Titlebar /> : renderEmptyState()}
        <Table.Content titleBarVisible={false} />
      </Table>
    </Card>
  );
};
```

#### Failed to load

Let users know that their data failed to load. If possible, provide a next action.

```jsx
<Page>
  <Page.Header
    title="Website Widgets"
    subtitle="Widgets let you add features and functionality to your site."
  />
  <Page.Content>
    <EmptyState
      skin="page-no-border"
      image={
        <Image width="120px" src="EmptyState_ServerError.svg" transparent />
      }
      title="We couldn't load this page"
      subtitle="Looks like there was a technical issue on our end. Wait a few minutes and try again."
    >
      <TextButton prefixIcon={<Icons.Refresh />}>Try Again</TextButton>
    </EmptyState>
  </Page.Content>
</Page>;
```

#### App introduction

Use an empty state in the main tab of the app settings panel to give a brief introduction to the app.

Place the app icon and a short description at the top, and provide main actions to help users get started using the app.

```jsx
<SidePanel
  skin="floating"
  width="420px"
  onCloseButtonClick={() => {}}
  onHelpButtonClick={() => {}}
>
  <SidePanel.Header title="Blog" />
  <Box height="480px">
    <VerticalTabs size="small" activeTabId={0} onChange={() => {}}>
      <VerticalTabs.TabItem id={0}>Main</VerticalTabs.TabItem>
      <VerticalTabs.TabItem id={1}>Display</VerticalTabs.TabItem>
      <VerticalTabs.TabItem id={2}>Layout</VerticalTabs.TabItem>
      <VerticalTabs.TabItem id={3}>Design</VerticalTabs.TabItem>
      <VerticalTabs.TabItem id={4}>Support</VerticalTabs.TabItem>
    </VerticalTabs>
    <Divider direction="vertical" />
    <SidePanel.Content>
      <EmptyState
        theme="section"
        image={
          <Image
            width="120px"
            height="120px"
            src="onboarding_community.svg"
            transparent
          />
        }
        title="Blog feed"
        subtitle="Customize the layout and design of your blog feed, or create a post."
      >
        <Box gap="SP2" direction="vertical">
          <Button size="small">Create Post</Button>
          <Button size="small" priority="secondary">
            Manage Posts
          </Button>
        </Box>
      </EmptyState>
    </SidePanel.Content>
  </Box>
</SidePanel>;
```

## Code

```jsx
import { EmptyState } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "end" \| "start"` | `'center'` | Sets the alignment of all empty state contents within the component container. |
| `children` | `ReactNode` | — | Contains components rendered below the subtitle, e.g., `<Button/>` or `<TextButton/>` |
| `classNames` | `{ imageContainer?: string \| undefined; }` | — | Sets the empty state image bottom margin. If not specified, use the default padding defined in the CSS. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute to be used in the tests. |
| `image` | `string \| ReactElement \| null` | — | Contains the empty state image. Can be either a string representing the image URL, or a node to render. |
| `skin` | `"section" \| "page" \| "page-no-border"` | `'section'` | Sets the style skin for the empty state. |
| `subtitle` | `ReactNode` | — | Sets the content for the subtitle. |
| `theme` | `"section" \| "page" \| "page-no-border"` | — | Sets the style skin for the empty state. Used only when `skin` isn't set. |
| `title` | `ReactNode` | — | Sets the content for the title. |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { EmptyStateUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { EmptyStateTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { EmptyStateTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { EmptyStateTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `element` | Returns the element |
| `getTitleText` | Returns the text of the title |
| `getSubtitleText` | Returns the text of the subtitle |
| `hasTheme` | Returns true if the component was configured with given skin |
| `hasSkin` | Returns true if the component was configured with given skin |
| `getImageUrl` | Returns the URL of the image element (if persist) |
| `getImageContainerClassName` | — |
| `imageNodeExists` | Returns `true` if a node passed via the `image` prop exists |
| `childrenContentExists` | Returns `true` if children content exists |
| `hasAlign` | Returns true if the component was configured with given align |
| `exists` | Checks whether the component found with the given data hook. |
| `click` | Clicks on the component root element. |
| `base` | Returns UniDriver for the base element. |

## Changelog

- **1.340.0** (2026-10-21) — maintenance release, no component-specific changes
- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.331.0** (2026-10-01) — maintenance release, no component-specific changes
- **1.329.0** (2026-09-24) — maintenance release, no component-specific changes
- **1.328.0** (2026-09-22) — maintenance release, no component-specific changes
- **1.326.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.294.0** (2026-07-02) — feat: title uses Heading H2 across all skins (BM reimagined) ([#16459](invalid-url)) — has visual changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.288.0** (2026-06-15) — maintenance release, no component-specific changes
- **1.278.0** (2026-05-08) — maintenance release, no component-specific changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.254.0** (2026-02-03) — maintenance release, no component-specific changes
- **1.215.0** (2025-08-27) — maintenance release, no component-specific changes
- **1.213.0** (2025-08-19) — maintenance release, no component-specific changes
- **1.196.0** (2025-06-04) — maintenance release, no component-specific changes
- **1.184.0** (2025-04-30) — fix: add width: 100% to empty state components to contain width ([#14805](invalid-url))
- **1.155.0** (2025-01-23) — maintenance release, no component-specific changes
- **1.154.0** (2025-01-16) — fix: remove min-height from an image ([#14456](invalid-url))
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.103.1** (2024-04-24) — maintenance release, no component-specific changes
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.93.0** (2024-02-08) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes