EmptySection

EmptySection

EmptySection is a small presentation component for empty states and placeholders. It renders an optional icon or pictogram, a required title, and a description centered inside a flexible container.

The component is used when a page, panel, or table needs a consistent "nothing to show" state without rebuilding the same layout each time.

Props

Name	Type	Required	Description
icon	ComponentType<{ className?: string; data-testid?: string }>	No	Optional icon component to render above the title.
title	string	Yes	Main empty-state heading text.
description	string | React.ReactNode	Yes	Supporting message rendered through the shared Subtitle component.
pictogram	ComponentType<{ className?: string; data-testid?: string }>	No	Optional pictogram component to render above the title. Takes precedence over icon when both are provided.
className	string	No	Optional additional classes appended to the root container.
whiteLayer	boolean	No	Applies the layer background style used for card-like empty states.

Behavior

Icon and pictogram precedence

The component resolves the visual asset with this order:

1. pictogram
2. icon
3. no image at all

If a visual component is rendered, it receives:

• className="empty-section-icon"
• data-testid="empty-section-icon"

That means callers pass the actual Carbon component, not a string name.

Description rendering

description is forwarded to the shared Subtitle component through its text prop. Because of that, the component supports either plain strings or richer React nodes.

Layout behavior

The root container always includes empty-section-container. If whiteLayer is true, it also adds empty-section-white-layer. Any custom className is prepended to those built-in classes.

Usage

With an icon

import { WarningFilled } from "@carbon/icons-react";

import EmptySection from "@/components/core/EmptySection";

<EmptySection
  icon={WarningFilled}
  title="No data available"
  description="Please check back later."
  whiteLayer
/>;

With a pictogram

import { Summit } from "@carbon/pictograms-react";

import EmptySection from "@/components/core/EmptySection";

<EmptySection
  pictogram={Summit}
  title="Nothing to show yet"
  description="Enter at least one filter to start searching."
/>;

With rich description content

import { Link } from "@tanstack/react-router";

<EmptySection
  title="No results"
  description={
    <>
      Adjust your filters or return to the <Link to="/search">search page</Link>
      .
    </>
  }
/>;

Styling

The component styles are defined in index.scss and center the content vertically and horizontally.

Key classes:

• .empty-section-container: full-width, full-height flex column centered on both axes
• .empty-section-icon: fixed visual size, bottom spacing, and interactive-border color
• .empty-section-white-layer: alternate background using Carbon layer token
• .empty-section-title: Carbon heading-02 typography
• .empty-section-subtitle: Carbon body-compact-02 typography

The icon color comes from --<prefix>-border-interactive, and the white-layer background uses --<prefix>-layer-02.

Testing Notes

Unit tests currently cover:

• icon rendering
• pictogram rendering
• support for description as a React node

Those tests validate the core contract rather than visual styling details.

When To Use

• empty table or list states
• search pages before the first query
• panels that have no configured data yet
• non-error placeholders where the UI needs a clear title and explanation