## Usage

The `<EmptyState />` component is used when there is no data to be displayed, for example:

- When no data exists yet.
- When an error getting the data has occurred.
- When no search results match the user's inputted search value.

For examples of implementation, refer to the [Filtering](/patterns/filtering/examples/) and [Tables](/patterns/tables/examples/#empty-states) patterns.

## Basic implementation

The most basic implementation of an `<EmptyState />` only requires a `title` and a `description`. The messaging should be concise, informative and communicate _why_ no data can be displayed.

Use the `headingLevel` prop to control the semantic heading level (rank) according to where in the page structure the empty state lives.

```tsx live
return <EmptyState title="No results found" description="Check your search value and try again." headingLevel={3} />;
```

## Actions

When possible, provide the user with actions they can take to see the data they need. Use the `primaryAction` prop to render a primary `<Button />` (or a `<ButtonLink />` if a `primaryAction.href` is defined). If there are more potential actions the user can take, use the `secondaryAction` prop to render a secondary button.

NOTE: A secondary action should never be used on its own.

```tsx live
return (
  <EmptyState
    title="Something went wrong"
    description="Refresh the page or try again later."
    primaryAction={{
      label: 'Primary action',
      onClick: () => alert('Primary action clicked'),
    }}
    secondaryAction={{
      label: 'Secondary action',
      onClick: () => alert('Secondary action clicked'),
    }}
  />
);
```

Button link example:

```tsx live
return (
  <EmptyState
    title="Page not found"
    description="Click to be redirected to the homepage."
    primaryAction={{
      label: 'Primary action',
      href: 'https://www.elmosoftware.com.au',
    }}
    secondaryAction={{
      label: 'Secondary action',
      href: 'https://www.elmosoftware.com.au',
    }}
  />
);
```

## Spot illustration

Optionally, provide a `spotIllustration` from the [Illustration](/packages/illustration/) package as a complement to convey the message of the empty state.

```tsx live
return (
  <EmptyState
    spotIllustration={LearningSpot}
    title="No courses found"
    description="Explore course catalogue to find new available courses."
    headingLevel={3}
  />
);
```

An inline message component to communicate why no data is displayed and what to do next.

EmptyState

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources

title

description

Semantic heading level for title. Defaults to `2`, which renders a `<h2>`.
If needed, adjust to follow Heading ranks best practices.
NOTE: This doesn't affect font-size.
@see WAI https://www.w3.org/WAI/tutorials/page-structure/headings/

headingLevel

Optionally, provide a spot illustration from `@eds/illustration` as a complement to convey the message.
@see Illustration https://eds.docs.elmotalent.com.au/packages/illustration/

Prop	Required	Description	Type
`title`	✅	Heading text of the empty state.	string
`description`	✅	Body text of the empty state.	string
`headingLevel`	—	Semantic heading level for title. Defaults to 2, which renders a <h2>. If needed, adjust to follow Heading ranks best practices. NOTE: This doesn't affect font-size. @see WAI https://www.w3.org/WAI/tutorials/page-structure/headings/	1 \| 2 \| 3 \| 4 \| 5 \| 6
`spotIllustration`	—	Optionally, provide a spot illustration from @eds/illustration as a complement to convey the message. @see Illustration https://eds.docs.elmotalent.com.au/packages/illustration/	ComponentClass<SpotIllustrationProps, any> \| FunctionComponent<SpotIllustrationProps>
`primaryAction`	—	Button type primary with action for the user.	ButtonPropTypes
`secondaryAction`	—	Button type secondary with action for the user.	ButtonPropTypes