Banner

Server component with client leaf BannerDismiss

ImportCopy Anchor Link

import { Banner, BannerDismiss } from '@nizivo/react/banner';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css and @nizivo/react/css/icon-button.css
import '@nizivo/react/css/banner.css';

Static or interactiveCopy Anchor Link

Server, with one client leaf. Banner renders on the server and ships no JavaScript. BannerDismiss, passed in dismiss, is the only part that hydrates; leave it out for a banner that blocks work and must stay. The Banner does not hide itself: onDismiss updates your state, or is a Server Action, and the page stops rendering it. How to choose.

In a client app (a Vite or React Router single-page app, or a 'use client' file) it is an ordinary React component: event handlers, refs and state work as usual. In a client app.

Banner or AlertCopy Anchor Link

A Banner speaks to the whole page, under the header: a promotion, a plan about to renew. Show one at a time. An Alert sits next to the content it is about, inside a form or a card.

TonesCopy Anchor Link

brand (the default) is Figma's Promo, on bg/brand-subtle, usually with media: a 72 px picture before the text, such as a product render (<img alt="" width={72} height={72} />; it is decorative). warning is on bg/warning-subtle, usually with an icon at 24 px. Figma names the first tone "Promo"; code calls it brand, as Badge and Card do (a question for design, handoff Q25).

LayoutCopy Anchor Link

Figma's row: 16 / 24 px padding, 20 px between parts, the title (Heading/H4) and its line (Body/M) in a column, the action and the dismiss after it, all centred. With less room the action wraps under the text, and the dismiss stays at the row's end. Hooks: --nz-banner-bg, --nz-banner-gap, --nz-banner-padding-block, --nz-banner-padding-inline, --nz-banner-radius, --nz-banner-title-font, --nz-banner-description-font, --nz-banner-dismiss-fg.

The dismiss buttonCopy Anchor Link

<BannerDismiss /> is a tertiary IconButton, 40 px (the action's height) with a 20 px close glyph (Figma draws 18, which has no icon token), named "Dismiss" (labels={{ dismiss: '…' }} or aria-label). With render, your element. A page that imports per-component stylesheets needs css/icon-button.css too.

Screen readersCopy Anchor Link

A banner has no live role by default: one that is on the page when it loads must not interrupt. For one added after a user action, pass role="status", or say it with announce() from @nizivo/react/toast.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Button } from '@nizivo/react/button';
import { Banner } from '@nizivo/react/banner';

/** A stand-in for a product render (use `<img alt="" width={72} height={72} />`). */
function Render(): JSX.Element {
  return (
    <svg viewBox="0 0 72 72" width="72" height="72" fill="none" stroke="currentColor">
      <rect x="14" y="20" width="44" height="38" rx="6" />
      <path d="M14 32h44M28 20v12M44 20v12" />
    </svg>
  );
}

export function BannerExample(): JSX.Element {
  return (
    <Banner
      media={<Render />}
      title="Open a second storefront in minutes"
      action={<Button variant="primary">Add storefront</Button>}
    >
      Sell in EUR and GBP from the same catalogue.
    </Banner>
  );
}

import type { JSX } from 'react';
import { Button } from '@nizivo/react/button';
import { Banner, BannerDismiss } from '@nizivo/react/banner';

/** A stand-in for `@nizivo/icons`' triangle-alert. */
function Warning(): JSX.Element {
  return (
    <svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor">
      <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" />
      <path d="M12 9v4M12 17h.01" />
    </svg>
  );
}

export function BannerWarningExample({ onDismiss }: { onDismiss?: () => void }): JSX.Element {
  return (
    <Banner
      tone="warning"
      icon={<Warning />}
      title="Your plan renews in 3 days"
      action={<Button>Update card</Button>}
      dismiss={<BannerDismiss {...(onDismiss && { onDismiss })} />}
    >
      Update the card on file to avoid interruption.
    </Banner>
  );
}

PropsCopy Anchor Link

Other exportsCopy Anchor Link

BannerDismissLabels type

import type { BannerDismissLabels } from '@nizivo/react/banner'

Strings this part renders (§16.4).

Name	Type	Default	Description
dismissrequired	string	'Dismiss'	The button's accessible name.

BannerDismissProps type

import type { BannerDismissProps } from '@nizivo/react/banner'

The props of BannerDismiss, listed above.

BannerProps type

import type { BannerProps } from '@nizivo/react/banner'

The props of Banner, listed above.

BannerState type

import type { BannerState } from '@nizivo/react/banner'

The render state of Banner, listed above.

BannerTone type

import type { BannerTone } from '@nizivo/react/banner'

Figma "Tone": brand is Figma's Promo (handoff Q25, D-bq).

type BannerTone = "brand" | "warning"

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-banner, .nz-banner-action, .nz-banner-content, .nz-banner-description, .nz-banner-dismiss, .nz-banner-icon, .nz-banner-media, .nz-banner-title, .nz-icon-button.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• banner-dismiss: draws the focus outline itself on keyboard focus.

KeyboardCopy Anchor Link

Source: Native <button> elements; no engine. Checked by the browser lane (test/browser/banner.spec.tsx) in Chromium, Firefox and WebKit.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: Figma node 7275:15120
• Ghost masters: Figma node 756:913