unstable_Banner API

Import

import { unstable_Banner as Banner } from "@stratakit/structures";
// OR
import * as Banner from "@stratakit/structures/unstable_Banner";

Banner (default)

Base element: <div>

A banner to highlight information and also optionally provide actions. The information could be very important (like a call to action) or reasonably import (like a status message).

Example:

<Banner label="Label" message="Message" icon={placeholderIcon} onDismiss={() => {}} />

label

Type: string | Element (required)

The label of the banner.

Either pass a string or a <VisuallyHidden> component if you don’t want the label to be visible.

message

Type: ReactNode (required)

The message content of the banner.

actions

Type: ReactNode (optional)

The actions available for the banner.

Example with one action:

actions={<Button key={…} onClick={}>Action</Button>}

Example with two Buttons:

actions={
  <>
    <Button key={…} onClick={…}>Action 1</Button>,
    <Button key={…} onClick={…}>Action 2</Button>,
  </>
}

Example with two Anchors as Button:

actions={
  <>
    <Anchor key={…} render={<button />} onClick={…}>Action 1</Anchor>,
    <Anchor key={…} render={<button />} onClick={…}>Action 2</Anchor>,
  </>
}

icon

Type: string | Element | undefined (optional)

A static icon decoration for the banner.

Can be a URL of an SVG from the @stratakit/icons package, or a custom JSX icon.

• If no icon is passed and the tone is "neutral", no icon is shown.
• If no icon is passed and the tone is not "neutral", the status icon is shown.

onDismiss

Type: (() => void) | undefined (optional)

Default: undefined

Callback invoked when the dismiss (”❌”) button is clicked.

If undefined, the dismiss button will not be rendered.

render

Type: (props: P) => React.ReactNode | React.ReactElement | undefined (optional)

Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged.

Check out the Composition guide for more details.

tone

Type: "neutral" | "info" | "positive" | "attention" | "critical" | undefined (optional)

Default: "neutral"

The tone of the banner.

variant

Type: "outline" | undefined (optional)

Default: "outline"

The variant of the banner.

Banner.Root

Base element: <div>

A banner to highlight information and also optionally provide actions. The information could be very important (like a call to action) or reasonably import (like a status message).

Example:

<Banner.Root tone="info" variant="outline">
  <Banner.Icon />
  <Banner.Label>Label</Banner.Label>
  <Banner.Message>Message</Banner.Message>
  <Banner.DismissButton onClick={onDismiss} />
</Banner.Root>

tone

Type: "neutral" | "info" | "positive" | "attention" | "critical" | undefined (optional)

Default: "neutral"

The tone of the banner.

variant

Type: "outline" | undefined (optional)

Default: "outline"

The variant of the banner.

Additional props

• render

Banner.Icon

Base element: <svg>

A static icon decoration for the banner.

• If no href is passed and the tone is "neutral", no icon is shown.
• If no href is passed and the tone is not "neutral", the status icon is shown.

Example with default status icon:

<Banner.Root tone="info">
  <Banner.Icon />
</Banner.Root>

Example with custom icon:
```tsx
import svgPlaceholder from "@stratakit/icons/placeholder.svg";

<Banner.Root>
  <Banner.Icon href={svgPlaceholder} />
</Banner.Root>

alt

Type: string | undefined (optional)

Alternative text describing the icon.

When this prop is passed, the SVG gets rendered as role="img" and labelled using the provided text.

This prop is not required if the icon is purely decorative. By default, the icon will be hidden from the accessibility tree.

href

Type: string | undefined (optional)

URL of the .svg file (e.g. from @stratakit/icons).

The URL can contain a hash pointing to a specific symbol within the SVG (e.g. #icon, #icon-large). By default, the #icon symbol is used if no hash is provided.

Note: The .svg must be an external HTTP resource for it to be processed by the <use> element. As a fallback, JS will be used to fetch the SVG from non-supported URLs; the fetched SVG content will be sanitized using the unstable_htmlSanitizer function passed to <Root>.

key

Type: Key | null | undefined (optional)

ref

Type: Ref<HTMLElement | SVGSVGElement> | undefined (optional)

Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref).

render

Type: (props: P) => React.ReactNode | React.ReactElement | undefined (optional)

Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged.

Check out the Composition guide for more details.

size

Type: "regular" | "large" | undefined (optional)

Size of the icon. This only affects the icon’s physical dimensions (not the SVG contents).

Defaults to "regular" (16px) and can be optionally set to "large" (24px).

Banner.Label

Base element: <span>

The label of the banner.

Pass render={<VisuallyHidden />} if you don’t want the label to be visible.

Example:

<Banner.Root>
  <Banner.Label>Label</Banner.Label>
</Banner.Root>

Example with a visually hidden label:

<Banner.Root>
  <Banner.Label render={<VisuallyHidden />}>Label</Banner.Label>
</Banner.Root>

Additional props

• render

Banner.Message

Base element: <span>

The message content of the banner.

Example:

<Banner.Root>
  <Banner.Message>Message content goes here.</Banner.Message>
</Banner.Root>

Additional props

• render

Banner.Actions

Base element: <div>

The actions available for the banner.

Example with one action:

<Banner.Root>
  <Banner.Actions>
    <Button key={…} onClick={…}>Action</Button>
  </Banner.Actions>
</Banner.Root>

Example with two Buttons:

<Banner.Root>
  <Banner.Actions>
    <Button key={…} onClick={…}>Action 1</Button>
    <Button key={…} onClick={…}>Action 2</Button>
  </Banner.Actions>
</Banner.Root>

Example with two Anchors as Button:

<Banner.Root>
  <Banner.Actions>
    <Anchor key={…} render={<button />} onClick={…}>Action 1</Anchor>,
    <Anchor key={…} render={<button />} onClick={…}>Action 2</Anchor>,
  </Banner.Actions>
</Banner.Root>

Additional props

• render

Banner.DismissButton

Base element: <button>

Dismiss (”❌”) button for the banner. Handle the onClick callback to dismiss the banner.

Example:

<Banner.Root>
  <Banner.DismissButton onClick={() => {}} />
</Banner.Root>

label

Type: string | undefined (optional)

Default: "Dismiss"

Label for the dismiss button.

The final accessible name of the dismiss button is a combination of this label and the text content of Banner.Label.

Additional props

• render