Banner

A floating top-of-viewport notification for global, non-blocking feedback. Supports semantic states, optional action, dismiss behavior, and timed or persistent visibility.

When to use

✓Use banner for global, top-lane, non-blocking announcements that affect the current page or session.
✓Use success/info states for broad confirmations or context updates.
✓Use warning/error for urgent account, billing, or availability messages requiring visibility.
✓Use actionLabel when users need a direct next step from the announcement.
✓Use persistent mode for conditions that remain true until user context changes.

Don't

✕Do not stack multiple banners at once; keep one top-lane message active at a time.
✕Do not use banner for localized form feedback; prefer inline notifications near the field or section.
✕Do not use banner for ephemeral confirmations where toast is more appropriate.
✕Do not put critical blocking workflows behind banner-only messaging; use modal flows when acknowledgment is required.

Banner vs Inline Notification vs Toast

Component	Best for
Banner	Global top-of-page context and announcements spanning the current view.
Inline Notification	Local, in-flow feedback tied to a specific section or task area.
Toast	Brief, transient, auto-dismissing status updates that should not take layout space.

Behavior rules

persistent takes precedence over duration and disables auto-dismiss.
Set duration to a value above 0 only when the message is safe to auto-dismiss.
Keep heading concise and description actionable. Prefer one clear action label when needed.

Integration examples

Vanilla JS

<diwa-banner
  id="global-notice"
  open
  state="warning"
  heading="Service degradation"
  description="Realtime insights are delayed. Core actions still work."
  action-label="View status"
></diwa-banner>

<script>
  const banner = document.getElementById('global-notice');
  banner.addEventListener('action', () => window.location.assign('/status'));
  banner.addEventListener('dismiss', () => banner.remove());
</script>

React

import { useState } from 'react';

export function UpgradeBanner() {
  const [open, setOpen] = useState(true);

  return (
    <diwa-banner
      open={open}
      state="info"
      heading="New plan available"
      description="Upgrade to unlock team analytics."
      actionLabel="View plans"
      ondismiss={() => setOpen(false)}
    />
  );
}