Skip to main content
astrocraft-ui/ components · 101
Shop

Banner

Free · MIT

Headless, accessible, and styled entirely through the attribute surface below — bring your own CSS system, or start from the reference theme.

← BadgeCard →

Install

Without a flag you get no styling at all — plain HTML carrying the attribute surface below. --theme copies the same theme in two dialects;--bridge lumos re-points either one onto Lumos for Astro's tokens (it needs a theme to re-point, and Lumos itself, already in your project).

Unstyled — behavior only, you write the CSS

Install command
npx astrocraft-ui add display/banner

Plain-CSS theme — no build step

Install command
npx astrocraft-ui add display/banner --theme css

Tailwind theme — needs Tailwind v4

Install command
npx astrocraft-ui add display/banner --theme tailwind

Plain-CSS theme, re-pointed onto Lumos tokens

Install command
npx astrocraft-ui add display/banner --theme css --bridge lumos

Tailwind theme, re-pointed onto Lumos tokens

Install command
npx astrocraft-ui add display/banner --theme tailwind --bridge lumos

Live demo

Banner

Dismiss it and watch where the keyboard goes: focus moves to the page's main landmark rather than falling to <body>, which is what sends a screen reader back to the top of the document. Persistence is yours — listen forbanner:dismiss.

You are looking at a staging build. Data here is reset every night.

Attribute surface

With no class-merging machinery, these attributes are the whole extension point. State is a data-attribute or a native attribute; visibility is the hiddenattribute. Generated from source by pnpm slots.

ComponentSlotsVariantsRuntime stateNative state
`Banner.astro``banner`———
`BannerClose.astro``banner-close``data-variant`: `primary` · `secondary` · `outline` · `ghost`
`data-size`: `sm` · `md` · `lg`		——

Source

What the command copies — 3 files, alias-free so the copy lands standing alone. This is the whole component; there is nothing else.

src/components/ui/display/banner/Banner.astro
---
// src/components/ui/display/banner/Banner.astro — headless primitive (see ../../README.md).
// A dismissible site-wide notice — the cookie bar, the "you are viewing a staging build" strip.
// Compose a BannerClose inside it.
//
// `role="region"` with a name, rather than `role="alert"`: a banner is usually present from page
// load, and an alert that fires on every navigation is noise a screen-reader user cannot turn off.
// As a named landmark it is instead reachable on purpose, by anyone, at any point.
//
// PERSISTENCE IS YOURS. Whether a dismissal is remembered, and where — a cookie, localStorage, the
// server — is a product decision with privacy consequences, so the library does not guess: it hides
// the banner and dispatches a bubbling `banner:dismiss` you can listen for.
//
// WHAT IS OURS is where the keyboard goes afterwards. Hiding the element that currently has focus
// drops focus to <body>, and most screen readers respond by jumping back to the top of the document
// — so the user is punished with the whole page again for having dismissed a notice. The script
// moves focus to the main landmark instead, which is where someone who just cleared a banner out of
// the way was trying to get.
import type { HTMLAttributes } from "astro/types";

type Props = HTMLAttributes<"div"> & { label?: string };

const { label = "Notice", class: className, ...rest } = Astro.props;
---

<div role="region" aria-label={label} class={className} data-slot="banner" {...rest}>
  <slot />
</div>

<script>
  import { onReadyOnce } from "../../_once";

  function wire(banner: HTMLElement) {
    banner.addEventListener("click", (event) => {
      if (!(event.target instanceof Element)) return;
      if (!event.target.closest('[data-slot="banner-close"]')) return;

      banner.hidden = true;
      banner.dispatchEvent(new Event("banner:dismiss", { bubbles: true }));

      // `tabindex="-1"` makes the landmark focusable without adding a tab stop — the same trick
      // FormErrorSummary uses. Body is the fallback for a page with no <main>.
      const landing = document.querySelector<HTMLElement>("main") ?? document.body;
      landing.tabIndex = -1;
      landing.focus({ preventScroll: true });
    });
  }

  onReadyOnce('[data-slot="banner"]', wire);
</script>
src/components/ui/display/banner/BannerClose.astro
---
// src/components/ui/display/banner/BannerClose.astro — Banner compound part (see ../../README.md).
// Dismisses the Banner it sits inside; wired by the Banner's delegated listener.
//
// `label` is the accessible name, and it should say WHICH notice is going away — a page can carry
// more than one banner, and three buttons all announced as "Dismiss" tell a screen-reader user
// nothing about which is which.
import type { HTMLAttributes } from "astro/types";

type Props = HTMLAttributes<"button"> & {
  label?: string;
  variant?: "primary" | "secondary" | "outline" | "ghost";
  size?: "sm" | "md" | "lg";
};

const {
  label = "Dismiss",
  variant = "ghost",
  size = "sm",
  class: className,
  ...rest
} = Astro.props;
---

<button
  type="button"
  aria-label={label}
  data-slot="banner-close"
  data-variant={variant}
  data-size={size}
  class={className}
  {...rest}
>
  <slot />
</button>
src/components/ui/display/banner/index.ts
import Banner from "./Banner.astro";
import BannerClose from "./BannerClose.astro";

export { Banner, BannerClose };
export default Banner;

What you get

The component source, copied into your project by npx astrocraft-ui add display/banner — no package dependency, no CSS to fight. Whatever the paid blocks compose, this is it.