Dropdown
Free · MITHeadless, accessible, and styled entirely through the attribute surface below — bring your own CSS system, or start from the reference theme.
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
npx astrocraft-ui add overlays/dropdownPlain-CSS theme — no build step
npx astrocraft-ui add overlays/dropdown --theme cssTailwind theme — needs Tailwind v4
npx astrocraft-ui add overlays/dropdown --theme tailwindPlain-CSS theme, re-pointed onto Lumos tokens
npx astrocraft-ui add overlays/dropdown --theme css --bridge lumosTailwind theme, re-pointed onto Lumos tokens
npx astrocraft-ui add overlays/dropdown --theme tailwind --bridge lumosLive demo
Dropdown
Menu parts in a Dropdown
The same parts compose into the Dropdown that shipped in v1. Build such a menu from the new parts OR from plain DropdownItems, not both — the note in_menu.ts explains which controller claims the arrow keys and why the freeze on _popover.ts is worth the constraint.
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.
| Component | Slots | Variants | Runtime state | Native state |
|---|---|---|---|---|
| `Dropdown.astro` | `dropdown` | — | — | — |
| `DropdownItem.astro` | `dropdown-item` | — | — | — |
| `DropdownMenu.astro` | `dropdown-menu` | `data-align`: `start` · `end` | — | `:popover-open` |
| `DropdownTrigger.astro` | `chevron` `dropdown-trigger` | `data-variant`: `primary` · `secondary` · `outline` · `ghost` `data-size`: `sm` · `md` · `lg` | — | `[aria-expanded]` |
Source
What the command copies — 5 files, alias-free so the copy lands standing alone. This is the whole component; there is nothing else.
---
// src/components/ui/overlays/dropdown/Dropdown.astro — headless primitive (see ../../README.md).
// Dropdown on the native Popover API: a DropdownTrigger toggles the DropdownMenu it points at (by id),
// which renders in the top layer — so it's never clipped by an ancestor's overflow — with native
// light-dismiss + Escape and native focus-return to the trigger. The shared `_popover` controller
// (also driving MegaMenu) positions the menu under its trigger, reflows it on scroll/resize, adds
// arrow-key roving (Up/Down/Home/End), and syncs `aria-expanded` (which also flips the trigger
// chevron). Compose DropdownTrigger / DropdownMenu / DropdownItem.
import type { HTMLAttributes } from "astro/types";
type Props = HTMLAttributes<"div">;
const { class: className, ...rest } = Astro.props;
---
<div class={className} data-slot="dropdown" {...rest}>
<slot />
</div>
<script>
import "../../_popover";
</script>
---
// src/components/ui/overlays/dropdown/DropdownItem.astro — Dropdown compound part (see ../../README.md).
// Menu item; renders <a> when `href` is set, otherwise a <button>. Activating it closes the dropdown
// (handled by the shared `_popover` controller). role="menuitem".
import type { HTMLAttributes } from "astro/types";
type Props = HTMLAttributes<"button"> & { href?: string };
const { href, class: className, ...rest } = Astro.props;
const Tag = href ? "a" : "button";
---
<Tag
href={href}
type={href ? undefined : "button"}
role="menuitem"
data-slot="dropdown-item"
class={className}
{...rest}
>
<slot />
</Tag>
---
// src/components/ui/overlays/dropdown/DropdownMenu.astro — Dropdown compound part (see ../../README.md).
// Top-layer menu via the native Popover API (`popover="auto"`): hidden until its DropdownTrigger
// (`popovertarget` = this menu's `id`) toggles it, with native light-dismiss + Escape. `id` is
// required (the trigger references it). `align` tells the Dropdown script which trigger edge to anchor
// to; the script sets `top`/`left` (the menu is `fixed`). role="menu".
import "../../../../styles/structure.css";
import type { HTMLAttributes } from "astro/types";
type Props = HTMLAttributes<"div"> & { id: string; align?: "start" | "end" };
const { align = "start", class: className, ...rest } = Astro.props;
---
<div
popover="auto"
role="menu"
data-slot="dropdown-menu"
data-align={align}
class={className}
{...rest}
>
<slot />
</div>
---
// src/components/ui/overlays/dropdown/DropdownTrigger.astro — Dropdown compound part (see ../../README.md).
// Button that toggles the DropdownMenu whose `id` equals this trigger's `for`, via the native
// Popover API (`popovertarget`). The shared `_popover` controller syncs `aria-expanded`; a theme
// rotates the chevron off it — `[data-slot="dropdown-trigger"][aria-expanded="true"] [data-slot="chevron"]`.
import type { HTMLAttributes } from "astro/types";
import Chevron from "../../_Chevron.astro";
type Props = HTMLAttributes<"button"> & {
for: string;
variant?: "primary" | "secondary" | "outline" | "ghost";
size?: "sm" | "md" | "lg";
};
const { for: target, variant = "outline", size = "md", class: className, ...rest } = Astro.props;
---
<button
type="button"
popovertarget={target}
aria-haspopup="menu"
aria-expanded="false"
data-slot="dropdown-trigger"
data-variant={variant}
data-size={size}
class={className}
{...rest}
>
<slot />
<slot name="chevron"><Chevron /></slot>
</button>
import Dropdown from "./Dropdown.astro";
import DropdownItem from "./DropdownItem.astro";
import DropdownMenu from "./DropdownMenu.astro";
import DropdownTrigger from "./DropdownTrigger.astro";
export { Dropdown, DropdownItem, DropdownMenu, DropdownTrigger };
export default Dropdown;
What you get
The component source, copied into your project by npx astrocraft-ui add overlays/dropdown — no package dependency, no CSS to fight. Whatever the paid blocks compose, this is it.