# ARC UI
> ARC Radiant Components — a dark-first Web Component library built with Lit. One Web Component source; identical component APIs across 7 targets.
- Version: 4.2.2
- Components: 166
- Targets: Web Components (canonical), React, Vue, Svelte, Angular, Solid, Preact, plain HTML/CSS
- License: MIT
## Installation
```bash
# Web Components (canonical)
npm install @arclux/arc-ui lit
# React
npm install @arclux/arc-ui-react @arclux/arc-ui lit
# Vue
npm install @arclux/arc-ui-vue @arclux/arc-ui lit
# Svelte
npm install @arclux/arc-ui-svelte @arclux/arc-ui lit
# Angular
npm install @arclux/arc-ui-angular @arclux/arc-ui lit
# Solid
npm install @arclux/arc-ui-solid @arclux/arc-ui lit
# Preact
npm install @arclux/arc-ui-preact @arclux/arc-ui lit
# Plain HTML (standalone HTML/CSS package, no JS)
npm install @arclux/arc-ui-html
```
## Quick Start
```html
Get Started
```
```jsx
// React
import { Button } from '@arclux/arc-ui-react';
Get Started
```
Registering components:
- `import '@arclux/arc-ui/'` registers a single element via its subpath export.
- `import '@arclux/arc-ui/register'` registers every component at once.
- Exception: `arc-code-block` is NOT included in the register barrel because it carries a heavy syntax highlighter. It must be imported explicitly with `import '@arclux/arc-ui/code-block'`.
## Architecture
Framework packages are generated from the Lit Web Component source. Practical consequences:
- Props, events, slots, and CSS parts are identical in every target — anything documented for `` applies to React's ``, Vue's ``, etc.
- Wrapper packages are generated output; the Web Component package (`@arclux/arc-ui`) is the source of truth. File issues against it.
- `@arclux/arc-ui-html` is standalone HTML/CSS with no JavaScript.
### Tiers
Components are organized into seven tiers by responsibility:
- **Layout** — page structure (shells, grids, containers)
- **Navigation** — wayfinding (tabs, menus, breadcrumbs)
- **Content** — display (cards, avatars, icons, carousels)
- **Data** — structured data (tables, lists, badges, meters, stats)
- **Typography** — text rendering (code blocks, markdown, kbd)
- **Input** — user interaction (buttons, forms, pickers)
- **Feedback** — system response (alerts, modals, toasts)
## Theming
The theme is dark by default. Set `data-theme="light"` on `` for light mode, or `data-theme="auto"` to follow `prefers-color-scheme`.
Compound tokens (gradients, glows, focus rings, shadows) reference base tokens via `var()`, so overriding the base accent tokens re-themes the entire library:
```css
:root {
--accent-primary: #your-brand-blue;
--accent-primary-rgb: R, G, B;
--accent-secondary: #your-brand-purple;
--accent-secondary-rgb: R, G, B;
}
```
## Font Roles
ARC UI ships no font files. Typography is five role slots — `body`, `label`, `mono`, `display`, `quote` — each exposed as `--font-` (composed stack) plus `--font--family`, `--font--fallback`, and `--font--weight`. Components reference roles, never typefaces, so assigning a face is one override:
```css
:root {
--font-body-family: 'Your Face';
}
```
- `body` — used for prose, inputs, and headings; the default for everything.
- `label` — used for form labels, table headers, and eyebrows (small, uppercase, tracked type).
- `mono` — used for code, keyboard hints, and tabular numerics.
- `display` — used for large headings; it follows `body` until assigned its own family.
- `quote` — used for the decorative glyph on `arc-blockquote`.
## Server-Side Rendering
`@arclux/arc-ui/ssr` exports `renderDeclarativeShadowDOM(html)` — HTML in, HTML out. Every `` in the input gets a declarative shadow root, regardless of what produced the markup (Next, Nuxt, SvelteKit, Astro, a hand-assembled string). All components server-render. Requires the optional peer `@lit-labs/ssr`. On the client, import `@arclux/arc-ui/hydrate` before any component is defined so Lit adopts the server markup instead of re-rendering it.
## Components (166)
### Layout (19)
- Container (``) — Max-width wrapper for page sections.
- Section (``) — Page section with optional uppercase label, consistent spacing.
- App Shell (``) — Full-page layout scaffold that composes a TopBar, Sidebar, and scrollable content area into a cohesive application frame.
- Auth Shell (``) — Authentication page layout with centered and split variants for sign-in, sign-up, password-reset, and other credential flows.
- Dashboard Grid (``) — Responsive grid for dashboard metric cards.
- Page Header (``) — Page title area with positional slots for composing breadcrumbs, actions, tabs, or any content around a heading and description.
- Page Layout (``) — Page structure primitive that arranges content into sidebar-left, sidebar-right, centered, or wide layouts using CSS Grid.
- Resizable (``) — Resizable panel with drag handle.
- Settings Layout (``) — Settings page with side navigation and content area.
- Split Pane (``) — Resizable split layout with two panes.
- Status Bar (``) — Bottom status bar with prefix, center, and suffix slots.
- Toolbar (``) — Horizontal toolbar with prefix, center, and suffix slots.
- Masonry (``) — Pinterest-style vertical-pack grid using CSS columns for efficient masonry layout without JavaScript.
- Float Bar (``) — Viewport-bottom floating toolbar with surface-overlay background, backdrop blur, and spring easing.
- Aspect Grid (``) — Uniform aspect-ratio cell grid with configurable columns and ratio.
- Inset (``) — Padding primitive consuming spacing tokens with optional negative-margin bleed mode.
- Sticky (``) — Wrapper that goes sticky at a configurable offset and emits a stuck attribute/event for visual state changes.
- Responsive Switcher (``) — Container-query-based layout that flips between horizontal and vertical at a threshold width.
- Center (``) — Content centering primitive with max-width, intrinsic centering, and text-center options.
### Navigation (22)
- Tabs (``) — Tabbed content navigation with keyboard support and ARIA roles.
- Breadcrumb (``) — Wayfinding navigation trail that shows the user their current location within a hierarchical page structure, with separator icons and current-page indication.
- Drawer (``) — Slide-out panel with backdrop overlay, keyboard dismissal, and left/right positioning for off-canvas navigation, filters, and detail views.
- Footer (``) — Page footer with branding, link columns, and legal text.
- Link (``) — Styled anchor with nav, muted, and default variants.
- Navigation Menu (``) — Horizontal navigation bar with hover-triggered dropdown sub-menus and full keyboard accessibility.
- Pagination (``) — Page navigation control with previous/next arrows, numbered page buttons, and smart ellipsis truncation.
- Scroll Spy (``) — Tracks scroll position and highlights the active navigation link.
- Sidebar (``) — Collapsible navigation sidebar with grouped sections, heading labels, and active link highlighting.
- Top Bar (``) — Fixed header bar that anchors every page with a brand slot on the left, an optional center navigation area, and a right-aligned actions region for user controls, search, and settings.
- Tree View (``) — Hierarchical tree structure with expandable/collapsible nodes, selection tracking, keyboard navigation, and indentation guide lines.
- Scroll To Top (``) — Floating button that appears after scrolling and smoothly returns the user to the top of the page.
- Scroll Indicator (``) — Thin progress bar that tracks scroll position of the page or a target container.
- Command Bar (``) — Always-visible search input designed to sit inside a top bar.
- Stepper Nav (``) — Wizard navigation with back/next/skip controls and step validation gates.
- Bottom Nav (``) — Mobile bottom bar with icon + label items.
- Skip Link (``) — Accessible skip-to-content link, invisible until focused.
- Anchor Nav (``) — Vertical or horizontal in-page link bar with active highlight.
- Breadcrumb Menu (``) — Each breadcrumb segment doubles as a dropdown showing sibling pages at that hierarchy level.
- Rail (``) — Ultra-narrow icon-only vertical navigation like VS Code's activity bar.
- Page Indicator (``) — Dot-based position indicator for page-level navigation or onboarding flows.
- Menubar (``) — Desktop-application-style menu bar (File / Edit / View) with nested submenus, keyboard shortcuts display, and full WAI-ARIA menubar keyboard navigation.
### Content (26)
- Card (``) — Content container with subtle border styling and hover effects.
- Feature Card (``) — Card with icon, heading, description, and animated hover effects.
- Divider (``) — Horizontal rule with multiple visual styles from subtle to glowing.
- Accordion (``) — Expandable content sections with smooth height animations.
- Avatar (``) — User avatar with image or initials fallback.
- Avatar Group (``) — Stack of avatars with overflow count badge.
- Color Swatch (``) — Color sample square with label — useful for token docs.
- CTA Banner (``) — Full-width call-to-action banner with gradient background, eyebrow text, headline, body copy, and action buttons.
- Empty State (``) — Placeholder for empty lists or search results.
- Icon (``) — Renders icons by name from any registered library — Phosphor (1,500+) and Lucide (1,900+) ship in `@arclux/arc-ui-icons` — with one-line library switching and custom icon registration.
- Skeleton (``) — Loading placeholder with shimmer animation.
- Spinner (``) — Animated loading spinner in three sizes.
- Collapsible (``) — A disclosure widget with a clickable heading that toggles the visibility of its slotted content using a smooth CSS grid animation.
- Carousel (``) — A scrollable slide container with navigation arrows, dot indicators, auto-play, looping, and keyboard controls.
- Infinite Scroll (``) — Intersection Observer-powered container that fires a load event when the user scrolls near the bottom, with built-in loading spinner and end-of-list state.
- Scroll Area (``) — Styled scrollable container with custom thin scrollbar styling for Webkit and Firefox, configurable orientation, and optional max-height constraint.
- Aspect Ratio (``) — Container that enforces a consistent width-to-height ratio on its content, ideal for images, videos, and embedded media.
- Marquee (``) — Continuously scrolling content strip with configurable speed, direction, gap, and pause-on-hover behavior for logos, testimonials, and announcements.
- Stack (``) — Flexbox layout component for vertical or horizontal stacking with token-based spacing.
- Image (``) — Enhanced image component with shimmer loading skeleton, smooth fade-in transition, error fallback, and aspect ratio presets.
- Virtual List (``) — Windowed list that renders only visible items for efficient scrolling through thousands of rows.
- QR Code (``) — Client-side QR code renderer that encodes any string into a crisp inline SVG.
- Lightbox (``) — Full-screen image viewer on the overlay stack: open from a thumbnail, step through a gallery with wrapping prev/next navigation, zoom to 2x with drag-to-pan, and dismiss with Escape or a backdrop click.
- Image Compare (``) — Before/after comparison with two layered images and a draggable divider revealing one over the other.
- Image Hotspots (``) — An annotated image with glowing pin markers, each opening a small popover of detail content.
- Video (``) — House-styled video player with a glowing poster play overlay and minimal custom controls over the native video element.
### Data (24)
- Value Card (``) — Horizontal card with icon and text, for values or features lists.
- Stat (``) — Numeric statistic display with gradient value and label.
- Badge (``) — Compact pill-shaped label for status indicators, category tags, and notification counts.
- Stepper (``) — Step indicator for multi-step workflows.
- Tag (``) — Compact pill-shaped label with color variants, custom color support, and an optional remove button, for categorisation, filtering, and selection feedback.
- Timeline (``) — Vertical timeline with dated events.
- Meter (``) — Semantic gauge display with color-coded fill zones (success, warning, error) based on configurable low/high/optimum thresholds.
- Animated Number (``) — Smooth count-up/down number animation with formatting options.
- List (``) — Structured list container with optional selection, keyboard navigation, and multiple visual variants.
- Diff (``) — Line-based text diff viewer with inline and side-by-side display modes.
- Countdown Timer (``) — Live countdown to a target date/time with days, hours, minutes, and seconds segments.
- Comparison (``) — A two-column or multi-column comparison table for pricing tiers, feature breakdowns, or before/after comparisons.
- Sparkline (``) — Tiny inline SVG chart for embedding lightweight line or bar visualizations inside tables, stat cards, and dashboards.
- Description List (``) — Structured term/detail pair list in a responsive grid layout with optional dividers.
- Chart (``) — An SVG chart component for dashboards with line, area, bar, and donut types.
- Data Grid (``) — A spreadsheet-grade grid for working with tabular data: inline cell editing, multi-column sorting, pinned columns, row selection, and virtualized rendering.
- Kanban (``) — A drag-and-drop kanban board driven by a `columns` data array.
- Gauge (``) — Radial gauge displaying a scalar value on an arc with color-coded zones (success, warning, error) and an animated sweep.
- Waveform (``) — Audio waveform visualization that doubles as a scrubber.
- Level Meter (``) — Segmented audio level meter with peak-hold.
- Clock (``) — Live clock with a digital or analog face, optionally pinned to an IANA timezone.
- Uptime (``) — Status-page uptime history strip: one slim tick per period, colored by status, with hover and keyboard detail.
- JSON Tree (``) — Collapsible JSON explorer with house syntax coloring — the dev-tools inspector for API payloads, configuration objects, and structured state.
- Activity Heatmap (``) — GitHub-style contribution calendar: a year of day cells, one column per week, each tinted by intensity on a five-step accent ramp, with hover and keyboard detail.
### Typography (14)
- Text (``) — Typography component with variants matching the arclight type scale.
- Code Block (``) — Syntax-highlighted code display with optional filename and copy button.
- Kbd (``) — Keyboard key indicator styled like a physical key.
- Truncate (``) — Multi-line text clamping with expandable show-more toggle.
- Highlight (``) — Text highlighting with search query match markers.
- Markdown (``) — Renders markdown content as styled HTML with zero dependencies.
- Blockquote (``) — Styled pull-quote with optional citation for editorial emphasis.
- Prose (``) — Long-form content container that applies typographic rhythm and styling to slotted HTML elements.
- Typewriter (``) — Character-by-character text reveal animation with blinking cursor.
- Gradient Text (``) — Inline text wrapper that applies gradient fills to text declaratively.
- Number Format (``) — Locale-aware number, currency, percentage, and compact formatter using Intl.
- Time Ago (``) — Relative time display that auto-updates ("3 minutes ago", "yesterday").
- Terminal (``) — Animated terminal window that types commands and prints their output line by line.
- Keyboard Map (``) — A rendered keyboard with highlighted keys and chords — the visual big sibling of Kbd and Hotkey, for shortcut documentation and editor cheat sheets.
### Input (43)
- Button (``) — Primary call-to-action element with three visual variants that map to action hierarchy.
- Input (``) — Versatile form control supporting single-line text, email, password, and multiline textarea modes with built-in label, placeholder, and validation states.
- Toggle (``) — On/off switch with smooth animation, glow effect, and ARIA switch role.
- Checkbox (``) — Multi-select form control supporting checked, indeterminate, and disabled states.
- Radio Group (``) — Single-select option group with arrow-key navigation and ARIA radiogroup semantics.
- Select (``) — Dropdown select with searchable options, keyboard navigation, and full ARIA listbox semantics for accessible form inputs.
- Calendar (``) — Interactive month-view calendar grid for date selection with min/max constraints, keyboard navigation, and today highlighting.
- Combobox (``) — Searchable dropdown with type-ahead filtering.
- Copy Button (``) — One-click copy-to-clipboard button with confirmation.
- Date Picker (``) — Calendar-based date picker with keyboard navigation.
- File Upload (``) — Drag-and-drop file upload zone with preview.
- Form (``) — Form wrapper with built-in validation, error aggregation, and submit handling.
- Icon Button (``) — Compact button that renders an icon with optional text label, supporting ghost, secondary, and primary variants.
- Multi Select (``) — Multi-value select with tag chips, inline search filtering, and keyboard navigation.
- Search (``) — Search input with a magnifying glass icon, clear button, loading spinner, and autocomplete suggestions dropdown.
- Range Slider (``) — Dual-thumb range slider for selecting a numeric interval within a defined range, with accent-primary fill between the thumbs and live value display.
- Slider (``) — Range input slider with a label, live numeric value display, accent-primary fill track, and customisable min/max/step.
- Textarea (``) — Multi-line text input with integrated label, placeholder, resize control, and live character count that turns red at the limit.
- Theme Toggle (``) — Three-state theme toggle cycling through dark, light, and auto modes with animated icon transitions and localStorage persistence.
- Segmented Control (``) — A radio-group-style toggle bar that renders slotted arc-option elements as a row of mutually exclusive buttons with an active highlight.
- Number Input (``) — A numeric stepper input with decrement and increment buttons flanking a central text field, supporting min/max clamping, step increments, and keyboard shortcuts.
- Rating (``) — A star-based rating input with hover preview, keyboard navigation, filled/unfilled SVG stars, and configurable max value.
- Chip (``) — A toggleable pill-shaped element for filters, tags, or multi-select options, with a selected state highlighted in accent-primary.
- Sortable List (``) — Drag-and-drop reorderable list with grip handles, keyboard reordering support, and visual insertion indicators.
- Color Picker (``) — Full-featured color picker with a saturation/lightness area, hue slider, hex input, and optional preset swatches.
- Pin Input (``) — One-character-per-box input for PINs, OTPs, and verification codes with auto-advance, paste support, and optional masking.
- Label (``) — Form label with required indicator, optional description text, and tooltip slot.
- Fieldset (``) — Grouped form section with legend, description, error message, and optional card variant.
- Switch Group (``) — Groups multiple toggle switches under a shared label with consistent sizing and disabled state.
- Button Group (``) — Connects multiple buttons into a single visual unit with shared borders and collapsed radii.
- Input Group (``) — Combines an input with prefix and suffix addon slots for labels, icons, or buttons attached to the input border.
- Hotkey (``) — Invisible keyboard shortcut listener that supports modifier combos (Ctrl+K) and chord sequences (g i).
- Time Picker (``) — Scrollable column-based time picker with 12h/24h format support.
- Date Range Picker (``) — Dual-calendar picker for selecting a start/end date range with presets and full keyboard navigation.
- Tag Input (``) — Free-text token entry field with optional autocomplete suggestions, delimiter splitting, and duplicate rejection.
- Password Input (``) — Password entry field with a built-in visibility toggle and an optional four-segment strength meter.
- Transfer List (``) — Dual-listbox for moving items between an available and a selected pane, ideal for permissions and settings UIs.
- Image Cropper (``) — Crop-before-upload control with a draggable, resizable crop rectangle, aspect-ratio locking, zoom, and canvas export at natural image resolution.
- Knob (``) — Rotary knob input for continuous parameters, with a glowing 270-degree arc fill, vertical-drag interaction, magnetic detents, and a monospace value readout.
- Signature Pad (``) — Canvas signature capture that participates in forms — freehand strokes serialize to a PNG data-URL and submit as the field value.
- Masked Input (``) — Text field that enforces a character mask as you type — dates, card numbers, phone numbers, license keys.
- Tree Select (``) — Dropdown select whose panel is a hierarchical tree — categories, instrument banks, folder pickers.
- Inline Edit (``) — Click-to-edit text that renders as plain content until activated, then swaps to a pre-filled field.
### Feedback (18)
- Alert (``) — Contextual alert banner with five semantic variants and optional dismiss button for delivering timely, prominent feedback to users.
- Progress (``) — Progress indicator as a bar or spinner, with determinate and indeterminate modes.
- Toast (``) — Stack-managed notification toasts with auto-dismiss, variant-colored indicators, configurable position, and smooth enter/exit animations.
- Tooltip (``) — Contextual hint that appears on hover or focus, providing supplementary information without cluttering the UI.
- Command Palette (``) — Spotlight-style command palette with search and keyboard shortcuts.
- Context Menu (``) — Right-click context menu with keyboard shortcuts.
- Dropdown Menu (``) — Menu dropdown triggered by a button with keyboard navigation.
- Hover Card (``) — Card that appears on hover with a delay.
- Notification Panel (``) — Notification dropdown panel triggered by a button.
- Popover (``) — Floating content panel anchored to a trigger element, with four placement positions and automatic outside-click dismissal.
- Sheet (``) — A sliding overlay panel that emerges from the bottom or right edge of the viewport, with a blurred backdrop, header, scrollable body, and footer slot.
- Dialog (``) — General-purpose focus-trapping overlay on the platform — backdrop blur, slide-up entrance, and Escape-to-dismiss for forms, settings, and rich content that needs full user attention.
- Banner (``) — Full-width persistent strip pinned to viewport or section top.
- Confirm (``) — Programmatic confirmation API that wraps dialog.
- Loading Overlay (``) — Semi-transparent surface-overlay with backdrop blur covering a container or page.
- Connection Status (``) — Auto-detects online/offline via navigator API.
- Announcement (``) — ARIA live-region wrapper with no visual output.
- Conversation (``) — An AI chat transcript: role-attributed messages in a scrollable column that follows new replies without ever yanking a reader who scrolled up.
## Further Reading
- [Full component reference with props, events, and examples](/llms-full.txt)
- [Documentation site](https://arcui.dev)
- [Component pages](https://arcui.dev/docs/components/)
- [Theming guide](https://arcui.dev/docs/theming/)
- [Typography and font roles](https://arcui.dev/docs/typography/)
- [Token reference](https://arcui.dev/docs/tokens/)