Page State

Page state displays a full-height message — for an empty result, an error, or general information — with an optional graphic and actions.

No results foundTry adjusting your search or filters.

Usage

forge-page-state centers a graphic, title, message, and one or more action buttons. It adapts to whatever container it’s in, so use it for a full-page empty state or server error, or scale it down inside a card or side sheet when space is limited.

Rules

Always include a graphic — it's the part users register first.

Write a header that describes the situation without sounding actionable, and body text that's concise and specific.

Include an action only when there's a genuine, logical next step, like "Add attachment" or "Refresh".

Use a greyscale illustration for a low-emphasis or secondary page state, and full color when it's the primary focus of the screen.

Don't

Don't invent an action just to fill the slot — leave it empty when there's nothing useful for the user to do.

Don't use a full-color illustration for a mini, low-emphasis empty state inside a card — prefer greyscale there.

Don't write header text that reads like an accusation or a dead end — keep the tone conversational.

Basic usage

Slot a graphic, title, message, and one or more action buttons.

A full page-state with a graphic, title, message, and two actions.

<forge-page-state>
  <img src="https://cdn.forge.tylertech.com/v1/images/spot-hero/404-error-spot-hero.svg" alt slot="graphic">
  <div slot="title">
    Nothing but tumbleweeds here...
  </div>
  <p slot="message">
    Even our best explorer couldn't find the page you're looking for. It might have been removed or you may have mistyped the URL.
  </p>
  <forge-button variant="raised" slot="action">
    Go back
  </forge-button>
  <forge-button variant="outlined" slot="action">
    Refresh
  </forge-button>
</forge-page-state>

Page states display full-height messages for empty states, errors, or other general information. They can be used as full page content, or within smaller containers and will adapt accordingly.

import "@tylertech/forge/page-state";

Slots

Name	Description
`graphic`	The slot where the graphic will be rendered.
`title`	The slot where the title will be rendered.
`message`	The slot where the message will be rendered.
`action`	The slot where the actions will be rendered.

CSS Parts

Name	Description
`::part(root)`	The root container element.
`::part(graphic-container)`	The graphic container element.
`::part(title-container)`	The title container element.
`::part(message-container)`	The message container element.
`::part(actions-container)`	The actions container element.

CSS Custom Properties

Name	Description
`--forge-page-state-width`	The width of the page state.
`--forge-page-state-height`	The height of the page state.
`--forge-page-state-spacing`	The spacing of the page state.
`--forge-page-state-mobile-width`	The mobile width of the page state.
`--forge-page-state-graphic-height`	The graphic height of the page state.
`--forge-page-state-graphic-spacing`	The graphic spacing of the page state.
`--forge-page-state-mobile-graphic-height`	The mobile graphic height of the page state.
`--forge-page-state-title-color`	The title color of the page state.
`--forge-page-state-title-spacing`	The title spacing of the page state.
`--forge-page-state-message-color`	The message color of the page state.
`--forge-page-state-message-spacing`	The message spacing of the page state.
`--forge-page-state-actions-spacing`	The actions spacing of the page state.

Graphic alt text

If the page state’s graphic communicates meaning, give it a descriptive alt attribute. If it’s purely decorative, use an empty alt="" so assistive technology skips over it.

Action buttons

If a page state includes action buttons, verify each one has an appropriate role — this only needs attention if you’re not using a real forge-button.