PlEmpty

The place where there is nothing, an empty list, a search that found nothing, a flow that has finished. A mark, a line, a sentence, and a way out.

React

import { PlEmpty } from 'plass-ui';

<PlEmpty
  icon={<InboxIcon />}
  title="No projects yet"
  description="Start one and it will show up here."
  actions={<PlButton>New project</PlButton>}
/>;

import 'package:plass_ui/plass_ui.dart';

PlEmpty(
  icon: const Icon(Icons.inbox),
  title: const Text('No projects yet'),
  description: const Text('Start one and it will show up here.'),
  actions: <Widget>[PlButton(onPressed: create, child: const Text('New project'))],
);

Props

Prop	Type	Default	Description
icon	ReactNode	—	The glyph or drawing above the words. Sized off size
title	ReactNode	—	The one line that says what is not here
description	ReactNode	—	What to do about it. One or two sentences, never a paragraph
actions	ReactNode	—	The way out — usually one PlButton
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Glyph, type scale and the space around it
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'secondary'	The family the glyph takes. secondary is nothing yet, danger is something went wrong, success is you are done
densityshared	'default' | 'compact'	'default'	The vertical padding, and nothing else

Prop	Type	Default	Description
icon	Widget?	—	The glyph or drawing above the words. Sized off size
title	Widget?	—	The one line that says what is not here
description	Widget?	—	What to do about it. One or two sentences, never a paragraph
actions	List<Widget>	[]	The way out — usually one PlButton
child	Widget?	—	Anything else that belongs between the description and the actions
sizeshared	PlassSize	PlassSize.md	Glyph, type scale and the space around it
colorshared	PlassColor	PlassColor.secondary	The family the glyph takes. secondary is nothing yet, danger is something went wrong, success is you are done
densityshared	PlassDensity	PlassDensity.standard	The vertical padding, and nothing else

Every native <div> attribute passes straight through. What the shared axes mean across the library is in prop conventions.

actions is a List<Widget> laid out in a Wrap, rather than the single slot the React build takes. A Dart caller has no fragment to put two buttons in.

One component

An empty list, a search with no results, a request that failed and a flow that finished are the same arrangement (a mark, a line, a sentence, a way out), which is why they are one component. What tells them apart is color:

secondary (the default)	Nothing here yet. Nothing has gone wrong
danger	Something has
success	You are done, which is the "your order is confirmed" screen, without a second component

React

import { PlButton, PlCard, PlEmpty } from 'plass-ui';

export default function EmptyKinds() {
  return (
    <div className="grid w-full gap-4 md:grid-cols-3">
      <PlCard>
        <PlEmpty
          size="sm"
          icon={<span>🔍</span>}
          title="No results"
          description="Try fewer words."
        />
      </PlCard>

      <PlCard>
        <PlEmpty
          size="sm"
          color="danger"
          icon={<span>⚠️</span>}
          title="Could not load"
          description="The server did not answer."
          actions={
            <PlButton size="sm" color="danger" variant="glass">
              Try again
            </PlButton>
          }
        />
      </PlCard>

      <PlCard>
        <PlEmpty
          size="sm"
          color="success"
          icon={<span>✅</span>}
          title="All done"
          description="Your order is on its way."
        />
      </PlCard>
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class EmptyKinds extends StatelessWidget {
  const EmptyKinds({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 620,
      child: Row(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: <Widget>[
          const Expanded(
            child: PlCard(
              child: PlEmpty(
                size: PlassSize.sm,
                icon: Text('🔍'),
                title: Text('No results'),
                description: Text('Try fewer words.'),
              ),
            ),
          ),
          const SizedBox(width: 16),
          Expanded(
            child: PlCard(
              child: PlEmpty(
                size: PlassSize.sm,
                color: PlassColor.danger,
                icon: const Text('⚠️'),
                title: const Text('Could not load'),
                description: const Text('The server did not answer.'),
                actions: <Widget>[
                  PlButton(
                    size: PlassSize.sm,
                    color: PlassColor.danger,
                    variant: PlassVariant.glass,
                    onPressed: () {},
                    child: const Text('Try again'),
                  ),
                ],
              ),
            ),
          ),
          const SizedBox(width: 16),
          const Expanded(
            child: PlCard(
              child: PlEmpty(
                size: PlassSize.sm,
                color: PlassColor.success,
                icon: Text('✅'),
                title: Text('All done'),
                description: Text('Your order is on its way.'),
              ),
            ),
          ),
        ],
      ),
    );
  }
}

No surface of its own

An empty state is always inside something (a card, a table, a panel), and a sheet inside a sheet is two sheets. What this decides is the arrangement and the space around it.

React

import { PlButton, PlEmpty, PlTable } from 'plass-ui';

interface Row {
  id: string;
  name: string;
}

export default function EmptyTable() {
  return (
    <PlTable<Row>
      className="w-full"
      columns={[
        { key: 'name', header: 'Name' },
        { key: 'id', header: 'Id' }
      ]}
      rows={[]}
      empty={
        <PlEmpty
          size="sm"
          title="Nothing matches that filter"
          description="Clear it to see everything again."
          actions={
            <PlButton size="sm" variant="glass" color="secondary">
              Clear filters
            </PlButton>
          }
        />
      }
    />
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class EmptyTable extends StatelessWidget {
  const EmptyTable({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 460,
      child: PlTable<Map<String, String>>(
        columns: <PlTableColumn<Map<String, String>>>[
          PlTableColumn<Map<String, String>>(
            header: const Text('Name'),
            cell: (Map<String, String> row, int _) => Text(row['name'] ?? ''),
          ),
          PlTableColumn<Map<String, String>>(
            header: const Text('Id'),
            cell: (Map<String, String> row, int _) => Text(row['id'] ?? ''),
          ),
        ],
        rows: const <Map<String, String>>[],
        empty: PlEmpty(
          size: PlassSize.sm,
          title: const Text('Nothing matches that filter'),
          description: const Text('Clear it to see everything again.'),
          actions: <Widget>[
            PlButton(
              size: PlassSize.sm,
              variant: PlassVariant.glass,
              color: PlassColor.secondary,
              onPressed: () {},
              child: const Text('Clear filters'),
            ),
          ],
        ),
      ),
    );
  }
}

PlTable's empty prop takes a node, and this is the node it was waiting for.

The action

The one thing worth getting right. A screen that says "No projects" and stops is a dead end; the same screen with a "New project" button is the best moment in the whole flow to offer one. The reader is looking straight at the space the thing would go in.

If there is genuinely nothing to do (a search with no results, where the action is "type something else") say that in the description rather than inventing a button.

Accessibility

• The glyph is aria-hidden. The title says what it says, and a reader should not be told twice.
• It has no role of its own. Put role="status" on it when the emptiness is the result of something the reader just did (clearing a filter, running a search), so the change is announced. Leave it off for a list that was empty when the page loaded, which has already been read.
• The title is a <p> rather than a heading. Where it belongs in a document's outline is the page's decision and not this component's; pass render on a PlTypography above it if it needs to be one.

The glyph is wrapped in an ExcludeSemantics, and there is no role: put the empty state inside a Semantics(liveRegion: true) when the emptiness is the result of something the reader just did.