EmptyState

Components/Layout

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

Overview

Copy

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.
Copy

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)
Copy

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.
Copy

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.

Copy

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.

Copy

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.

Copy

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.

Copy

Failed to load

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

Copy

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.

Copy

Code

Copy

Props

NameTypeDefaultDescription
align"center" | "end" | "start"'center'Sets the alignment of all empty state contents within the component container.
childrenReactNode—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.
dataHookstring—Applies a data-hook HTML attribute to be used in the tests.
imagestring | 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.
subtitleReactNode—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.
titleReactNode—Sets the content for the title.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
elementReturns the element
getTitleTextReturns the text of the title
getSubtitleTextReturns the text of the subtitle
hasThemeReturns true if the component was configured with given skin
hasSkinReturns true if the component was configured with given skin
getImageUrlReturns the URL of the image element (if persist)
getImageContainerClassName—
imageNodeExistsReturns true if a node passed via the image prop exists
childrenContentExistsReturns true if children content exists
hasAlignReturns true if the component was configured with given align
existsChecks whether the component found with the given data hook.
clickClicks on the component root element.
baseReturns 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) — 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)
  • 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)
  • 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

Last updated: 22 October 2026

Did this help?