Examples
Empty and error states pattern
Choose the correct shared surface for empty, loading, error, and completed results.
No projects yet
Create the first project to give your team a place to start.
Tabs showing empty, no-results, loading, error, and success states
"use client";
import { useEffect, useRef, useState } from "react";
import { Alert } from "@phuctech/ui/components/alert";
import { Button } from "@phuctech/ui/components/button";
import { EmptyState } from "@phuctech/ui/components/empty-state";
import { Result } from "@phuctech/ui/components/result";
import { Skeleton } from "@phuctech/ui/components/skeleton";
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@phuctech/ui/components/tabs";
type StateView = "empty" | "no-results" | "loading" | "error" | "success";
export function Example() {
const [view, setView] = useState<StateView>("empty");
const retryTimer = useRef<number | null>(null);
useEffect(() => () => {
if (retryTimer.current !== null) window.clearTimeout(retryTimer.current);
}, []);
function retry() {
if (retryTimer.current !== null) window.clearTimeout(retryTimer.current);
setView("loading");
retryTimer.current = window.setTimeout(() => {
retryTimer.current = null;
setView("success");
}, 450);
}
return (
<div className="w-full max-w-2xl">
<Tabs value={view} onValueChange={(value) => setView(value as StateView)} className="w-full">
<TabsList aria-label="Project result states" className="flex w-full flex-wrap">
<TabsTrigger value="empty">Empty</TabsTrigger>
<TabsTrigger value="no-results">No results</TabsTrigger>
<TabsTrigger value="loading">Loading</TabsTrigger>
<TabsTrigger value="error">Error</TabsTrigger>
<TabsTrigger value="success">Success</TabsTrigger>
</TabsList>
<TabsContent value="empty"><EmptyState heading="No projects yet" description="Create the first project to give your team a place to start." action={<Button type="button">Create project</Button>} /></TabsContent>
<TabsContent value="no-results"><EmptyState kind="no-results" heading="No projects match “orbit”" description="Try a shorter search or clear the current filters." action={<Button type="button" variant="outline">Clear search</Button>} /></TabsContent>
<TabsContent value="loading">
<section aria-busy="true" aria-label="Loading projects" className="grid gap-3 rounded-xl border border-border bg-card p-5">
<p role="status" className="sr-only">Loading projects</p>
<Skeleton shape="text" lines={2} />
<Skeleton shape="rectangle" className="h-20" />
<Skeleton shape="rectangle" className="h-20" />
</section>
</TabsContent>
<TabsContent value="error"><Alert variant="danger" heading="Projects could not load" description="Your saved projects are safe. Try again to return to a trusted state." /><div className="mt-3 flex justify-center"><Button type="button" onClick={retry}>Try again</Button></div></TabsContent>
<TabsContent value="success"><Result status="success" heading="Projects are ready" description="The list loaded successfully. This example uses fixture data only." action={<Button type="button" variant="outline" onClick={() => setView("empty")}>Return to empty state</Button>} /></TabsContent>
</Tabs>
</div>
);
}
State model
Copy
Write from the person’s point of view. Name the object, explain the condition in plain language, and use an action that says what will happen next. Avoid vague “Something went wrong” copy and avoid apologies that do not help recovery.
The runnable Preview and Code/Copy tabs use src/components/design/examples/source/empty-error-states-pattern.tsx. The recovery delay is a local fixture; this pattern has no public property playground.
- Empty: “No projects yet” plus “Create project.”
- No results: repeat the query or filter context and offer “Clear search.”
- Error: say what could not load, preserve safe context, and offer “Try again.”
Accessibility
- Keep the state heading in the document structure; do not communicate the state with an illustration or color alone.
- Use
role="status"for non-urgent loading/success updates androle="alert"only for an error that needs immediate attention. - Make Retry and the recovery action keyboard-focusable and keep the label specific.
- Respect reduced motion. A spinner may be decorative, but the loading message must still be available as text.
Do and don’t
Treat emptiness as an invitation to act and errors as a short path back to a trusted state.
Show a blank container, hide the recovery action behind hover, or make the user guess whether data was deleted.
Related
- Button gives the recovery action a clear verb and loading state.
- Card keeps a state message and its action together.
- Accessibility documents the shared focus and contrast contract.