Skip to main content
astrocraft-ui/ components · 101

Dropdown

Free · MIT

Headless, 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

Install command
npx astrocraft-ui add overlays/dropdown

Plain-CSS theme — no build step

Install command
npx astrocraft-ui add overlays/dropdown --theme css

Tailwind theme — needs Tailwind v4

Install command
npx astrocraft-ui add overlays/dropdown --theme tailwind

Plain-CSS theme, re-pointed onto Lumos tokens

Install command
npx astrocraft-ui add overlays/dropdown --theme css --bridge lumos

Tailwind theme, re-pointed onto Lumos tokens

Install command
npx astrocraft-ui add overlays/dropdown --theme tailwind --bridge lumos

Live 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.

ComponentSlotsVariantsRuntime stateNative 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
---
// 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
---
// 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
---
// 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
---
// 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>
src/components/ui/overlays/dropdown/index.ts
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.