XDS — Design System

EmptyState@xds/core · XDSEmptyState v0.0.13

Usage

EmptyState shows a placeholder when a content area has no data. Use it for empty lists, zero search results, first-time setups, or cleared inboxes. Always include a title and a next step so the user is not stuck.

ts
import {XDSEmptyState} from '@xds/core/EmptyState'

Best practices

Guidance	Practices
Do	Include a clear title and a call-to-action button so users know how to proceed.
Do	Use an illustration or icon that reinforces the context of the empty state.
Do	Use the compact variant inside cards or sidebars where space is limited.
Don't	Leave an empty state without guidance — always explain what happened and what the user can do next.
Don't	Use a generic message like "No data" — be specific about what is empty and why.
Don't	Use an EmptyState for error messages that require immediate action — use a Banner instead.

Examples

Common configurations, variations, and states.

EmptyState — Actions

tsx
'use client';
import {XDSEmptyState} from '@xds/core/EmptyState';
import {XDSButton} from '@xds/core/Button';
import {XDSIcon} from '@xds/core/Icon';
import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
export default function EmptyStateActions() {
  return (
    <XDSEmptyState
      icon={<XDSIcon icon={MagnifyingGlassIcon} size="lg" />}
      title="No results found"
      description="Try adjusting your search terms or clearing filters to see more results."
      actions={
        <>
          <XDSButton label="Go back" variant="secondary" />
          <XDSButton label="Clear filters" variant="primary" />
        </>
      }
    />
  );
}

EmptyState — CompactSmaller empty state with reduced spacing for constrained areas. Use inside sidebar panels, card widgets, or notification drawers where a full-size empty state would overwhelm the layout.

tsx
'use client';
import {XDSEmptyState} from '@xds/core/EmptyState';
import {XDSButton} from '@xds/core/Button';
import {XDSHStack} from '@xds/core/Layout';
import {XDSIcon} from '@xds/core/Icon';
import {InboxIcon} from '@heroicons/react/24/outline';
export default function EmptyStateCompact() {
  return (
    <XDSEmptyState
      icon={<XDSIcon icon={InboxIcon} size="lg" />}
      title="No notifications"
      description="You're all caught up. New notifications will appear here."
      actions={
        <XDSHStack gap={2}>
          <XDSButton label="Settings" variant="secondary" size="sm" />
          <XDSButton label="Refresh" variant="primary" size="sm" />
        </XDSHStack>
      }
      isCompact
    />
  );
}

EmptyState — Container

tsx
'use client';
import {XDSEmptyState} from '@xds/core/EmptyState';
import {XDSButton} from '@xds/core/Button';
import {XDSCard} from '@xds/core/Card';
import {XDSIcon} from '@xds/core/Icon';
import {FolderPlusIcon} from '@heroicons/react/24/outline';
export default function EmptyStateContainer() {
  return (
    <XDSCard>
      <XDSEmptyState
        icon={<XDSIcon icon={FolderPlusIcon} size="lg" />}
        title="No projects yet"
        description="Create your first project to start organizing your work. You can invite team members after."
        actions={
          <>
            <XDSButton label="Import" variant="secondary" />
            <XDSButton label="Create project" variant="primary" />
          </>
        }
      />
    </XDSCard>
  );
}

Showcase source

tsx
'use client';
import {XDSEmptyState} from '@xds/core/EmptyState';
import {XDSButton} from '@xds/core/Button';
import {XDSIcon} from '@xds/core/Icon';
import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
export default function EmptyStateShowcase() {
  return (
    <XDSEmptyState
      icon={<XDSIcon icon={MagnifyingGlassIcon} size="lg" />}
      title="No results found"
      description="Try adjusting your search or filters to find what you need."
      actions={<XDSButton label="Clear filters" variant="secondary" />}
    />
  );
}

Usage

import {XDSEmptyState} from '@xds/core/EmptyState'

Best practices

Guidance	Practices
Do	Include a clear title and a call-to-action button so users know how to proceed.
Do	Use an illustration or icon that reinforces the context of the empty state.
Do	Use the compact variant inside cards or sidebars where space is limited.
Don't	Leave an empty state without guidance — always explain what happened and what the user can do next.
Don't	Use a generic message like "No data" — be specific about what is empty and why.
Don't	Use an EmptyState for error messages that require immediate action — use a Banner instead.

tsx

'use client'; import {XDSEmptyState} from '@xds/core/EmptyState'; import {XDSButton} from '@xds/core/Button'; import {XDSIcon} from '@xds/core/Icon'; import {MagnifyingGlassIcon} from '@heroicons/react/24/outline'; export default function EmptyStateActions() { return ( <XDSEmptyState icon={<XDSIcon icon={MagnifyingGlassIcon} size="lg" />} title="No results found" description="Try adjusting your search terms or clearing filters to see more results." actions={ <> <XDSButton label="Go back" variant="secondary" /> <XDSButton label="Clear filters" variant="primary" /> </> } /> ); }

tsx

'use client'; import {XDSEmptyState} from '@xds/core/EmptyState'; import {XDSButton} from '@xds/core/Button'; import {XDSHStack} from '@xds/core/Layout'; import {XDSIcon} from '@xds/core/Icon'; import {InboxIcon} from '@heroicons/react/24/outline'; export default function EmptyStateCompact() { return ( <XDSEmptyState icon={<XDSIcon icon={InboxIcon} size="lg" />} title="No notifications" description="You're all caught up. New notifications will appear here." actions={ <XDSHStack gap={2}> <XDSButton label="Settings" variant="secondary" size="sm" /> <XDSButton label="Refresh" variant="primary" size="sm" /> </XDSHStack> } isCompact /> ); }

tsx

'use client'; import {XDSEmptyState} from '@xds/core/EmptyState'; import {XDSButton} from '@xds/core/Button'; import {XDSCard} from '@xds/core/Card'; import {XDSIcon} from '@xds/core/Icon'; import {FolderPlusIcon} from '@heroicons/react/24/outline'; export default function EmptyStateContainer() { return ( <XDSCard> <XDSEmptyState icon={<XDSIcon icon={FolderPlusIcon} size="lg" />} title="No projects yet" description="Create your first project to start organizing your work. You can invite team members after." actions={ <> <XDSButton label="Import" variant="secondary" /> <XDSButton label="Create project" variant="primary" /> </> } /> </XDSCard> ); }

tsx

'use client'; import {XDSEmptyState} from '@xds/core/EmptyState'; import {XDSButton} from '@xds/core/Button'; import {XDSIcon} from '@xds/core/Icon'; import {MagnifyingGlassIcon} from '@heroicons/react/24/outline'; export default function EmptyStateShowcase() { return ( <XDSEmptyState icon={<XDSIcon icon={MagnifyingGlassIcon} size="lg" />} title="No results found" description="Try adjusting your search or filters to find what you need." actions={<XDSButton label="Clear filters" variant="secondary" />} /> ); }