XDS — Design System

XDSBanner@xds/core · Banner

Preview coming soon

Usage

Banner shows a persistent message at the top of a page or section. Use it for form errors, system updates, maintenance notices, or success confirmations that the user needs to see until they act on it.

Best practices

Guidance	Practices
Do	Pick a status that matches the message: info for updates, warning for caution, error for problems, success for confirmations.
Do	Use the card container inside page content and the section container for full-width messages that span the entire page.
Do	Make info and success banners dismissable. Keep error banners visible until the user fixes the issue.
Do	Keep titles short and scannable — "Payment failed" not "There was a problem processing your most recent payment."
Don't	Use Banner for short-lived messages that disappear on their own — use Toast instead.
Don't	Stack multiple banners with the same status — combine related messages into one banner.

Anatomy

Element		Description
Icon	required	Automatically set based on the status (info, warning, error, success).
Title		The main message. Required if no description is provided.
Description		Additional detail below the title. Required if no title is provided.
Action button		A button for the user to act on the message, like "Review" or "Retry".
Dismiss button		Lets the user close the banner. Enabled by setting isDismissable.
Collapsible content		Extra detail that expands below the banner header, like a list of errors.

Import

ts
import {XDSBanner} from '@xds/core/Banner'

Props

Prop	Type	Description
statusrequired	'info' \| 'warning' \| 'error' \| 'success'	Status type controlling icon and color.
titlerequired	ReactNode	Title text or ReactNode displayed in the header.
description	ReactNode	Description text rendered below the title in the header.
icon	ReactNode	Override the default status icon.
isDismissable	boolean (default: false)	Whether the banner can be dismissed by the user.
onDismiss	() => void	Called when the dismiss button is clicked; banner hides itself regardless of whether this is provided.
endContent	ReactNode	Action content rendered in the header area, end-aligned. Typically a button or link.
container	'card' \| 'section' (default: 'card')	Container type: card has border-radius; section is full-width with no border-radius for page-level use.
children	ReactNode	Content rendered in the card-background area below the colored header.
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

Examples

Common configurations, variations, and states.

Banner — ActionAdd a button to a banner so the user can act on the message. Use for trial expirations, payment failures, or anything that needs a response.

tsx
'use client';
import {XDSBanner} from '@xds/core/Banner';
import {XDSButton} from '@xds/core/Button';
import {XDSStack} from '@xds/core/Layout';
export default function BannerWithActionButton() {
  return (
    <XDSStack direction="vertical" gap={3}>
      <XDSBanner
        status="info"
        title="Your trial expires in 3 days"
        description="Upgrade now to keep access to all features."
        endContent={<XDSButton label="Upgrade" variant="secondary" size="sm" />}
      />
      <XDSBanner
        status="warning"
        title="API key expires soon"
        description="Generate a new key before December 1 to avoid service interruption."
        endContent={
          <XDSButton label="Renew key" variant="secondary" size="sm" />
        }
      />
      <XDSBanner
        status="error"
        title="Payment failed"
        description="We could not process your last payment."
        endContent={<XDSButton label="Retry" variant="secondary" size="sm" />}
      />
    </XDSStack>
  );
}

Banner — CollapsibleCombine an action button, dismiss control, and expandable detail area in one banner. Use for complex notifications like config changes or deployment summaries.

tsx
'use client';
import {XDSBanner} from '@xds/core/Banner';
import {XDSButton} from '@xds/core/Button';
import {XDSList, XDSListItem} from '@xds/core/List';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function BannerCollapsibleContent() {
  return (
    <XDSBanner
      status="warning"
      title="Configuration changes detected"
      description="Review the changes before they take effect."
      endContent={<XDSButton label="Review" variant="secondary" size="sm" />}
      isDismissable
      defaultIsExpanded>
      <XDSStack direction="vertical" gap={2}>
        <XDSText type="supporting" color="secondary">
          Changed settings:
        </XDSText>
        <XDSList density="compact">
          <XDSListItem label="Authentication method updated" />
          <XDSListItem label="Rate limits modified" />
        </XDSList>
      </XDSStack>
    </XDSBanner>
  );
}

Banner — DismissLet the user close a banner after reading it. Use for maintenance notices, feature tips, or any non-critical message the user can acknowledge.

tsx
'use client';
import {XDSBanner} from '@xds/core/Banner';
import {XDSStack} from '@xds/core/Layout';
export default function BannerDismissable() {
  return (
    <XDSStack direction="vertical" gap={3}>
      <XDSBanner
        status="success"
        title="Deployment complete"
        description="Version 3.2.0 is now live in production."
        isDismissable
      />
      <XDSBanner
        status="warning"
        title="Scheduled maintenance tonight"
        description="The system will be briefly unavailable from 2:00–3:00 AM."
        isDismissable
      />
      <XDSBanner
        status="info"
        title="New feature available"
        description="Try the new dashboard layout in Settings."
        isDismissable
      />
    </XDSStack>
  );
}

Banner — Full WidthA full-width banner with no border radius for page-level notifications. Use at the top of a page for site-wide announcements or maintenance alerts.

tsx
'use client';
import {XDSBanner} from '@xds/core/Banner';
import {XDSButton} from '@xds/core/Button';
import {XDSStack} from '@xds/core/Layout';
export default function BannerSectionVariant() {
  return (
    <XDSStack direction="vertical" gap={3}>
      <XDSBanner
        status="warning"
        title="Scheduled downtime"
        description="All services will be unavailable on Sunday from 2:00–4:00 AM."
        container="section"
        isDismissable
      />
      <XDSBanner
        status="info"
        title="Welcome to the new dashboard"
        description="We have redesigned the layout based on your feedback."
        container="section"
        endContent={
          <XDSButton label="Take a tour" variant="secondary" size="sm" />
        }
      />
    </XDSStack>
  );
}

Banner — StatusesAll 4 banner statuses: info, success, warning, and error. Use to show persistent messages like updates, confirmations, cautions, or problems at the top of a page or section.

tsx
'use client';
import {XDSBanner} from '@xds/core/Banner';
import {XDSStack} from '@xds/core/Layout';
export default function BannerStatuses() {
  return (
    <XDSStack direction="vertical" gap={3}>
      <XDSBanner
        status="info"
        title="A new software update is available"
        description="Version 2.4.1 includes performance improvements and bug fixes."
      />
      <XDSBanner
        status="success"
        title="Changes saved"
        description="Your profile information has been updated successfully."
      />
      <XDSBanner
        status="warning"
        title="Storage almost full"
        description="You have used 90% of your available storage."
      />
      <XDSBanner
        status="error"
        title="Build failed"
        description="3 tests did not pass. Check the logs for details."
      />
    </XDSStack>
  );
}

Showcase source

tsx
'use client';
import {XDSBanner} from '@xds/core/Banner';
import {XDSStack} from '@xds/core/Layout';
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
  root: {
    maxWidth: 800,
  },
});
export default function BannerShowcase() {
  return (
    <XDSStack direction="vertical" gap={3} xstyle={styles.root}>
      <XDSBanner status="info" title="A new software update is available." />
      <XDSBanner status="success" title="Your changes have been saved." />
      <XDSBanner
        status="warning"
        title="Your trial expires in 3 days."
        description="Upgrade to keep access to all features."
      />
      <XDSBanner
        status="error"
        title="Payment failed."
        description="Update your billing information to continue."
      />
    </XDSStack>
  );
}