# Banner

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/banner
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=299-282

```tsx
import { Banner } from '@commenda/pathfinder/banner';
<Banner
  tone="info"
  description="Review the filing details before submitting."
/>;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Styles are precompiled with Tailwind v4; consumers need no Tailwind scanning. Interactive callbacks belong in client components in Next.js App Router.

## Usage [#usage]

```tsx
import { Banner } from '@commenda/pathfinder/banner';
<Banner
  tone="info"
  description="Review the filing details before submitting."
/>;
```

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `description` | `string` | required | Required |
| `title` | `string` | optional | Optional; unavailable for announcement |
| `tone` | `FeedbackTone \| "announcement"` | conditional | neutral |
| `actionConfig` | `FeedbackAction` | optional | One link; secondary button for announcement |
| `dismissConfig` | `DismissConfig` | optional | Optional close control |
| `open` | `boolean` | conditional | Controlled / uncontrolled; true initially |
| `defaultOpen` | `boolean` | optional | Controlled / uncontrolled; true initially |
| `onOpenChange` | `((open: boolean) => void)` | conditional | Required with open |
| `announcement` | `FeedbackAnnouncement` | optional | auto |
| `className` | `string` | optional | Additional classes for the component root. |

### dismissConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | No |  |
| `onDismiss` | `(() => void)` | No |  |

Place below the breadcrumb at the top of the content card. Use one banner at a time for account or product context, never a single record. Announcement centers the message and omits icon and title. Copy wraps on narrow screens. Dismissal follows Alert’s controlled-state and completion-callback rules; nothing expires automatically.

### Actions [#actions]

`FeedbackAction` requires a label and exactly one of `onClick` (command) or `href` (native navigation). Commands support `disabled`, `disabledReason`, `loadingConfig`, and `leadingIcon`; navigation supports `target`, `rel`, and `leadingIcon`. The application owns async work and retry state.

## Examples [#examples]

### Tones [#tones]


```tsx
<>
  {(['neutral', 'info', 'success', 'warning', 'error'] as const).map((tone) => (
    <Banner
      key={tone}
      tone={tone}
      description="Review the filing details before submitting."
    />
  ))}
</>;
```


### Actions [#actions-1]


```tsx
<Banner
  tone="info"
  description="Review the filing details before submitting."
  actionConfig={{ label: 'Review filing', onClick: onReviewFiling }}
/>;
```


### Announcement [#announcement]


```tsx
<Banner
  tone="announcement"
  description="Review the filing details before submitting."
  actionConfig={{ label: 'Review filing', onClick: onReviewFiling }}
/>;
```


### Dismissible [#dismissible]


```tsx
<Banner
  tone="info"
  description="Review the filing details before submitting."
  dismissConfig={{}}
/>;
```


Read the [design guidance](/docs/components/banner#design-rules) before using these components.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Alert and Banner — 299:2 [#alert-and-banner--2992]

- **ALERT-01:** Persistent, contextual feedback beside the form, table or figure it concerns. Never auto-dismiss. No dismissConfig produces a callout that stays until the owner removes it. Field errors remain on fields; form alerts summarize them.
- **ALERT-02:** Title states what happened without a period; description states the next step. Aim for two lines, but never clip essential text. At most a secondary small Button for recovery plus a link for more information. Passing confirmations use Toast.
- **ALERT-03:** Neutral is a state, info is news, success is completion, warning is an approaching issue, error is a current problem. Auto announcement maps warnings/errors to alert and info/success to status; neutral stays nonurgent. The explicit announcement prop can override this for the actual event.
- **ALERT-04:** Tinted background and 0.5 px border, radius 8, padding 12 vertical/16 start/12 end, gap 10; icon 16, Label/13 Strong title, Copy/13 body, gap 2. Close uses plain IconButton xs on tinted surfaces.
- **BANNER-01:** Whole-account or product context only; place beneath the breadcrumb across the content card. One at a time, one concise message, one link. The application owns placement and prioritization. Wrap on narrow screens rather than truncate.
- **BANNER-02:** Announcement is the sixth banner tone from node 917:314: blue 100/background, blue 300 bottom border, centered blue 900 copy, no icon or title, optional secondary small Button.
- **FEEDBACK-DISMISS-01:** Dismissal fades and collapses space over 200 ms, ease-out. onOpenChange requests closure immediately; onDismiss follows the collapse after an accepted close. A controlled owner can reject the request. The owner restores focus if needed.
- **FEEDBACK-ACTION-01:** Commands use Button; navigation uses native anchors. Require a label and exactly one of onClick or href. Components choose action appearance; callers own loading, disabled reasons and async behavior.