Empty state

To add the EmptyState component to your app:

1
2
import { EmptyState } from "@forge/react";

Description

An empty state appears when there is no data to display and describes what the user can do next.

Props

Examples

Default

The only required property of an empty state is the header.

1
2
export const EmptyStateExample = () => {
  return <EmptyState header="You don't have access to this issue" />;
};

Custom header level

The headingLevel rendered by default is 4. To make sure that the empty state is accessible, headers must follow a logical order. If the empty state does not follow a h3 or h4 in the reading order, then you will need to modify the heading order to the next logical heading level.

1
2
export const CustomHeadingLevelEmptyStateExample = () => {
  return (
    <EmptyState header="You don't have access to this issue" headingLevel={1} />
  );
};

Description

Descriptions should add useful and relevant additional information.

1
2
export const EmptyStateWithDescriptionExample = () => {
  return (
    <EmptyState
      header="You don't have access to this issue"
      description="Make sure the issue exists in this project. If it does, ask a project admin for permission to see the project's issues."
    />
  );
};

Actions

Primary

Use a primary action button to recommend the best next step that people can take.

1
2
export const EmptyStateWithOneActionExample = () => {
  return (
    <EmptyState
      header="You don't have access to this issue"
      primaryAction={<Button appearance="primary">Request access</Button>}
    />
  );
};

Secondary

Use a secondary action button to recommend an alternate step that people could take. This will render on the left side of the primary action button.

1
2
export const EmptyStateWithTwoActionsExample = () => {
  return (
    <EmptyState
      header="You don't have access to this issue"
      primaryAction={<Button appearance="primary">Request access</Button>}
      secondaryAction={<Button>View permissions</Button>}
    />
  );
};

Tertiary

Use tertiary action buttons to link to external resources or documentation to further explain how to resolve the empty state. This will render below the primary and secondary action buttons.

1
2
export const EmptyStateWithAllActionsExample = () => {
  return (
    <EmptyState
      header="You don't have access to this issue"
      primaryAction={<Button appearance="primary">Request access</Button>}
      secondaryAction={<Button>View permissions</Button>}
      tertiaryAction={
        <LinkButton appearance="link" href="/">
          About permissions
        </LinkButton>
      }
    />
  );
};

Loading State

Use the isLoading prop to indicate a loading state. This will show a spinner next to the action buttons when true.

1
2
export const LoadingStateEmptyStateExample = () => {
  return (
    <EmptyState
      header="You don't have access to this issue"
      primaryAction={<Button appearance="primary">Request access</Button>}
      isLoading={true}
    />
  );
};

Width

Narrow

The horizontal space that an empty state takes up can be controlled with the width prop. It can be set to either narrow or wide, where the default is wide.

1
2
export const NarrowEmptyStateExample = () => {
  return (
    <EmptyState
      header="You don't have access to this issue"
      description="Make sure the issue exists in this project. If it does, ask a project admin for permission to see the project's issues."
      primaryAction={<Button appearance="primary">Request access</Button>}
      width="narrow"
    />
  );
};