# Empty states

Tells the reader why a loaded surface has nothing to show and offers the action that fills it: one sentence, at most one action, no icon.

* Kind: pattern
* Page: https://design.werklist.com/patterns/empty-states
* Version: 2.1.2

## When to use it

* A surface has loaded and has no items
* A search or a filter returned nothing
* The reader has dealt with everything and is all caught up
* A list that only the reader's own action fills is empty
* A reader who cannot add sees an empty surface

## When not to use it

* Before the content has loaded: show the skeleton
* When the load failed: show the error in place
* Icons, illustrations, a second paragraph

## Rules

* One sentence and at most one action. No icon, illustration or second paragraph.
* The toolbar, the search field and the filters stay above the empty state.
* In a table the header row stays, and the small sentence fills a body at least three rows high.
* A surface is empty only after it has loaded. While it loads it shows its skeleton, and a failed load shows the error.
* The action opens the same form as the Add button in the toolbar.
* A search that finds nothing is announced once: 'No candidates match.'

## Anatomy

* Sentence on a page: 20 px, 26 px from 640 px wide, line height 1.25, weight 700, in balanced lines at most 34 rem wide (--text)
* Sentence in a panel or a card: 14 px on 20 px, weight 400 (--text-muted)
* Action on a page: Primary button, 44 px, 24 px under the sentence. It opens the same form as the Add button in the toolbar. (--space-6)
* Action in a panel or a card: Quiet small button or a link, 8 px under the sentence, or none (--space-2)
* Space above and below: On a page 48 px, 64 px from 640 px wide. In a panel or a card 48 px. (--space-12, --space-16)

## Variants

* Nothing yet: Says what goes here and offers the create action: 'Add the first candidate to this project.'
* Nothing matches: Says the search or the filters hid everything and offers Clear filters or Clear search
* All done: Says the reader is finished and offers nothing: 'You are all caught up.'
* Filled by you: Says how the list fills and offers nothing: 'Candidates you save appear here.'
* No access: Says who can add and offers nothing: 'Only the owners of this board can add items.'
* Error in place: The failure sentence in full ink and Try again, as the Errors pattern sets it

## Accessibility

* The sentence is plain text in reading order. It is a heading only when the surface has no other.
* The action follows the sentence in reading order.

## Content

* Say what goes here or why nothing is here.
* No 'Oops', no exclamation mark, no 'No data'.

## Tokens

* --text
* --text-muted
* --space-2
* --space-6
* --space-12
* --space-16