# Banner

Shows a full-width message about the system or page.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Banner.tsx)

## Overview

A full-width strip for a message about the whole product or page.

## Examples

### Basic

```tsx
import { Banner } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Banner>
      <Banner.Content>Tempo mainnet is live.</Banner.Content>
      <Banner.Action>Read more</Banner.Action>
      <Banner.Dismiss />
    </Banner>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Banner/Basic.tsx)

### Intent

Set `intent` to `neutral` (default), `info`, `positive`, `warning`, or `negative`.

```tsx
import { Banner, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      {(['neutral', 'info', 'positive', 'warning', 'negative'] as const).map((intent) => (
        <Banner intent={intent} key={intent}>
          <Banner.Content>Tempo mainnet is live.</Banner.Content>
          <Banner.Action>Read more</Banner.Action>
          <Banner.Dismiss />
        </Banner>
      ))}
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'flex', flexDirection: 'column', gap: '8' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Banner/Intent.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Banner } from '@tempoxyz/ds'

<Banner>
  <Banner.Content />
  <Banner.Action />
  <Banner.Dismiss />
</Banner>
```

## Guidelines

### When to Use

* Report a condition that affects the whole product or page, such as degraded RPC service or paused deposits.
* Announce maintenance or a change for every account, such as a new webhook retry policy.
* Mark the environment, such as a testnet build of Tempo Wallet.

### When Not to Use

* Use [Alert](/docs/components/alert) for a message about one section, form, or field.
* Use [Toast](/docs/components/toast) to confirm that an action finished, such as Payment sent.
* If an action needs a decision before it continues, use [AlertDialog](/docs/components/alert-dialog).
* Use `Field.Error` from [Field](/docs/components/field) for a validation message on one input.

### Choose an Intent by Severity

* **Neutral (neutral):** The default. Announcements with no severity, such as a testnet notice.
* **Info (info):** Context that needs no action now, such as upcoming maintenance.
* **Positive (positive):** A resolved condition, such as resumed deposits.
* **Warning (warning):** Degraded service or a step to take soon, such as delayed deposits.
* **Negative (negative):** An outage or failure that blocks work, such as paused payments.

### State Severity in the Text

Banner has no icon part, so the text carries the severity. The `intent` tint doesn't reach screen reader users or forced-colors modes.

**Do:** Name the affected feature and the impact, such as delayed deposits.

```tsx
/**
 * Do example for "State Severity in the Text" on the Banner page.
 * Name the affected feature and the impact, such as delayed deposits.
 * @module
 */
import { Banner } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Banner intent="warning">
      <Banner.Content>Deposits from Ethereum are delayed by about 20 minutes.</Banner.Content>
      <Banner.Action>View status</Banner.Action>
    </Banner>
  )
}
```

**Don't:** Rely on the `negative` tint to say that something is broken.

```tsx
/**
 * Don't example for "State Severity in the Text" on the Banner page.
 * Don't rely on the `negative` tint to say that something is broken.
 * @module
 */
import { Banner } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Banner intent="negative">
      <Banner.Content>Heads up</Banner.Content>
      <Banner.Action>Learn more</Banner.Action>
    </Banner>
  )
}
```

### Show One Banner at a Time

Hold the less severe messages until the current one clears. Place the banner above the page header.

**Do:** Show the single most urgent banner above the page content.

```tsx
/**
 * Do example for "Show One Banner at a Time" on the Banner page.
 * Show the single most urgent banner above the page content.
 * @module
 */
import { Banner, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <Banner intent="negative">
        <Banner.Content>Payments are paused while we fix an RPC outage.</Banner.Content>
      </Banner>
      <div {...styles.content()}>
        <div {...styles.label()}>Balance</div>
        <div {...styles.value()}>$1,250.00</div>
      </div>
    </div>
  )
}

namespace styles {
  export const content = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '4',
    padding: '16',
  })

  export const label = style({ color: 'content.secondary', typography: 'body.b3' })

  export const page = style({ display: 'flex', flexDirection: 'column', width: '100% !custom' })

  export const value = style({ color: 'content.primary', typography: 'heading.h2' })
}
```

**Don't:** Stack several banners of different intents.

```tsx
/**
 * Don't example for "Show One Banner at a Time" on the Banner page.
 * Don't stack several banners of different intents.
 * @module
 */
import { Banner, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <Banner intent="negative">
        <Banner.Content>Payments are paused.</Banner.Content>
      </Banner>
      <Banner intent="info">
        <Banner.Content>Maintenance on Oct 22 at 14:00 UTC.</Banner.Content>
      </Banner>
      <Banner>
        <Banner.Content>Webhooks now retry for 24 hours.</Banner.Content>
        <Banner.Dismiss />
      </Banner>
    </div>
  )
}

