{"slug":"empty-state","meta":{"title":"Empty State","slug":"empty-state","kind":"pattern","summary":"What a screen shows when it has nothing to show — which is either someone's first impression of the feature, or proof that their work is done.","problem":"A list with no rows renders as a blank area or the word \"None\". The person cannot tell whether the feature is broken, whether their filter is too narrow, or whether they are supposed to do something — so they leave.","family":["orient","recover"],"data_shape":["collection"],"principles":["orientation","friction"],"interaction":["scanning"],"density":"low","complexity":"low","status":"stable","visibility":"public","use_when":["Any list, table, board, queue or search result can legitimately be empty.","A new account starts with nothing, so the empty state is the first screen anyone sees."],"avoid_when":["Never. Every collection needs one — the only question is which of the four kinds it is."],"alternatives":[{"slug":"loading-skeleton","when":"The content is not empty, it has not arrived yet. Those must look different."}],"ask_leo":"Give every empty collection in this app a real empty state, and pick the right\none of the four kinds.\n\nFIRST USE — nothing exists yet. Say what this feature is for in one sentence,\nshow the primary action as a button, and if setup is involved, say how long it\ntakes. This is the highest-value screen in the product; do not waste it on the\nword \"None\".\n\nFILTERED TO NOTHING — records exist but none match. Say which filters are\nactive, give the total that exists without them, and offer to clear the\nfilters. Never show the first-use screen here; it implies their data is gone.\n\nALL DONE — a queue or task list someone emptied. Say so as success, in plain\nwords, and offer where to go next. Do not show a \"create one\" button; nobody\nfinishing a queue wants to add work.\n\nERROR — the data could not be loaded. Say that clearly, offer retry, and never\nlet it look like \"you have nothing\". A failure that reads as emptiness makes\npeople think their records were deleted.\n\nIn every case: no bare \"No results\". Say what is empty, why, and what to do.\n","related":[{"title":"Filter Bar","url":"/patterns/filter-bar","summary":"Where the filtered-to-nothing state comes from, and what it must offer."},{"title":"Orientation","url":"/patterns/orientation","summary":"An empty screen is where orientation matters most and is skipped most."}]},"body":"## Anatomy\n\nThere is no single empty state. There are four, and showing the wrong one is\nworse than showing none, because it asserts something untrue.\n\n```\nFIRST USE                        FILTERED TO NOTHING\n┌───────────────────────────┐    ┌───────────────────────────┐\n│  No invoices yet          │    │  No invoices are overdue  │\n│  Invoices bill a client   │    │  and owned by Dana.       │\n│  for completed jobs.      │    │  318 invoices exist.      │\n│      [ Create invoice ]   │    │      [ Clear filters ]    │\n└───────────────────────────┘    └───────────────────────────┘\n\nALL DONE                         ERROR\n┌───────────────────────────┐    ┌───────────────────────────┐\n│  Queue clear ✓            │    │  Couldn't load invoices.  │\n│  Nothing is waiting on    │    │  The billing service did  │\n│  you right now.           │    │  not respond.             │\n│      [ Back to dashboard ]│    │      [ Try again ]        │\n└───────────────────────────┘    └───────────────────────────┘\n```\n\n## Why it works\n\nAn empty screen is the only screen with **no content to compete with the\nmessage**, which makes it the most reliably read text in the product. First-use\nempty states are, in practice, the best onboarding surface anyone has: they\nappear exactly when the person is trying to understand the feature, and they\ncost nothing to build.\n\nThe other three kinds are about preventing a wrong conclusion. Emptiness is\nambiguous by nature — the same blank area means \"you have none\", \"your filter is\nnarrow\", \"you are finished\" and \"we are broken\". Naming which one it is removes\nthe ambiguity, and that is the whole job.\n\n## The dangerous confusion\n\n**An error that looks like emptiness is the worst outcome in this pattern.**\nA failed request rendering as \"No invoices\" tells a paying customer their data\nis gone. They will not report a loading bug; they will report data loss, or\nchurn.\n\nThe same applies to a filtered list showing the first-use state — \"No invoices\nyet. Create your first one\" — when the person has three hundred invoices and a\nnarrow filter.\n\n## Getting it wrong\n\n- **\"No results.\"** True, useless, and it is the default in almost every table\n  component.\n- **The wrong kind.** First-use copy on a filtered list; a create button on a\n  finished queue.\n- **Blank.** Indistinguishable from a rendering failure.\n- **An illustration and nothing else.** A friendly drawing is not an\n  explanation.\n- **A first-use state with no action**, which explains the feature and then\n  leaves the person with no way to start using it.\n\n## Exemplars\n\n**Slack's empty channel** tells you what the channel is for and gives you the\none action that makes it useful, which is why nobody has ever had to be taught\nwhat to do in a new channel.\n\n**Gmail's \"You're all caught up\"** is the finished-queue state done as success,\nand it is a big part of why emptying an inbox feels like an accomplishment\nrather than an absence.\n\n**Stripe's filtered empty state** names the filters back to you and offers to\nclear them — the small thing that stops people concluding the data is missing.\n\nThe extractable rule: **empty is a question, and the screen has to answer it.**\nWhich of the four kinds this is, is the answer.\n"}