Banner

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

• Tell everyone using the product about a state of the whole product, such as maintenance, degraded service or an outage. Put Banner.Root first in AppShell.Root: it spans the shell edge to edge above the header, or above the sidebar and the content, and lines its icon up with the shell.
• Name the state in Banner.Title, such as Scheduled maintenance; the tone colors the plane and the icon but never says it alone. Banner.Description adds when and what to do, in one line where it fits. Banner.Actions holds a link or button to the status page or the next step; on a phone the actions go under the text.
• The banner is a polite live region: a change to its text is announced without interrupting. onDismiss shows a dismiss button; remove the banner when it is called, and focus moves to the first control after it.

• Don't use a banner for a message about one task or form; use InlineMessage there. Don't use it for an outcome the reader just caused; use Toast.
• Don't stack banners. Show the most severe state, and put the rest on the status page.
• Don't make a danger banner dismissible while the outage lasts, or bring a dismissed notice back on every page.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

Root(tone, role=status) → Icon + Content(Title + Description) + Actions + dismiss button

Keyboard and accessibility

• The banner takes no focus. Tab reaches its actions and the dismiss button; Enter or Space presses them.
• After dismissing, focus moves to the first control that followed the banner.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { AppShell, Banner, LinkButton } from '@surflane/ui'

<AppShell.Root layout='workspace'>
  {notice && (
    <Banner.Root tone='caution' onDismiss={() => setNotice(false)}>
      <Banner.Icon />
      <Banner.Content>
        <Banner.Title>Scheduled maintenance</Banner.Title>
        <Banner.Description>
          Deployments pause on Saturday, 02:00–04:00 UTC.
        </Banner.Description>
      </Banner.Content>
      <Banner.Actions>
        <LinkButton href='/status' variant='outline' size='small'>
          View status
        </LinkButton>
      </Banner.Actions>
    </Banner.Root>
  )}
  <AppShell.Sidebar>…</AppShell.Sidebar>
  <AppShell.Content>…</AppShell.Content>
</AppShell.Root>

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens