--- title: Components description: Cards, steps, tabs, accordions, badges, code groups, frames, trees, type tables, live previews, and diffs — the built-in components, usable in any MDX page. --- Blume ships an accessible, themeable component set available in any `.mdx` page with **no imports**. Each one is shown below with a live preview and its source. Components are vanilla and React-free; React only switches on if you add your own island. ## Card and CardGroup Cards link to a destination with an icon, title, and short blurb. Group them with `CardGroup` for a responsive grid. Reach for them on landing pages, section indexes, and “next steps” — anywhere you’re guiding the reader onward. Install Blume and ship your first page. Browse the component library. ```astro lineNumbers Install Blume and ship your first page. Browse the component library. ``` `Card` takes `title`, an optional `href` (omit it for a non-clickable card), and an `icon` from Blume's built-in icon set. `CardGroup` takes `cols` (default `2`). ## Steps A numbered vertical sequence for ordered instructions — installs, setup flows, and tutorials where the order matters. Each `Step` takes a `title`. Add the package to your project. Drop an `.mdx` file into your content folder. Run `blume build` and deploy `dist/`. ```astro lineNumbers Add the package to your project. Drop an `.mdx` file into your content folder. Run `blume build` and deploy `dist/`. ``` ## Tabs Switch between equivalent content in place — language variants, OS-specific commands, or alternative approaches — without stacking everything on the page. Each `Tab` takes a `title`. Use Homebrew to install the toolchain. Use winget to install the toolchain. ```astro lineNumbers Use Homebrew to install the toolchain. Use winget to install the toolchain. ``` Add `inline` to render borderless — a tab strip on a full-width rule with the content flowing beneath as prose — instead of the bordered box. Add `param` to sync the active tab to a URL query param instead of the hash, which makes the selection shareable: a link ending in `?install=windows` opens on the Windows tab. Each group syncs to its own `param`, so you can use several independent, deep-linkable groups on one page. Use Homebrew to install the toolchain. Use winget to install the toolchain. ```astro lineNumbers Use Homebrew to install the toolchain. Use winget to install the toolchain. ``` ## Badge A small inline label for status or metadata — version tags, “new” or “beta” markers, stability levels. The `variant` tunes the color to the meaning. ### Default Neutral metadata with no particular emphasis. Stable ```astro Stable ``` ### Accent Draws the eye using your theme accent — good for “new” or featured markers. New ```astro New ``` ### Success A positive or passing state. Passing ```astro Passing ``` ### Warning Something to use with caution, such as an experimental feature. Beta ```astro Beta ``` ### Danger A negative or breaking state, such as a deprecation. Deprecated ```astro Deprecated ``` ## Icon Render an icon by name — the same `icon` prop powers cards, steps, tabs, and sidebar entries. Names come from [Lucide](https://lucide.dev/icons), lowercase and kebab-cased (`rocket`, `gauge`, `book-open`). ```astro ``` Blume is Lucide-only — a bare name resolves against Lucide, and you can prefix a name with `lucide:` (`lucide:rocket`) for symmetry with other icon inputs. `size` sets the pixel size (default `16`) and `color` tints it (any CSS color; defaults to `currentColor`). Pass a raw `` string, an image URL, or a local image path in place of a name to render your own art, and add a `label` to expose it to assistive tech — without one, the icon is decorative. Icons resolve at build time and inline as zero-JS SVG — nothing is fetched at runtime. ## File tree Illustrate a project or folder layout. Wrap a normal Markdown list and Blume styles it as a tree — handy for explaining structure in setup and config guides. - docs/ - index.mdx - guides/ - configuration.mdx - blume.config.ts ```astro lineNumbers - docs/ - index.mdx - guides/ - configuration.mdx - blume.config.ts ``` ## Accordion Stack related collapsibles in a single bordered container with dividers between them — FAQs, optional steps, or long examples. Each child is an `AccordionItem` (`title`, optional `icon`, `description`, `defaultOpen`). For a single standalone disclosure, use [Expandable](#expandable). Yes — every page can be `.md` or `.mdx`. Yes, via Tailwind v4 tokens and your own `theme.css`. ```astro lineNumbers Yes — every page can be `.md` or `.mdx`. Yes, via Tailwind v4 tokens and your own `theme.css`. ``` ## Expandable A lightweight inline disclosure for nested detail — expanding a field's sub-properties or an optional aside. `title` labels the toggle (defaults to “Show more”); set `defaultOpen` to start expanded. These settings are optional and rarely need changing. ```astro These settings are optional and rarely need changing. ``` ## Columns Lay cards or blocks out in a responsive grid of equal columns that reflows on mobile. `Columns` takes `cols`; wrap each cell in a `Column`. Built on Astro and Vite. Tailwind v4 design tokens. ```astro lineNumbers Built on Astro and Vite. Tailwind v4 design tokens. ``` ## CodeGroup Group several code blocks into one tabbed switcher — a tab per language or file. The tab label is each block's title (the text after the language). Add `dropdown` to switch with a menu instead of a tab bar. ```ts TypeScript export const greet = (name: string) => `Hello, ${name}`; ``` ```python Python def greet(name: str) -> str: return f"Hello, {name}" ``` ```rust Rust fn greet(name: &str) -> String { format!("Hello, {name}") } ``` ````astro ```ts TypeScript export const greet = (name: string) => `Hello, ${name}`; ``` ```python Python def greet(name: str) -> str: return f"Hello, {name}" ``` ```rust Rust fn greet(name: &str) -> String { format!("Hello, {name}") } ``` ```` ## Frame Wrap an image or any visual in a centered, bordered frame with an optional `caption` (rendered as Markdown) and `hint`. ```astro lineNumbers Product screenshot ``` ## YouTube Embed a YouTube video in a responsive, privacy-friendly (`youtube-nocookie.com`) 16:9 frame that ships no client JavaScript. Pass a video `id` or a full `url`, plus an optional `title` (for accessibility) and a `start` time in seconds. ```astro lineNumbers ``` ## Color Show color swatches with copyable hex values — useful for documenting a palette or brand colors. Use `variant="compact"` for a swatch list, or `variant="table"` with `Color.Row` to group them. Each `Color.Item` takes a `name` and a `value` (a hex string, or `{ light, dark }` for theme-aware colors). ```astro lineNumbers ``` ## Tree Render a hierarchical file/folder structure with expandable folders. (For a quick, list-driven version see [File tree](#file-tree); `Tree` gives per-folder control.) Use `Tree.Folder` (`name`, optional `defaultOpen`, `openable`) and `Tree.File` (`name`). ```astro lineNumbers ``` ## Panel A titled container for supplementary, set-aside content. `title` is optional. Panels hold supporting detail without interrupting the main flow. ```astro Panels hold supporting detail without interrupting the main flow. ``` ## Tooltip Reveal a definition or hint on hover for an inline term. `tip` is the hover text; add an optional `headline` and a `cta` + `href` for a follow-up link. Hover the API term to learn more. ```astro Hover the API term. ``` ## Tile A clickable preview that leads with a visual — an icon or image — above a title and description. Good for galleries and showcases. Takes `title`, `description`, and `href`; the child is the visual. ```astro ``` ## Prompt A single row with a label and a copy button. The `description` (Markdown) is the visible label; the body is the prompt itself — hidden, and copied to the clipboard when the **Copy prompt** button is pressed. `actions` controls the buttons (e.g. `["copy", "cursor"]`). Write reference docs for the POST /v1/pets endpoint. ```astro Write reference docs for the POST /v1/pets endpoint. ``` ## Visibility Show or hide content by audience. `for="web"` renders only on the site; `for="agents"` targets the agent-facing Markdown that AI agents read (`llms-full.txt` and each page's `.md` mirror). This note appears on the website but is omitted from the agent-facing Markdown. ```astro Shown on the site only. Shown only in the generated Markdown. ``` ## Type tables Tables for documenting an object's properties — its props, types, and defaults. Write the rows by hand with `TypeTable`, or generate them straight from a TypeScript interface or type alias with `AutoTypeTable`. ### Type table A **Prop / Type** grid where each row expands to reveal its description and details. Pass a `type` map keyed by property name; each entry takes a `type`, plus an optional `description`, `default`, `required` flag, `typeDescription`, and `typeDescriptionLink`. Optional props (`required` unset) show a `?` after the name. ```astro lineNumbers ``` ### Auto type table Generate a type table from a TypeScript type so the docs stay in sync with the source. Point `AutoTypeTable` at a file with `path` (resolved from your project root) and a type `name`. Descriptions come from JSDoc comments, defaults from `@default` tags, and optional properties (`?`) are marked accordingly. ```astro ``` You can also pass the type inline with `type` instead of a `path` — handy for small examples: ```astro lineNumbers ``` ## GitHub info A card linking to a GitHub repository with its live star and fork counts. Counts are fetched at build time — no client JavaScript — and the card still renders if the API is unreachable. Pass `owner` and `repo`, or omit them to use the repository from your `blume.config`. Set a `GITHUB_TOKEN` environment variable to lift the API rate limit. ```astro lineNumbers ``` ## Component `Component` renders an example file from your project's `examples/` directory as a live preview alongside its highlighted source, in tabs. Point it at a file with `path` — its location under `examples/`, without the extension (so `examples/counter.tsx` is `path="counter"`). React, Vue, Svelte, and Astro examples are all supported; framework examples hydrate, Astro ones render statically. It keeps the preview and the code in sync from a single file. The preview renders in an isolated frame that the docs styles never reach — no prose margins, typography, or theme chrome bleed into your component. The frame gets Tailwind (preflight + utilities scanned from your example files and anything they import), Blume's design tokens so classes like `bg-background` follow the site palette by default, and it follows the site's light/dark toggle live. The pane sizes itself to the rendered example — and keeps tracking it if the example grows or shrinks after load — with the Preview and Code tabs sharing one height so toggling them never shifts the page. To style previews with your own design system — say, shadcn variables — point `examples.css` at a stylesheet. It's injected into every preview frame after Blume's defaults, so your tokens win. Don't `@import "tailwindcss"` in it; the frame already provides Tailwind. Both `.dark` and `[data-theme="dark"]` work for dark-mode overrides: ```ts // blume.config.ts export default defineConfig({ examples: { css: "examples/theme.css" }, }); ``` ```css /* examples/theme.css */ :root { --primary: oklch(0.6 0.2 260); } .dark { --primary: oklch(0.75 0.15 260); } @theme inline { --color-primary: var(--primary); } ``` The directory is configurable too — set `source` (or use the string shorthand, `examples: "..."`) when your examples live elsewhere (e.g. a registry layout). `path` is always relative to it: ```ts // blume.config.ts export default defineConfig({ examples: "registry/files-sdk", }); ``` ```astro ``` `examples` can also be a glob (anything with `*`, `?`, `[]`, `{}`, or `!`). Only matching files are discovered, and `path` is relative to the glob's static prefix (the part before the first wildcard). This is for a registry that colocates each component's source with its example — point at just the examples so the sources, which have no default export to preview, aren't swept in: ```ts // blume.config.ts export default defineConfig({ // registry/files-sdk/file-list/file-list.tsx — source, left out // registry/files-sdk/file-list/examples/basic.tsx — discovered examples: "registry/files-sdk/**/examples/*", }); ``` ```astro ``` ```astro ``` An Astro example renders live with no client JavaScript: ## CodeBlock `CodeBlock` highlights a code string with the same Shiki theme and transformers as your fenced code — including the light/dark swap — for places a fence can't go, like a landing page or a custom component. Pass `code` and a `lang`: \`Hello, \${name}!\`;`} /> ```astro --- import CodeBlock from "blume/components/content/CodeBlock.astro"; --- ``` To highlight to an HTML string yourself (e.g. inside your own component), import the underlying helper from `blume/markdown`: ```ts import { highlightCode } from "blume/markdown"; const html = await highlightCode(source, "ts"); ``` ## Diff `Diff` renders a git-style diff, highlighted with the same Shiki theme as your code blocks and produced entirely at build time — no client JavaScript. Give it two inline strings (`old` / `new`), two file paths (`before` / `after`), or a unified patch (an inline `patch` string or a `src` file). ```astro ``` Diff two files in your project, relative to its root: ```astro ``` Or render a unified patch — either from a file with `src`, or inline with `patch`: ```astro ``` ```astro ```