# Herald UI

> The component library for building AI Operating Systems — 105 shadcn-registry items across components, blocks, and hooks (chat, fleet dashboards, task boards, media viewers, a multi-agent roundtable, a knowledge graph, and a full drop-in cockpit). Built on Base UI, themed with one OKLCH hue, and endpoint-agnostic — every piece is prop-driven with injected callbacks, so an agent can wire it to any backend.

## Using Herald

Herald is a shadcn registry. Register the namespace once in the consuming project's `components.json`:

    { "registries": { "@herald-ui": "https://herald-ui.vercel.app/r/{name}.json" } }

Then install any item by name — the source drops into the project with its dependencies:

    npx shadcn add @herald-ui/<name>

Fastest start: `npx shadcn add @herald-ui/dashboard` scaffolds a full AI-OS cockpit (sidebar, notifications, fleet KPIs, agent cards, usage chart, activity feed). Every component uses semantic tokens (bg-background, text-muted-foreground, bg-brand) — never hardcode colors, and one brand hue re-themes the whole system.

## Guides

- [Getting Started](https://herald-ui.vercel.app/docs/getting-started): Compose the shell, chat, and surfaces into a coherent AI OS.
- [Installation](https://herald-ui.vercel.app/docs/installation): Register the @herald-ui namespace and add components.
- [Agents](https://herald-ui.vercel.app/docs/agents): Wire Herald's injected callbacks to a live agent gateway (OpenClaw / Hermes / your own).

## Blocks

Composed, drop-in surfaces. After `npx shadcn add @herald-ui/<name>` the source lands locally — import from `@/blocks/<name>`.

- [Activity Feed](https://herald-ui.vercel.app/docs/activity-feed): A searchable, timelined event feed. — `npx shadcn add @herald-ui/activity-feed`
- [Conversation List](https://herald-ui.vercel.app/docs/conversation-list): A recency-grouped chat-history sidebar. — `npx shadcn add @herald-ui/conversation-list`
- [File Tree](https://herald-ui.vercel.app/docs/file-tree): A recursive, searchable folder explorer. — `npx shadcn add @herald-ui/file-tree`
- [Kanban Board](https://herald-ui.vercel.app/docs/kanban-board): A draggable, data-defined column board. — `npx shadcn add @herald-ui/kanban-board`
- [Media Viewer](https://herald-ui.vercel.app/docs/media-viewer): A full-screen zoom/pan/slideshow lightbox. — `npx shadcn add @herald-ui/media-viewer`
- [Media Grid](https://herald-ui.vercel.app/docs/media-grid): A windowed thumbnail grid of assets. — `npx shadcn add @herald-ui/media-grid`
- [Notifications Bell](https://herald-ui.vercel.app/docs/notifications-bell): A bell with an unread badge + panel. — `npx shadcn add @herald-ui/notifications-bell`
- [Sidebar Nav](https://herald-ui.vercel.app/docs/sidebar-nav): A collapsible grouped navigation rail. — `npx shadcn add @herald-ui/sidebar-nav`
- [Dashboard](https://herald-ui.vercel.app/docs/dashboard): A complete drop-in AI-OS cockpit — one command installs it all. — `npx shadcn add @herald-ui/dashboard`
- [Session List](https://herald-ui.vercel.app/docs/session-list): Master-detail browser for agent sessions. — `npx shadcn add @herald-ui/session-list`
- [Inline Agent Chat](https://herald-ui.vercel.app/docs/inline-agent-chat): A compact single-agent chat card to embed. — `npx shadcn add @herald-ui/inline-agent-chat`
- [Concierge Drawer](https://herald-ui.vercel.app/docs/concierge-drawer): A slide-in tool-using copilot drawer. — `npx shadcn add @herald-ui/concierge-drawer`
- [Roundtable Transcript](https://herald-ui.vercel.app/docs/roundtable-transcript): Multi-speaker conversation with transport controls. — `npx shadcn add @herald-ui/roundtable-transcript`
- [Provider Manager](https://herald-ui.vercel.app/docs/provider-manager): Manage BYO OpenAI-compatible providers. — `npx shadcn add @herald-ui/provider-manager`
- [Persona Builder](https://herald-ui.vercel.app/docs/persona-builder): Compose an AI character in one form. — `npx shadcn add @herald-ui/persona-builder`
- [Model Card Browser](https://herald-ui.vercel.app/docs/model-card-browser): Searchable visual model/LoRA picker. — `npx shadcn add @herald-ui/model-card-browser`
- [Knowledge Graph](https://herald-ui.vercel.app/docs/knowledge-graph): A dependency-free force-directed graph. — `npx shadcn add @herald-ui/knowledge-graph`
- [Mobile Tab Bar](https://herald-ui.vercel.app/docs/mobile-tab-bar): A safe-area-aware bottom tab bar. — `npx shadcn add @herald-ui/mobile-tab-bar`
- [Chat](https://herald-ui.vercel.app/docs/chat-panel): A full, drop-in chat surface — Thread + Composer + model picker. — `npx shadcn add @herald-ui/chat-panel`
- [Tool Manager](https://herald-ui.vercel.app/docs/tool-manager): Manage an agent's built-in tools and MCP servers, per-tool toggles included. — `npx shadcn add @herald-ui/tool-manager`
- [Schedule Board](https://herald-ui.vercel.app/docs/schedule-board): The gateway's cron wall — recurring jobs, countdowns, pause/run/delete. — `npx shadcn add @herald-ui/schedule-board`
- [App Shell](https://herald-ui.vercel.app/docs/app-shell): The sidebar + topbar + content frame for an AI OS. — `npx shadcn add @herald-ui/app-shell`

## Components

Primitives and AI-native components. After `npx shadcn add @herald-ui/<name>` the source lands locally — import from `@/components/ui/<name>`.

- [Button](https://herald-ui.vercel.app/docs/button): Actions and links, seven variants across sizes. — `npx shadcn add @herald-ui/button`
- [Accordion](https://herald-ui.vercel.app/docs/accordion): A vertically stacked set of disclosures. — `npx shadcn add @herald-ui/accordion`
- [Alert](https://herald-ui.vercel.app/docs/alert): A callout for important messages. — `npx shadcn add @herald-ui/alert`
- [Carousel](https://herald-ui.vercel.app/docs/carousel): A slideshow of content panels. — `npx shadcn add @herald-ui/carousel`
- [Badge](https://herald-ui.vercel.app/docs/badge): Compact status and metadata labels. — `npx shadcn add @herald-ui/badge`
- [Input](https://herald-ui.vercel.app/docs/input): A single-line text field. — `npx shadcn add @herald-ui/input`
- [Textarea](https://herald-ui.vercel.app/docs/textarea): A multiline text field. — `npx shadcn add @herald-ui/textarea`
- [Label](https://herald-ui.vercel.app/docs/label): An accessible form label. — `npx shadcn add @herald-ui/label`
- [Dialog](https://herald-ui.vercel.app/docs/dialog): A modal dialog. — `npx shadcn add @herald-ui/dialog`
- [Popover](https://herald-ui.vercel.app/docs/popover): A floating panel anchored to a trigger. — `npx shadcn add @herald-ui/popover`
- [Tooltip](https://herald-ui.vercel.app/docs/tooltip): A hover / focus label. — `npx shadcn add @herald-ui/tooltip`
- [Dropdown Menu](https://herald-ui.vercel.app/docs/dropdown-menu): A menu of actions. — `npx shadcn add @herald-ui/dropdown-menu`
- [Switch](https://herald-ui.vercel.app/docs/switch): A binary on/off toggle. — `npx shadcn add @herald-ui/switch`
- [Slider](https://herald-ui.vercel.app/docs/slider): A single- or multi-value range slider. — `npx shadcn add @herald-ui/slider`
- [Toggle](https://herald-ui.vercel.app/docs/toggle): A two-state pressable button. — `npx shadcn add @herald-ui/toggle`
- [Toggle Group](https://herald-ui.vercel.app/docs/toggle-group): A set of grouped toggles. — `npx shadcn add @herald-ui/toggle-group`
- [Calendar](https://herald-ui.vercel.app/docs/calendar): A date picker on react-day-picker. — `npx shadcn add @herald-ui/calendar`
- [Skeleton](https://herald-ui.vercel.app/docs/skeleton): A loading placeholder. — `npx shadcn add @herald-ui/skeleton`
- [Spinner](https://herald-ui.vercel.app/docs/spinner): A loading indicator. — `npx shadcn add @herald-ui/spinner`
- [Kbd](https://herald-ui.vercel.app/docs/kbd): A keyboard shortcut hint. — `npx shadcn add @herald-ui/kbd`
- [Breadcrumb](https://herald-ui.vercel.app/docs/breadcrumb): A path of links to the current page. — `npx shadcn add @herald-ui/breadcrumb`
- [Separator](https://herald-ui.vercel.app/docs/separator): A visual divider. — `npx shadcn add @herald-ui/separator`
- [Sonner](https://herald-ui.vercel.app/docs/sonner): Toast notifications. — `npx shadcn add @herald-ui/sonner`
- [Drawer](https://herald-ui.vercel.app/docs/drawer): A draggable bottom sheet on Vaul — scopeable to a container. — `npx shadcn add @herald-ui/drawer`
- [Avatar](https://herald-ui.vercel.app/docs/avatar): An image avatar with an initials-and-hue fallback. — `npx shadcn add @herald-ui/avatar`
- [Card](https://herald-ui.vercel.app/docs/card): A surface for grouping related content. — `npx shadcn add @herald-ui/card`
- [Empty State](https://herald-ui.vercel.app/docs/empty-state): A placeholder for empty lists and screens. — `npx shadcn add @herald-ui/empty-state`
- [Progress](https://herald-ui.vercel.app/docs/progress): A determinate linear progress bar. — `npx shadcn add @herald-ui/progress`
- [Progress Ring](https://herald-ui.vercel.app/docs/progress-ring): A compact SVG completion donut. — `npx shadcn add @herald-ui/progress-ring`
- [Tabs](https://herald-ui.vercel.app/docs/tabs): Layered sections toggled by a segmented control. — `npx shadcn add @herald-ui/tabs`
- [Alert Dialog](https://herald-ui.vercel.app/docs/alert-dialog): A focus-trapped modal that confirms destructive actions. — `npx shadcn add @herald-ui/alert-dialog`
- [Select](https://herald-ui.vercel.app/docs/select): A single-select dropdown on an input-style trigger. — `npx shadcn add @herald-ui/select`
- [Combobox](https://herald-ui.vercel.app/docs/combobox): A searchable single-select with type-to-filter. — `npx shadcn add @herald-ui/combobox`
- [Context Menu](https://herald-ui.vercel.app/docs/context-menu): A cursor-anchored right-click menu with submenus. — `npx shadcn add @herald-ui/context-menu`
- [Stat Tile](https://herald-ui.vercel.app/docs/stat-tile): A KPI cell with a trend delta for dashboards. — `npx shadcn add @herald-ui/stat-tile`
- [Filter Chip](https://herald-ui.vercel.app/docs/filter-chip): Removable, toggleable active-filter pills. — `npx shadcn add @herald-ui/filter-chip`
- [Message Actions](https://herald-ui.vercel.app/docs/message-actions): Hover-revealed copy / edit / regenerate row. — `npx shadcn add @herald-ui/message-actions`
- [Source Chips](https://herald-ui.vercel.app/docs/source-chips): Numbered citation pills for RAG answers. — `npx shadcn add @herald-ui/source-chips`
- [Censorable Image](https://herald-ui.vercel.app/docs/censorable-image): Blur-until-reveal for sensitive or spoiler media. — `npx shadcn add @herald-ui/censorable-image`
- [Prompt Starters](https://herald-ui.vercel.app/docs/prompt-starters): Clickable suggestion chips for an empty composer. — `npx shadcn add @herald-ui/prompt-starters`
- [Sampling Params](https://herald-ui.vercel.app/docs/sampling-params): Temperature + collapsible advanced LLM knobs. — `npx shadcn add @herald-ui/sampling-params`
- [Conversation Export](https://herald-ui.vercel.app/docs/conversation-export): Share a transcript as copyable / downloadable Markdown. — `npx shadcn add @herald-ui/conversation-export`
- [Voice Input](https://herald-ui.vercel.app/docs/voice-input): Push-to-talk mic button + dictation hook. — `npx shadcn add @herald-ui/voice-input`
- [Attachment Tray](https://herald-ui.vercel.app/docs/attachment-tray): Image attach / paste / drag-drop for a composer. — `npx shadcn add @herald-ui/attachment-tray`
- [Slash Commands](https://herald-ui.vercel.app/docs/slash-command-palette): Inline "/" command autocomplete above a composer. — `npx shadcn add @herald-ui/slash-command-palette`
- [Tag Autocomplete](https://herald-ui.vercel.app/docs/tag-autocomplete): Caret-aware prompt-tag autocomplete with weight stepping. — `npx shadcn add @herald-ui/tag-autocomplete`
- [Agent Status Card](https://herald-ui.vercel.app/docs/agent-status-card): A card summarizing an agent's health and stats. — `npx shadcn add @herald-ui/agent-status-card`
- [Prop List](https://herald-ui.vercel.app/docs/prop-list): Key→value inspector rows for detail panels. — `npx shadcn add @herald-ui/prop-list`
- [Bar List](https://herald-ui.vercel.app/docs/bar-list): Ranked horizontal bars for top-N by metric. — `npx shadcn add @herald-ui/bar-list`
- [Sparkline](https://herald-ui.vercel.app/docs/sparkline): A tiny inline trend chart for KPI rows. — `npx shadcn add @herald-ui/sparkline`
- [Theme Toggle](https://herald-ui.vercel.app/docs/theme-mode-toggle): A light / dark / system segmented control. — `npx shadcn add @herald-ui/theme-mode-toggle`
- [Accent Hue Picker](https://herald-ui.vercel.app/docs/accent-hue-picker): Pick a brand accent on the OKLCH hue wheel. — `npx shadcn add @herald-ui/accent-hue-picker`
- [Radius Picker](https://herald-ui.vercel.app/docs/radius-picker): Segmented control for the global corner radius. — `npx shadcn add @herald-ui/radius-picker`
- [Status Badge](https://herald-ui.vercel.app/docs/status-badge): A colored dot + label for live/idle/error state. — `npx shadcn add @herald-ui/status-badge`
- [Date Field](https://herald-ui.vercel.app/docs/date-field): An ISO-bound date input with a Calendar popover. — `npx shadcn add @herald-ui/date-field`
- [Property Select](https://herald-ui.vercel.app/docs/property-select): Single-select field with per-option glyphs. — `npx shadcn add @herald-ui/property-select`
- [Column Chart](https://herald-ui.vercel.app/docs/column-chart): Vertical bars over time for usage or cost. — `npx shadcn add @herald-ui/column-chart`
- [Storage Meter](https://herald-ui.vercel.app/docs/storage-meter): A stacked usage bar broken down by source. — `npx shadcn add @herald-ui/storage-meter`
- [Selection Bar](https://herald-ui.vercel.app/docs/selection-bar): Floating bulk-actions toolbar for multi-select. — `npx shadcn add @herald-ui/selection-bar`
- [Settings Section](https://herald-ui.vercel.app/docs/settings-section): Titled card of labeled rows with controls. — `npx shadcn add @herald-ui/settings-section`
- [Recurrence Field](https://herald-ui.vercel.app/docs/recurrence-field): Repeat-rule editor + a pure recurrence engine. — `npx shadcn add @herald-ui/recurrence-field`
- [User Menu](https://herald-ui.vercel.app/docs/user-menu): Account trigger + dropdown for a shell. — `npx shadcn add @herald-ui/user-menu`
- [Markdown](https://herald-ui.vercel.app/docs/markdown): GFM markdown with syntax-highlighted, copyable code. — `npx shadcn add @herald-ui/markdown`
- [Tool Card](https://herald-ui.vercel.app/docs/tool-card): A tool-call card with details and result disclosures. — `npx shadcn add @herald-ui/tool-card`
- [Message](https://herald-ui.vercel.app/docs/message): Renders a message from its typed parts[]. — `npx shadcn add @herald-ui/message`
- [Thread](https://herald-ui.vercel.app/docs/thread): A chat transcript rendered from the typed parts[] model. — `npx shadcn add @herald-ui/thread`
- [Composer](https://herald-ui.vercel.app/docs/composer): A controlled multiline input with send/stop and slots. — `npx shadcn add @herald-ui/composer`
- [Model Picker](https://herald-ui.vercel.app/docs/model-picker): A grouped agents/providers target picker. — `npx shadcn add @herald-ui/model-picker`
- [Command Palette](https://herald-ui.vercel.app/docs/command-palette): A global ⌘K command palette. — `npx shadcn add @herald-ui/command-palette`
- [Approval Card](https://herald-ui.vercel.app/docs/approval-card): A human-in-the-loop permission gate rendered from an approval part. — `npx shadcn add @herald-ui/approval-card`
- [Data Table](https://herald-ui.vercel.app/docs/data-table): A typed, sortable, multi-select table — zero table library. — `npx shadcn add @herald-ui/data-table`
- [Log Viewer](https://herald-ui.vercel.app/docs/log-viewer): A live-tailing log console with severity filters and a reading-aware autoscroll. — `npx shadcn add @herald-ui/log-viewer`

## Hooks

Framework-agnostic logic. After `npx shadcn add @herald-ui/<name>` the source lands locally — import from `@/hooks/<name>`.

- [useStreamClock](https://herald-ui.vercel.app/docs/use-stream-clock): Live elapsed timer that freezes to a final duration. — `npx shadcn add @herald-ui/use-stream-clock`
- [useTurnRunner](https://herald-ui.vercel.app/docs/use-turn-runner): Multi-agent round-robin speaker orchestrator. — `npx shadcn add @herald-ui/use-turn-runner`
- [useGeneration](https://herald-ui.vercel.app/docs/use-generation): Blocking submit → poll → result job lifecycle. — `npx shadcn add @herald-ui/use-generation`
- [useUndoableDelete](https://herald-ui.vercel.app/docs/use-undoable-delete): Optimistic delete with an Undo toast. — `npx shadcn add @herald-ui/use-undoable-delete`
- [useStream](https://herald-ui.vercel.app/docs/use-stream): The SSE → parts[] streaming hook. — `npx shadcn add @herald-ui/use-stream`

## Foundation

- [utils](https://herald-ui.vercel.app/docs/utils): The cn() class-merge helper every component uses. — `npx shadcn add @herald-ui/utils`
- [tokens](https://herald-ui.vercel.app/docs/tokens): The OKLCH design-token layer — parametric brand hue, radius, light/dark. — `npx shadcn add @herald-ui/tokens`
- [format](https://herald-ui.vercel.app/docs/format): Shared formatting utils — the one relative-time vocabulary (formatRelativeTime) + RelativeTime type. — `npx shadcn add @herald-ui/format`
- [chat-types](https://herald-ui.vercel.app/docs/chat-types): The typed parts[] chat message model (text/reasoning/tool/image/error). — `npx shadcn add @herald-ui/chat-types`
- [chat-styles](https://herald-ui.vercel.app/docs/chat-styles): Prose + shimmer styles for markdown and streaming chat surfaces. — `npx shadcn add @herald-ui/chat-styles`
- [stream](https://herald-ui.vercel.app/docs/stream): SSE → parts[] parsing primitives used by useStream. — `npx shadcn add @herald-ui/stream`