namespace styles {
  export const page = style({ display: 'flex', flexDirection: 'column', width: '100% !custom' })
}
```

### Limit Dismissal to Announcements

`Banner.Dismiss` only renders the button. Remove the banner in its `onClick`, and store the dismissal so the banner doesn't return on the next page.

**Do:** Add `Banner.Dismiss` to announcements and `info` messages.

```tsx
/**
 * Do example for "Limit Dismissal to Announcements" on the Banner page.
 * Add `Banner.Dismiss` to announcements and `info` messages.
 * @module
 */
import { Banner, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <Banner intent="info">
        <Banner.Content>Maintenance starts Oct 22 at 14:00 UTC.</Banner.Content>
        <Banner.Dismiss />
      </Banner>
    </div>
  )
}

namespace styles {
  export const page = style({ display: 'flex', flexDirection: 'column', width: '100% !custom' })
}
```

**Don't:** Let people dismiss an active outage. Remove the banner when the condition ends.

```tsx
/**
 * Don't example for "Limit Dismissal to Announcements" on the Banner page.
 * Don't let people dismiss an active outage. Remove the banner when the condition ends.
 * @module
 */
import { Banner, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <Banner intent="negative">
        <Banner.Content>Payments are paused during an RPC outage.</Banner.Content>
        <Banner.Dismiss />
      </Banner>
    </div>
  )
}

namespace styles {
  export const page = style({ display: 'flex', flexDirection: 'column', width: '100% !custom' })
}
```

### Offer One Action

**Do:** Add at most one `Banner.Action`, such as View status.

```tsx
/**
 * Do example for "Offer One Action" on the Banner page.
 * Add at most one `Banner.Action`, such as View status.
 * @module
 */
import { Banner, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <Banner intent="warning">
        <Banner.Content>Deposits from Ethereum are delayed by about 20 minutes.</Banner.Content>
        <Banner.Action>View status</Banner.Action>
      </Banner>
    </div>
  )
}

namespace styles {
  export const page = style({ display: 'flex', flexDirection: 'column', width: '100% !custom' })
}
```

**Don't:** Add several actions to one banner.

```tsx
/** Don't example for "Offer One Action" on the Banner page. Don't add several actions to one banner. @module */
import { Banner, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <Banner intent="warning">
        <Banner.Content>Deposits are delayed.</Banner.Content>
        <Banner.Action>Status</Banner.Action>
        <Banner.Action>Support</Banner.Action>
        <Banner.Action>Retry</Banner.Action>
      </Banner>
    </div>
  )
}

namespace styles {
  export const page = style({ display: 'flex', flexDirection: 'column', width: '100% !custom' })
}
```

## Content

* Lead with what changed and who it affects, then what to do: Deposits from Ethereum are delayed by about 20 minutes.
* Keep it to one or two short sentences.
* Give times with a time zone, such as Maintenance starts Oct 22 at 14:00 UTC.
* Describe the condition, not the intent. Write Payments are paused, not Error or Warning.
* Name the destination in the action label, such as View status. Avoid Click here and Learn more.

## Accessibility

Renders a plain `div` with no role and no live region. The action and dismiss controls are native buttons, and the banner never takes focus.

### Semantics

* **Banner (div):** Not a landmark or live region. Screen readers read it in order, so place it before the main content.
* **Banner.Action (button):** To make it a link, pass `render` with a link and `nativeButton={false}`.
* **Banner.Dismiss (button):** Named "Dismiss" by default. Its close icon is decorative.

### Keyboard

* **Move to the Next Control (Tab):** Focuses the action, then the dismiss button.
* **Activate the Button (Enter or Space):** Activates the action or the dismiss button.

### Your Responsibilities

* **Announce Late Banners (role):** If a banner appears after page load, add `role="status"`, or `role="alert"` for an outage.
* **Move Focus on Dismiss:** After a dismissal, move focus to the start of the main content.
* **Name Each Dismiss (aria-label):** If a page has several, name each one, such as "Dismiss maintenance notice".

## Related

[Alert](/docs/components/alert)

Use for a message about one section.

[Toast](/docs/components/toast)

Use for confirming a finished action.

[AlertDialog](/docs/components/alert-dialog)

Use for a decision before an action continues.

[Feedback and Status](/docs/patterns/feedback-and-status)

Covers choosing a message component.
