--- title: Komponenten description: >- Karten, Schritte, Tabs, Akkordeons, Badges, Codegruppen, Rahmen, Bäume, Typtabellen, Live-Vorschauen und Diffs – die integrierten Komponenten, nutzbar auf jeder MDX-Seite. --- Blume liefert einen barrierefreien, themenfähigen Komponentensatz, der auf jeder `.mdx`-Seite **ohne Imports** verfügbar ist. Jede Komponente wird unten mit einer Live-Vorschau und ihrem Quellcode gezeigt. Die Komponenten sind Vanilla und React-frei; React wird nur aktiviert, wenn du deine eigene Island hinzufügst. ## Card and CardGroup Karten verlinken mit Icon, Titel und kurzem Text auf ein Ziel. Gruppiere sie mit `CardGroup` zu einem responsiven Raster. Setze sie auf Landingpages, in Abschnittsübersichten und bei „nächsten Schritten“ ein – überall dort, wo du die Leserschaft weiterführst. **[Quickstart](/docs/quickstart)** Installiere Blume und veröffentliche deine erste Seite. **[Components](/docs/content/components)** Durchstöbere die Komponentenbibliothek. ```astro lineNumbers Install Blume and ship your first page. Browse the component library. ``` `Card` nimmt `title`, ein optionales `href` (weglassen für eine nicht klickbare Karte) und ein `icon` aus Blumes integriertem Icon-Set entgegen. `CardGroup` nimmt `cols` entgegen (Standard `2`). ## Steps Eine nummerierte vertikale Abfolge für geordnete Anleitungen – Installationen, Einrichtungsabläufe und Tutorials, bei denen die Reihenfolge zählt. Jeder `Step` nimmt einen `title` entgegen. 1. **Install Blume** Füge das Paket zu deinem Projekt hinzu. 2. **Write a page** Lege eine `.mdx`-Datei in deinen Inhaltsordner. 3. **Ship it** Führe `blume build` aus und deploye `dist/`. ```astro lineNumbers Add the package to your project. Drop an `.mdx` file into your content folder. Run `blume build` and deploy `dist/`. ``` ## Tabs Wechsle an Ort und Stelle zwischen gleichwertigen Inhalten – Sprachvarianten, betriebssystemspezifischen Befehlen oder alternativen Vorgehensweisen – ohne alles untereinander auf der Seite zu stapeln. Jeder `Tab` nimmt einen `title` entgegen. **macOS** Nutze Homebrew, um die Toolchain zu installieren. **Windows** Nutze winget, um die Toolchain zu installieren. ```astro lineNumbers Use Homebrew to install the toolchain. Use winget to install the toolchain. ``` Füge `inline` hinzu, um randlos zu rendern – eine Tab-Leiste auf einer Linie über die volle Breite, mit dem Inhalt, der darunter als Fließtext folgt – statt der umrandeten Box. Füge `param` hinzu, um den aktiven Tab statt mit dem Hash mit einem URL-Query-Parameter zu synchronisieren; das macht die Auswahl teilbar: Ein Link, der auf `?install=windows` endet, öffnet den Windows-Tab. Jede Gruppe synchronisiert sich mit ihrem eigenen `param`, sodass du mehrere unabhängige, direkt verlinkbare Gruppen auf einer Seite verwenden kannst. Gruppen mit gleichnamigen Tabs wechseln gemeinsam – wähle in einer „macOS“, und jede Gruppe mit einem macOS-Tab zieht nach. Füge `syncKey` hinzu, um diese Synchronisierung einzugrenzen: Nur Gruppen mit demselben Schlüssel wechseln gemeinsam, sodass unabhängige Gruppen, die zufällig einen Tab-Titel teilen, eigenständig bleiben. **macOS** Nutze Homebrew, um die Toolchain zu installieren. **Windows** Nutze winget, um die Toolchain zu installieren. ```astro lineNumbers Use Homebrew to install the toolchain. Use winget to install the toolchain. ``` ## Badge Ein kleines Inline-Label für Status oder Metadaten – Versionskennzeichen, „new“- oder „beta“-Markierungen, Stabilitätsstufen. Die `variant` stimmt die Farbe auf die Bedeutung ab. ### Default Neutrale Metadaten ohne besondere Betonung. Stabil ```astro Stable ``` ### Accent Zieht mit deiner Theme-Akzentfarbe den Blick auf sich – gut für „neu“- oder Hervorhebungs-Markierungen. Neu ```astro New ``` ### Success Ein positiver oder bestandener Zustand. Bestanden ```astro Passing ``` ### Warning Etwas, das mit Vorsicht zu verwenden ist, etwa ein experimentelles Feature. Beta ```astro Beta ``` ### Danger Ein negativer oder brechender Zustand, etwa eine Veraltung. Veraltet ```astro Deprecated ``` ## Icon Rendere ein Icon anhand seines Namens – dieselbe `icon`-Prop treibt Karten, Schritte, Tabs und Sidebar-Einträge an. Die Namen stammen von [Lucide](https://lucide.dev/icons), in Kleinschreibung und Kebab-Case (`rocket`, `gauge`, `book-open`). ```astro ``` Blume unterstützt ausschließlich Lucide – ein reiner Name wird gegen Lucide aufgelöst, und du kannst einem Namen zur Symmetrie mit anderen Icon-Eingaben `lucide:` voranstellen (`lucide:rocket`). `size` legt die Pixelgröße fest (Standard `16`) und `color` färbt es ein (jede CSS-Farbe; Standard ist `currentColor`). Übergib anstelle eines Namens einen rohen ``-String, eine Bild-URL oder einen lokalen Bildpfad, um eigene Grafiken zu rendern, und ergänze ein `label`, um es assistiven Technologien zugänglich zu machen – ohne ein solches gilt das Icon als dekorativ. Icons werden zur Build-Zeit aufgelöst und als SVG ohne JavaScript eingebettet – zur Laufzeit wird nichts nachgeladen. ## File tree Veranschauliche ein Projekt- oder Ordnerlayout. Umschließe eine gewöhnliche Markdown-Liste, und Blume stylt sie als Baum – praktisch, um Strukturen in Einrichtungs- und Konfigurationsanleitungen zu erklären. - docs/ - index.mdx - guides/ - configuration.mdx - blume.config.ts ```astro lineNumbers - docs/ - index.mdx - guides/ - configuration.mdx - blume.config.ts ``` ## Accordion Staple zusammengehörige Aufklappbereiche in einem einzigen umrandeten Container mit Trennlinien dazwischen – FAQs, optionale Schritte oder lange Beispiele. Jedes Kind ist ein `AccordionItem` (`title`, optional `icon`, `description`, `defaultOpen`). Für einen einzelnen eigenständigen Aufklappbereich verwende [Expandable](#expandable). Ja – jede Seite kann `.md` oder `.mdx` sein. Ja, über Tailwind-v4-Tokens und dein eigenes `theme.css`. ```astro lineNumbers Yes — every page can be `.md` or `.mdx`. Yes, via Tailwind v4 tokens and your own `theme.css`. ``` ## Expandable Ein leichtgewichtiger Inline-Aufklappbereich für verschachtelte Details – etwa die Unterattribute eines Feldes oder eine optionale Randbemerkung. `title` beschriftet den Umschalter (Standard „Show more“); setze `defaultOpen`, damit er aufgeklappt startet. Diese Einstellungen sind optional und müssen selten geändert werden. ```astro These settings are optional and rarely need changing. ``` ## Columns Ordne Karten oder Blöcke in einem responsiven Raster aus gleich breiten Spalten an, das auf Mobilgeräten umbricht. `Columns` nimmt `cols` entgegen; umschließe jede Zelle mit einem `Column`. **Fast** Gebaut auf Astro und Vite. **Themeable** Tailwind-v4-Design-Tokens. ```astro lineNumbers Built on Astro and Vite. Tailwind v4 design tokens. ``` ## CodeGroup Fasse mehrere Codeblöcke zu einem einzigen Tab-Umschalter zusammen – ein Tab pro Sprache oder Datei. Die Tab-Beschriftung ist der Titel des jeweiligen Blocks (der Text nach der Sprache), und der Kopier-Button der Gruppe sitzt in der Tab-Leiste und kopiert den gerade angezeigten Block. Füge `dropdown` hinzu, um statt über eine Tab-Leiste über ein Menü zu wechseln. ```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 Umschließe ein Bild oder eine beliebige Grafik mit einem zentrierten, umrandeten Rahmen samt optionaler `caption` (wird als Markdown gerendert) und `hint`. ```astro lineNumbers Product screenshot ``` ## YouTube Bette ein YouTube-Video in einen responsiven, datenschutzfreundlichen (`youtube-nocookie.com`) 16:9-Rahmen ein, der kein Client-JavaScript ausliefert. Übergib eine Video-`id` oder eine vollständige `url` sowie optional einen `title` (für Barrierefreiheit) und eine `start`-Zeit in Sekunden. [Big Buck Bunny](https://www.youtube.com/watch?v=aqz-KE-bpKQ) ```astro lineNumbers ``` ## Color Zeige Farbfelder mit kopierbaren Hex-Werten – nützlich, um eine Palette oder Markenfarben zu dokumentieren. Verwende `variant="compact"` für eine Liste von Farbfeldern oder `variant="table"` mit `Color.Row`, um sie zu gruppieren. Jedes `Color.Item` nimmt einen `name` und einen `value` entgegen (einen Hex-String oder `{ light, dark }` für themenabhängige Farben). ```astro lineNumbers ``` ## Tree Rendere eine hierarchische Datei-/Ordnerstruktur mit ausklappbaren Ordnern. (Für eine schnelle, listenbasierte Variante siehe [File tree](#file-tree); `Tree` bietet Kontrolle pro Ordner.) Verwende `Tree.Folder` (`name`, optional `defaultOpen`, `openable`) und `Tree.File` (`name`). ```astro lineNumbers ``` ## Panel Ein betitelter Container für ergänzende, beiseitegestellte Inhalte. `title` ist optional. Panels nehmen ergänzende Details auf, ohne den Lesefluss zu unterbrechen. ```astro Panels hold supporting detail without interrupting the main flow. ``` ## Tooltip Zeige beim Überfahren eines Inline-Begriffs eine Definition oder einen Hinweis. `tip` ist der Hover-Text; ergänze optional eine `headline` sowie ein `cta` + `href` für einen weiterführenden Link. Fahre über den Begriff API, um mehr zu erfahren. ```astro Hover the API term. ``` ## Tile Eine klickbare Vorschau, die mit einer Grafik – einem Icon oder Bild – über Titel und Beschreibung eröffnet. Gut für Galerien und Showcases. Nimmt `title`, `description` und `href` entgegen; das Kind ist die Grafik. ```astro ``` ## Prompt Eine einzelne Zeile mit einer Beschriftung und einem Kopier-Button. Die `description` (Markdown) ist die sichtbare Beschriftung; der Body ist der Prompt selbst – ausgeblendet und beim Drücken des Buttons **Copy prompt** in die Zwischenablage kopiert. `actions` steuert die Buttons (z. B. `["copy", "cursor"]`). Schreibe eine Referenzdokumentation für den Endpunkt POST /v1/pets. ```astro Write reference docs for the POST /v1/pets endpoint. ``` ## Visibility Zeige oder verbirg Inhalte je nach Zielgruppe. `for="web"` rendert nur auf der Website; `for="agents"` zielt auf das an Agenten gerichtete Markdown, das KI-Agenten lesen (`llms-full.txt` und die `.md`-Spiegelung jeder Seite). ```astro Shown on the site only. Shown only in the generated Markdown. ``` ## Type tables Tabellen zur Dokumentation der Eigenschaften eines Objekts – seiner Props, Typen und Standardwerte. Schreibe die Zeilen mit `TypeTable` von Hand oder erzeuge sie direkt aus einem TypeScript-Interface oder Typ-Alias mit `AutoTypeTable`. ### Type table Ein **Prop / Type**-Raster, in dem sich jede Zeile ausklappen lässt, um ihre Beschreibung und Details zu zeigen. Übergib eine `type`-Map mit den Eigenschaftsnamen als Schlüssel; jeder Eintrag nimmt einen `type` entgegen, dazu optional eine `description`, ein `default`, ein `required`-Flag, `typeDescription` und `typeDescriptionLink`. Optionale Props (`required` nicht gesetzt) zeigen ein `?` nach dem Namen. | Prop | Type | Default | Description | | - | - | - | - | | `label` | `string` | - | The button's visible label. | | `variant?` | `"primary" \| "ghost"` | `"primary"` | Visual style. | | `disabled?` | `boolean` | - | | ```astro lineNumbers ``` ### Auto type table Erzeuge eine Typtabelle aus einem TypeScript-Typ, damit die Dokumentation mit dem Quellcode synchron bleibt. Richte `AutoTypeTable` mit `path` (relativ zum Projektstammverzeichnis aufgelöst) und einem Typ-`name` auf eine Datei aus. Beschreibungen stammen aus JSDoc-Kommentaren, Standardwerte aus `@default`-Tags, und optionale Eigenschaften (`?`) werden entsprechend markiert. ```astro ``` Du kannst den Typ statt eines `path` auch inline über `type` übergeben – praktisch für kleine Beispiele: ```astro lineNumbers ``` ## GitHub info Eine Karte, die auf ein GitHub-Repository verlinkt und dessen aktuelle Stern- und Fork-Zahlen anzeigt. Die Zahlen werden zur Build-Zeit abgerufen – kein Client-JavaScript – und die Karte wird auch dann gerendert, wenn die API nicht erreichbar ist. Übergib `owner` und `repo` oder lass beides weg, um das Repository aus deiner `blume.config` zu verwenden. Setze eine Umgebungsvariable `GITHUB_TOKEN`, um das API-Ratenlimit anzuheben. Die Karte liest die Instanz aus [`github.host`](/docs/configuration#github-enterprise), sodass auf einer Enterprise-gehosteten Website auch explizite `owner`/`repo` diese Instanz adressieren. Übergib `host`, um eine einzelne Karte woanders hinzurichten – etwa auf ein öffentliches Projekt von einer Enterprise-Website aus; die REST-Basis wird davon genauso abgeleitet wie von `github.host`. ```astro lineNumbers ``` ## Component `Component` rendert eine Beispieldatei aus dem Verzeichnis `examples/` deines Projekts als Live-Vorschau neben ihrem hervorgehobenen Quellcode, in Tabs. Richte es mit `path` auf eine Datei aus – ihr Ort unterhalb von `examples/`, ohne Erweiterung (aus `examples/counter.tsx` wird also `path="counter"`). React-, Vue-, Svelte- und Astro-Beispiele werden alle unterstützt; Framework-Beispiele hydrieren, Astro-Beispiele werden statisch gerendert. So bleiben Vorschau und Code aus einer einzigen Datei synchron. Die Vorschau rendert in einem isolierten Rahmen, den die Doku-Styles nie erreichen – keine Fließtext-Abstände, Typografie oder Theme-Elemente sickern in deine Komponente. Der Rahmen erhält Tailwind (Preflight + Utilities, die aus deinem Projekt und deinem Beispielverzeichnis gescannt werden), Blumes Design-Tokens, sodass Klassen wie `bg-background` standardmäßig der Website-Palette folgen, und er folgt der Hell-/Dunkel-Umschaltung der Website in Echtzeit. Der Bereich passt seine Größe an das gerenderte Beispiel an – und verfolgt das weiter, falls das Beispiel nach dem Laden wächst oder schrumpft – wobei die Tabs „Preview“ und „Code“ dieselbe Höhe teilen, sodass das Umschalten die Seite nie verschiebt. Um Vorschauen mit deinem eigenen Designsystem zu gestalten – etwa mit shadcn-Variablen – richte `examples.css` auf ein Stylesheet aus. Es wird nach Blumes Standardwerten in jeden Vorschaurahmen eingefügt, sodass deine Tokens gewinnen. Verwende darin kein `@import "tailwindcss"`; der Rahmen stellt Tailwind bereits bereit. Sowohl `.dark` als auch `[data-theme="dark"]` funktionieren für 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); } ``` Auch das Verzeichnis ist konfigurierbar – setze `source` (oder nutze die Kurzschreibweise als String, `examples: "..."`), wenn deine Beispiele anderswo liegen (z. B. in einem Registry-Layout). `path` ist immer relativ dazu: ```ts // blume.config.ts export default defineConfig({ examples: "registry/files-sdk", }); ``` ```astro ``` `examples` kann auch ein Glob sein (alles mit `*`, `?`, `[]`, `{}` oder `!`). Es werden nur passende Dateien erfasst, und `path` ist relativ zum statischen Präfix des Globs (dem Teil vor dem ersten Platzhalter). Das ist für eine Registry gedacht, die den Quellcode jeder Komponente neben ihrem Beispiel ablegt – richte es nur auf die Beispiele aus, damit die Quelldateien, die keinen Default-Export für eine Vorschau haben, nicht mit eingesammelt werden: ```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 ``` In einem Monorepo liegen die Komponenten, die deine Beispiele importieren, meist in einem benachbarten Workspace-Paket. Tailwinds `@source` scannt Dateien, keine Importe: Blume scannt dein Projekt und das `examples`-Verzeichnis (wohin auch immer `source` zeigt, auch außerhalb des Projekts), sodass eine Klasse, die nur innerhalb dieses benachbarten Pakets verwendet wird, erst erzeugt wird, wenn du das Paket zum Scan hinzufügst. Das machst du mit einer `@source`-Direktive in `examples.css` (für die Vorschaurahmen) oder `theme.css` (für die Website), relativ zu der Datei geschrieben, in der sie steht – die übliche Tailwind-Regel – und Blume übernimmt sie in das erzeugte Stylesheet: ```css /* examples/theme.css */ @source "../../../packages/ui/src"; ``` ```astro ``` Ein Astro-Beispiel rendert live und ohne Client-JavaScript: ## CodeBlock `CodeBlock` hebt einen Code-String mit demselben Shiki-Theme und denselben Transformern hervor wie deine eingezäunten Codeblöcke – einschließlich des Hell-/Dunkel-Wechsels – für Stellen, an die kein Code-Fence passt, etwa eine Landingpage oder eine eigene Komponente. Übergib `code` und ein `lang`: \`Hello, \${name}!\`;`} /> ```astro --- import CodeBlock from "blume/components/content/CodeBlock.astro"; --- ``` Um selbst zu einem HTML-String hervorzuheben (z. B. innerhalb deiner eigenen Komponente), importiere den zugrunde liegenden Helfer aus `blume/markdown`: ```ts import { highlightCode } from "blume/markdown"; const html = await highlightCode(source, "ts"); ``` ## Diff `Diff` rendert einen Diff im Git-Stil, hervorgehoben mit demselben Shiki-Theme wie deine Codeblöcke und vollständig zur Build-Zeit erzeugt – kein Client-JavaScript. Übergib zwei Inline-Strings (`old` / `new`), zwei Dateipfade (`before` / `after`) oder einen Unified Patch (einen Inline-`patch`-String oder eine `src`-Datei). ```astro ``` Vergleiche zwei Dateien in deinem Projekt, relativ zu dessen Stammverzeichnis: ```astro ``` Oder rendere einen Unified Patch – entweder aus einer Datei mit `src` oder inline mit `patch`: ```astro ``` ```astro ```