Link Box

Free · MIT

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

← Breadcrumb Nav →

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 navigation/link-box

Plain-CSS theme — no build step

npx astrocraft-ui add navigation/link-box --theme css

Tailwind theme — needs Tailwind v4

npx astrocraft-ui add navigation/link-box --theme tailwind

Plain-CSS theme, re-pointed onto Lumos tokens

npx astrocraft-ui add navigation/link-box --theme css --bridge lumos

Tailwind theme, re-pointed onto Lumos tokens

npx astrocraft-ui add navigation/link-box --theme tailwind --bridge lumos

LinkBox

The whole card is clickable, and the card's own link still works — click "docs" below and you get the docs, not the card. The accessible name of the card is just its title, and the body text stays selectable. A nested <a> would be invalid HTML; this is the fix.

Headless is a promise you can test

Load the catalog with no theme and drive every primitive. Everything must still be operable — the rest is in the docs.

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
`LinkBox.astro`	`link-box`	—	—	—
`LinkOverlay.astro`	`link-overlay`	—	—	—

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/navigation/link-box/LinkBox.astro

---
// src/components/ui/navigation/link-box/LinkBox.astro — headless primitive (see ../../README.md).
// The whole-card-clickable pattern, done the way that is actually valid and actually accessible.
//
// The obvious implementations are both wrong. Wrapping the card in one <a> nests the card's own
// links inside it, which is invalid HTML and leaves a screen reader reading the entire card as one
// link name. Adding a click handler to the <div> gives a mouse user a target and everyone else
// nothing. This ships neither: ONE real link (LinkOverlay) covers the box with a stretched
// pseudo-element, so the accessible name is just the title, text inside the card stays selectable,
// and any other link or button in the card keeps working because structure.css lifts it above the
// overlay.
//
// `as` exists because the box is nearly always already a semantic element — an <article> in a feed,
// an <li> in a list — and wrapping one in a <div> just to hold a `position: relative` is a box
// nobody asked for.
import "../../../../styles/structure.css";

import type { HTMLAttributes } from "astro/types";

type Props = HTMLAttributes<"div"> & {
  /** Render element — `article` / `li` / `div`. The stretch needs a real box, so not `contents`. */
  as?: keyof HTMLElementTagNameMap;
};

const { as, class: className, ...rest } = Astro.props;
const Tag = as ?? "div";
---

<Tag class={className} data-slot="link-box" {...rest}>
  <slot />
</Tag>

src/components/ui/navigation/link-box/LinkOverlay.astro

---
// src/components/ui/navigation/link-box/LinkOverlay.astro — LinkBox compound part (see ../../README.md).
// The card's ONE real link. Put it on the title: its text is the accessible name of the whole card,
// so "Read more" here reads as "Read more" in a list of links and the title does not.
//
// Exactly one per LinkBox. Two stretched overlays would each cover the whole box and the one later
// in the DOM would silently win every click.
import "../../../../styles/structure.css";

import type { HTMLAttributes } from "astro/types";

type Props = HTMLAttributes<"a"> & { href?: string };

const { href, class: className, ...rest } = Astro.props;
---

<a href={href} class={className} data-slot="link-overlay" {...rest}>
  <slot />
</a>

src/components/ui/navigation/link-box/index.ts

import LinkBox from "./LinkBox.astro";
import LinkOverlay from "./LinkOverlay.astro";

export { LinkBox, LinkOverlay };
export default LinkBox;

What you get

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