# Banner

> A full-width, page-level announcement such as maintenance windows or plan limits.

Category: Feedback · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/banner

Banner spans the top of the page or app shell and applies to the whole product, not one section. The default brand tone uses inverse ivory and indigo; status tones communicate urgency. Show at most one banner at a time and let people dismiss non-critical ones.

## Import

```tsx
import { Banner } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Brand announcement

```tsx
import { Banner } from '@bindshq/stance-react';

export function Basic() {
  return (
    <Banner dismissible action={<a href="#outlook">See what’s new</a>}>
      The eSignify Outlook add-in is now available for every plan.
    </Banner>
  );
}
```

### Tones

```tsx
import { Banner } from '@bindshq/stance-react';

export function Tones() {
  return (
    <div style={{ display: 'grid', gap: 8 }}>
      <Banner tone="info" label="Information">
        Directory sync now runs every hour.
      </Banner>
      <Banner tone="success" label="Success">
        Your organisation is verified.
      </Banner>
      <Banner tone="warning" label="Plan limit" action={<a href="#billing">Add seats</a>}>
        You have used 48 of 50 seats.
      </Banner>
      <Banner tone="danger" label="Service status">
        Deployments are paused while Exchange Online is degraded.
      </Banner>
    </div>
  );
}
```

### Controlled dismissal

Persist dismissal yourself, e.g. in user settings.

```tsx
import * as React from 'react';
import { Banner, Button } from '@bindshq/stance-react';

export function Controlled() {
  const [open, setOpen] = React.useState(true);
  return (
    <div style={{ display: 'grid', gap: 12, justifyItems: 'start' }}>
      <Banner tone="warning" dismissible open={open} onOpenChange={setOpen} label="Maintenance">
        Scheduled maintenance on Sunday, 02:00 to 03:00 GMT.
      </Banner>
      {!open && (
        <Button size="sm" variant="outline" onClick={() => setOpen(true)}>
          Restore banner
        </Button>
      )}
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Banner | `tone` | `'brand' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'brand'` | Visual tone. |
| Banner | `children` | `ReactNode` | None | The message. |
| Banner | `action` | `ReactNode` | None | A link or button after the message. |
| Banner | `icon` | `ReactNode \| false` | None | Custom or hidden icon (status tones show one by default). |
| Banner | `dismissible` | `boolean` | `false` | Show a dismiss button. |
| Banner | `open / defaultOpen / onOpenChange` | `boolean / boolean / (open: boolean) => void` | `defaultOpen: true` | Visibility state. |
| Banner | `label` | `string` | `'Announcement'` | Accessible region name. |
| Banner | `dismissLabel` | `string` | `'Dismiss announcement'` | Dismiss button label. |

## Accessibility

- Rendered as a labelled <section> region so it can be found from the landmarks list.
- It is not a live region: content present on load is read in order. For urgent changes after load, use Alert or Toast.
- The dismiss button has an explicit accessible name.

## Guidelines

**Do**

- Keep the message to one sentence with one action.
- Remember dismissal across sessions.

**Don’t**

- Use banners for marketing on every page.
- Show several banners at once.

## Related

- https://stanceui.com/components/alert
- https://stanceui.com/components/toast