Banner

Banners inform users of important, page-level information — such as errors, warnings, or success messages — without interrupting their workflow.

Your session will expire in 5 minutes. Extend

Overview

A banner displays an important, succinct message, and provides actions for users to address (or dismiss the banner). It requires a user action to be dismissed.

Banners should be displayed at the top of the screen, below the app bar. The banner displays a short amount of information, but may be clicked to launch a dialog with rich text information.

Usage

forge-banner displays a persistent, page-level message through theme, dismissed, and persistent, plus optional icon and button slots. Reserve it for a full-page announcement the user only needs to see once; for guidance scoped to a single field or section, use an inline message instead, for a reactive confirmation of an action use a toast, and for a high-priority alert that requires a decision use a dialog.

Rules

Use a banner for a page-level announcement the user only needs to see once, like a new feature or maintenance notice.

Pair the message with a "Learn more" action when there's more detail to show, typically opening a dialog.

Keep banner text succinct — a sentence or two, not a paragraph.

Place a banner at the top of the page, below the app bar.

Don't

Don't use a banner for information scoped to a single field or component — use an inline message instead.

Don't use a banner for a reactive confirmation of an action, like a save or delete — use a toast instead.

Don't use a banner for a high-priority alert that requires a decision — use a dialog instead.

Theme

Set theme to primary, secondary, tertiary, success, error, warning, info (the default), or info-secondary to match the message’s severity.

Every banner theme, ordered from most to least urgent.

<div style="display: flex; gap: 12px; flex-direction: column;">
  <forge-banner theme="error">
    Error
  </forge-banner>
  <forge-banner theme="warning">
    Warning
  </forge-banner>
  <forge-banner theme="success">
    Success
  </forge-banner>
  <forge-banner theme="info">
    Info (default)
  </forge-banner>
  <forge-banner theme="info-secondary">
    Info (secondary)
  </forge-banner>
</div>

With an icon and action

Pair the message with a leading icon in the icon slot to reinforce its severity, and a trailing action in the button slot when there’s more detail to show.

A banner with a leading icon and a Learn more action.

<forge-banner>
  Minim sunt eu laborum labore minim iconium buttonium.
  <forge-icon slot="icon" name="notifications">
  </forge-icon>
  <forge-button slot="button" variant="outlined">
    Learn more...
  </forge-button>
</forge-banner>

<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconNotifications } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconNotifications]);
</script>

Persistent

Set persistent to remove the banner’s built-in dismiss button when the message shouldn’t be dismissed by the user.

A persistent banner has no built-in dismiss button.

<forge-banner persistent>
  An announcement that only your app can dismiss.
</forge-banner>

Banners are used to inform users of important information, such as errors, warnings, or success messages. Use banners for non-critical messages that require user attention but do not interrupt workflow.

import "@tylertech/forge/banner";

Properties

Property	Attribute	Type	Default	Description
`dismissed`	`dismissed`	`boolean`	`false`	Controls the visibility of the banner.
`persistent`	`persistent`	`boolean`	`false`	Controls the visibility of the built-in dismiss button.
`theme`	`theme`	`BannerTheme`	`"info"`	The theme of the banner.
`canDismiss`	—	`boolean`	—

Events

Name	Type	Description
`forge-banner-before-dismiss`	`CustomEvent<void>`	Dispatched before the banner is dismissed. Cancelable to prevent dismissal.
`forge-banner-dismissed`	`CustomEvent<void>`	Dispatched when the banner is dismissed.

Slots

Name	Description
`(default)`	The content of the banner.
`icon`	The icon to display.
`button`	The optional button to display.

CSS Custom Properties

Name	Description
`--forge-banner-background`	The background color of the banner.
`--forge-banner-color`	The text color of the banner.
`--forge-banner-icon-color`	The color of the icon.
`--forge-banner-gap`	The gap between the contents.
`--forge-banner-padding-inline`	The inline padding.
`--forge-banner-padding-block`	The block padding.
`--forge-banner-transition-duration`	The transition duration.
`--forge-banner-transition-easing`	The transition easing function.

Live region behavior

Set role="alert" on an urgent banner — equivalent to aria-live="assertive" — so it’s announced immediately. For a less urgent banner, use aria-live="polite" instead, so assistive technology waits until the user finishes their current task before announcing it.