Banner

Installation

1. Install the package.

npm install @hashintel/ds-components

2. Import the component.

import { Banner } from "@hashintel/ds-components";

export const PermissionsChangeBanner = () => (
  <Banner tone="warning">
    <Banner.Title>Workspace permissions are changing</Banner.Title>
    <Banner.Description>
      Members inherited from parent teams must be re-added by 1 November.
    </Banner.Description>
  </Banner>
);

When to use

When not to use

Anatomy

<Banner tone="neutral">
  <Banner.Title>Title</Banner.Title>
  <Banner.Description>Description</Banner.Description>
  <Banner.Actions>
    <Banner.ActionButton>Action</Banner.ActionButton>
  </Banner.Actions>
</Banner>

Examples

Basic

Description only

Most banners don't need a title — a lone Banner.Description keeps a short status to a single line.

Tones

tone sets the palette and the default icon: neutral for routine context, brand for product messages, success to confirm, warning to forewarn, and error for failures that need attention now.

Variants

soft (the default) tints the surface for messages in the page flow. outline sits flat on opaque surfaces such as cards and dialogs. solid is a saturated fill — reserve it for the most prominent page-level messages.

With actions

Wrap Banner.ActionButtons in Banner.Actions so users can resolve the condition in place — prefer one or two. Action buttons default to a compact secondary treatment, and the solid variant restyles them to read on the fill; pass an explicit variant to opt out.

Dismissible

Pass dismissible with an onDismiss callback to render a trailing dismiss button. Dismissing doesn't automatically remove the banner — you must handle it via the callback. Make banners dismissible unless they carry critical information or a required action.

import { useState } from "react";

import { Banner } from "@hashintel/ds-components";

export const EditorTipBanner = () => {
  const [dismissed, setDismissed] = useState(false);

  if (dismissed) {
    return null;
  }

  return (
    <Banner tone="brand" dismissible={{ onDismiss: () => setDismissed(true) }}>
      <Banner.Description>
        {"Tip: drag a property onto the canvas to add it to the entity type."}
      </Banner.Description>
    </Banner>
  );
};

Leading icon

icon defaults to true, the tone's own icon — keep it unless a more specific glyph adds meaning. Pass { iconName } for a named design-system icon, or false for none. Pass icon={{ custom }} to lead with any node

Custom children

Children that aren't Banner.Actions render in the message column, so custom markup can replace or sit alongside the built-in parts. Custom content doesn't pick up the tone's text color — set your own.

Behavior

• When the banner runs narrow, the actions wrap beneath the message instead of squeezing it into a narrow column.

Content

• Lead the title with what happened, as a short sentence: "Workspace permissions are changing". Use sentence case and no trailing period.
• Keep descriptions to 1–2 sentences: what happened, then what to do about it.
• For warning and error banners, always say how to resolve the condition.
• Write action labels verb-first, 1–3 words: "Review changes", "Retry sync".
• Don't write severity into the copy ("Error:", "Warning!") — the tone's icon and color already carry it.

Accessibility

A banner that announces an urgent problem should implement the WAI-ARIA alert pattern.

What Banner provides

• Banner.Title renders a real heading — h2 by default, but this can be adjusted with as.
• No ARIA role is set by default — a banner rendered with the page needs none.

What you must do

• Set role="status" on banners inserted after load so screen readers announce them politely; reserve role="alert" for urgent failures — it interrupts whatever is being read.
• Choose the Banner.Title heading level with as so it slots into the page's heading outline.

API reference

Banner

Banner.Title

Banner.Description

Banner.Actions

Banner.ActionButton