# Accessibility
URL: https://www.spaceui.one/docs/accessibility

***

title: Accessibility
description: How is accessibility with Space UI?
------------------------------------------------

Animations can greatly enhance user experience, but they can also create accessibility issues if not handled with care. Some users are sensitive to motion and may experience discomfort, dizziness, or difficulty focusing when faced with strong visual effects.

To address this, operating systems and browsers expose a setting called **Reduced Motion** (`prefers-reduced-motion`). When enabled, it communicates that the user prefers simpler or fewer animations.

## Core Principles

<Cards className="sm:grid-cols-2">
  <Card title="Prefers Reduced Motion" description="Automatically honors user OS preferences by neutralizing large translations, scaling, and aggressive physics." category="Comfort" badge="System Setting" dotColor="bg-blue-400" ringColor="bg-blue-300" actionLabel="Learn More" href="#prefers-reduced-motion" />

  <Card title="MotionConfig Provider" description="A single root-level wrapper delivers seamless WCAG 2.2 AA compliant motion safety across all Space UI primitives." category="Engineering" badge="Zero Config" dotColor="bg-emerald-400" ringColor="bg-emerald-300" actionLabel="Setup Guide" href="#space-ui--motion" />
</Cards>

## Prefers Reduced Motion

`prefers-reduced-motion` is a CSS media query and system-level setting. If a user has enabled it, it usually means:

* Avoiding large-scale movement (scale, translate, rotate).
* Preferring subtle effects such as opacity fades.
* Disabling parallax or auto-scrolling animations.
* Turning off looping or auto-playing background motion.

The goal isn't to remove animation entirely, but to make it comfortable and safe.

## Space UI & Motion

Space UI **is built on top of [Motion](https://motion.dev/)**.
This means all Space UI components can leverage Motion’s accessibility features.

The recommended way to support Reduced Motion is to wrap your app with `MotionConfig`:

```tsx
import { MotionConfig } from 'motion/react'

export function App({ children }: { children: React.ReactNode }) {
  return <MotionConfig reducedMotion="user">{children}</MotionConfig>
}
```

With `reducedMotion="user"`, Motion will automatically:

* Disable transform and layout animations if the user has Reduced Motion enabled.
* Keep helpful transitions like opacity or background-color.

As a result, Space UI components will automatically respect user preferences without extra configuration.

## Conclusion

Accessible animations help ensure your UI is usable for everyone.
By combining Space UI with Motion’s `MotionConfig`, you can provide a smooth, animated experience while adapting gracefully to `prefers-reduced-motion`.

**We recommend adding `MotionConfig reducedMotion="user"` at the root of your app.**

For more details, see the [Motion documentation](https://motion.dev/docs/react-accessibility).


# AI Agents
URL: https://www.spaceui.one/docs/agents

***

title: AI Agents
description: Build faster and cleaner interfaces with autonomous AI coding agents, specialized skills, and MCP tools.
---------------------------------------------------------------------------------------------------------------------

import { IconArrowRight } from '@tabler/icons-react'
import { Frame, FrameHeader } from '@/registry/primitives/frame'
import { Card as CardPrimitives, CardPanel } from '@/registry/primitives/card'
import { Badge } from '@/registry/components/spaceui/badge-squircle'

Space UI is engineered from the ground up for both human developers and **autonomous AI coding agents** (Claude Code, Cursor, Windsurf, GitHub Copilot, Codex, and Antigravity).

Thanks to standard shadcn registry schemas, headless Base UI primitives, and typed Motion animations, AI models can inspect, install, compose, and refactor Space UI components with zero hallucination.

***

## The 3 Pillars of AI Integration

Space UI's agent ecosystem is structured into three dedicated layers:

<Cards className="sm:grid-cols-3">
  <Card href="/docs/mcp" title="MCP Server" description="Direct IDE tool integration exposing component search, TypeScript signatures, and autonomous installation." category="Tools · 01" badge="MCP Protocol" dotColor="bg-blue-400" ringColor="bg-blue-300" actionLabel="Setup guide" />

  <Card href="/docs/skills" title="Agent Skills" description="Rules and hard-won lessons in .agents/skills/ that your agent applies on its own." category="Guides · 02" badge="Skill Rules" dotColor="bg-green-400" ringColor="bg-green-300" actionLabel="Explore skills" />

  <Card href="/docs/llms" title="LLM Context" description=" Machine-readable endpoints (/llms.txt, /llms-full.txt, and raw per-component markdown)." category="Endpoints · 03" badge="Context Dumps" dotColor="bg-purple-400" ringColor="bg-purple-300" actionLabel="View endpoints" />
</Cards>

***

## How Agents Work with Space UI

When an AI agent operates in your workspace with Space UI:

<div className="not-prose my-6 flex flex-col gap-3">
  {/* Top: AI Agent */}

  <Frame>
    <FrameHeader className="flex flex-row items-center justify-between px-3 py-1.5">
      <span className="text-xs font-semibold text-muted-foreground tracking-wider">AI Agent</span>

      <Badge size="xs" variant="secondary" className="bg-background! text-foreground">
        <span className="relative flex justify-center items-center size-fit">
          <span className="absolute inline-flex h-full w-full rounded-full opacity-75 animate-ping animation-duration-[2.25s] bg-purple-300" />

          <span className="relative inline-flex rounded-full size-2.5 animate-pulse bg-purple-400" />
        </span>

        <span className="relative">Workspace Engine</span>
      </Badge>
    </FrameHeader>

    <CardPrimitives className="rounded-xl overflow-hidden bg-background">
      <CardPanel className="p-4">
        <h4 className="text-sm font-semibold text-foreground">Your AI Assistant</h4>

        <p className="text-xs text-muted-foreground mt-1">
          Claude Code, Cursor, Windsurf, GitHub Copilot, Antigravity
        </p>
      </CardPanel>
    </CardPrimitives>
  </Frame>

  <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
    <Frame className="flex flex-col h-full">
      <FrameHeader className="flex flex-row items-center justify-between px-3 py-1.5">
        <span className="text-xs font-semibold text-muted-foreground tracking-wider">1. Query & Install</span>

        <Badge size="xs" variant="secondary" className="bg-background! text-foreground">
          <span className="relative flex justify-center items-center size-fit">
            <span className="absolute inline-flex h-full w-full rounded-full opacity-75 animate-ping animation-duration-[2.25s] bg-blue-300" />

            <span className="relative inline-flex rounded-full size-2.5 animate-pulse bg-blue-400" />
          </span>

          <span className="relative">MCP Server</span>
        </Badge>
      </FrameHeader>

      <CardPrimitives className="flex-1 rounded-xl overflow-hidden bg-background">
        <CardPanel className="p-4 flex flex-col justify-between gap-3 h-full">
          <div>
            <h4 className="text-sm font-semibold text-foreground">@spaceui MCP Protocol</h4>

            <p className="text-xs text-muted-foreground mt-1 [&_p]:text-xs [&_p]:sm:text-sm [&_p]:leading-relaxed [&_p]:my-0">
              Autonomous component discovery, typed prop inspection, and CLI installation.
            </p>
          </div>

          <div className="flex flex-wrap gap-1.5">
            <Badge size="xs" variant="secondary">search_components</Badge>
            <Badge size="xs" variant="secondary">get_component</Badge>
            <Badge size="xs" variant="secondary">add_component</Badge>
          </div>
        </CardPanel>
      </CardPrimitives>
    </Frame>

    <Frame className="flex flex-col h-full">
      <FrameHeader className="flex flex-row items-center justify-between px-3 py-1.5">
        <span className="text-xs font-semibold text-muted-foreground tracking-wider">2. Guide & Refactor</span>

        <Badge size="xs" variant="secondary" className="bg-background! text-foreground">
          <span className="relative flex justify-center items-center size-fit">
            <span className="absolute inline-flex h-full w-full rounded-full opacity-75 animate-ping animation-duration-[2.25s] bg-green-300" />

            <span className="relative inline-flex rounded-full size-2.5 animate-pulse bg-green-400" />
          </span>

          <span className="relative">Agent Skills</span>
        </Badge>
      </FrameHeader>

      <CardPrimitives className="flex-1 rounded-xl overflow-hidden bg-background">
        <CardPanel className="p-4 flex flex-col justify-between gap-3 h-full">
          <div>
            <h4 className="text-sm font-semibold text-foreground">.agents/skills/ Rules</h4>

            <p className="text-xs text-muted-foreground mt-1 [&_p]:text-xs [&_p]:sm:text-sm [&_p]:leading-relaxed [&_p]:my-0">
              Rules and lessons your agent applies on its own.
            </p>
          </div>

          <div className="flex flex-wrap gap-1.5">
            <Badge size="xs" variant="secondary">space-motion</Badge>
          </div>
        </CardPanel>
      </CardPrimitives>
    </Frame>
  </div>

  <Frame>
    <FrameHeader className="flex flex-row items-center justify-between px-3 py-1.5">
      <span className="text-xs font-semibold text-muted-foreground tracking-wider">Output</span>

      <Badge size="xs" variant="secondary" className="bg-background! text-foreground">
        <span className="relative flex justify-center items-center size-fit">
          <span className="absolute inline-flex h-full w-full rounded-full opacity-75 animate-ping animation-duration-[2.25s] bg-orange-300" />

          <span className="relative inline-flex rounded-full size-2.5 animate-pulse bg-orange-400" />
        </span>

        <span className="relative">React 19</span>
      </Badge>
    </FrameHeader>

    <CardPrimitives className="rounded-xl overflow-hidden bg-background">
      <CardPanel className="p-4">
        <h4 className="text-sm font-semibold text-foreground">Your React Workspace</h4>

        <p className="text-xs text-muted-foreground mt-1 [&_p]:text-xs [&_p]:sm:text-sm [&_p]:leading-relaxed [&_p]:my-0">
          Base UI primitives, Tailwind CSS v4, and tactile motion in src/components/ui
        </p>
      </CardPanel>
    </CardPrimitives>
  </Frame>
</div>

***

## Best Practices for Agent Prompts

To get the highest quality code from your AI assistant:

### 1. Specify Component Handles

Always reference the exact `@spaceui/<component>` identifier so the agent fetches the official registry item:

```text
Add an interactive notification list using @spaceui/notification-list and @spaceui/badge.
```

### 2. Combine with Skills

Ask your agent to apply one of the [Space UI skills](/docs/skills) while it builds or reviews:

```text
Review the transitions of this dialog with space-motion and fix anything slower than it should be.
```

### 3. Use Copy Markdown for Context

If your agent does not have live MCP access, click the **"Copy Markdown"** button at the top of any component page and paste the complete spec into your prompt.


# Changelog
URL: https://www.spaceui.one/docs/changelog

***

title: Changelog
description: Latest updates and announcements.
----------------------------------------------

import { Changelog, ChangelogItem, ChangelogChange } from '@/components/docs/mdx/changelog'

<Changelog>
  <ChangelogItem date="2026-09-19" version="0.0.13" title="Shaders, Liquid Physics, Community Wall & Design Polish" summary="Procedural WGSL shaders, liquid metal and silk borders, fluid physics components, interactive community wall, and global design refinements.">
    <ChangelogChange kind="Components">
      * Added `LiquidMetalBorder` and `SilkBorder`: liquid metal flow and shimmering silk reactive borders with configurable lighting and angles.
      * Added procedural WebGPU/WGSL shaders:
        * `HeatShade`: procedural heat distortion shader with dynamic heat licks.
        * `SilkGradient`: fluid real-time silk wave gradient shader.
      * Added fluid physics & morphing components:
        * `LiquidSwitch`: fluid toggle switch with organic liquid morphing.
        * `LiquidSortableList`: drag-and-drop sortable list with smooth fluid transitions.
        * `SloshSlider`: interactive range slider with fluid slosh physics.
        * `SlideToConfirm`: interactive swipe/slide-to-action confirmation control.
        * `FrostBlurred`: frosted glass blur with chromatic diffusion and layered depth.
      * Added animated text & search components:
        * `MorphingText`: smooth text morphing between words and phrases.
        * `BlurRevealText`: staged kinetic blur-to-clear text reveal animation.
        * `MorphingCommandBar`, `MorphingSearchPill` & `MorphingArea`: expandable search pills and morphing command bar controls.
      * Added utility & layout components:
        * `AdaptiveDensityGrid`: dynamic layout grid with fluid cell packing.
        * `ChromaPalette`: interactive color palette previewer and selector.
        * `InteractiveChecklist`: micro-animated interactive checklist.
        * `TeamRosterSelector`: interactive team member selection widget.
    </ChangelogChange>

    <ChangelogChange kind="new">
      * Added `CommunityWall`: interactive infinite canvas block for community notes, stickers, and social badges.
      * Added `InteractiveGridHero`: hero block with proximity-reactive cursor mesh grid.
      * Added dedicated Pricing page with interactive savings calculator and plan comparisons.
      * Expanded **Emoji Explorer** asset catalog with 30,000+ indexed Unicode assets.
      * Added quick export drawer to **OG Image Generator**.
    </ChangelogChange>

    <ChangelogChange kind="improved">
      * Global design polish across landing sections, bento showcases, and navigation.
      * Enhanced component preview stages and documentation layouts.
      * Optimized WebGPU/WebGL shader rendering and frame pacing.
      * Refined typography hierarchy with custom Open Runde font pairings.
    </ChangelogChange>

    <ChangelogChange kind="fixed">
      * Fixed reactive storage synchronization in `useLocalStorage`.
      * Fixed threshold and trigger edge cases in `useLoadMore`.
      * Fixed WebGL context cleanup and memory disposal on component unmount.
    </ChangelogChange>
  </ChangelogItem>

  <ChangelogItem date="2026-09-14" version="0.0.12" title="Floating Multi-Pill Layout, New Components & Design Tools" summary="Modular floating island navigation dock, sticky sidebars overhaul, new UI components, interactive design tools suite, and bug fixes.">
    <ChangelogChange kind="Components">
      * Added `GitHubActivity`: interactive GitHub contribution heatmap supporting live user and repository commit activity.
      * Added `FluidCountdown`: fluid countdown timer with smooth slot-machine roll transitions powered by `@number-flow/react`.
      * Added `Thinking`: AI reasoning/thinking status bubble indicator with subtle pulsating animations.
      * Added `HandleReel`: animated handle ticker and reel ticker component.
      * Added `BadgeSquircle` and `ButtonSquircle`: squircle-shaped badges and buttons with tailored curvature.
      * Added new carousel blocks: Dither Carousel, Lens Carousel, Liquid Gooey Carousel, and Prism Carousel.
      * Added `Stats` block template featuring GitHub stats, commit graphs, and analytics cards.
    </ChangelogChange>

    <ChangelogChange kind="new">
      * Added Interactive Design Tools Suite:
        * **Flags Explorer**: vector flag asset catalog, playground, and multi-format export.
        * **Image Split**: multi-row and grid image splitting utility.
        * **Plush Studio**: interactive 3D plush cushion design playground with real-time settings.
        * **OG Image Generator**: dynamic OpenGraph preview generator and showcase dashboard.
    </ChangelogChange>

    <ChangelogChange kind="improved">
      * Overhauled site header into a modular floating island layout with separate brand, navigation, and tools capsules.
      * Enhanced mega menu geometry with circular arc fillets for seamless ear transitions.
      * Enhanced `GitHubActivity` with horizontal `ScrollArea`, edge fades, and auto-scroll on mobile while preserving the 100% full-width grid on desktop.
      * Integrated `NumberFlow` into `GitHubLink` for animated rolling star counts with compact notation.
      * Refactored squircle borders and visual consistency across Library components and marketing views.
    </ChangelogChange>

    <ChangelogChange kind="fixed">
      * Fixed initial SSR/hydration border-radius flash (FOUC) and spring physics in `BouncyAccordion`.
      * Fixed sticky positioning and scroll pinning on `DocsSidebar` and `DocsTocSidebar`, preventing sidebars from unsticking on long pages.
      * Fixed 56px top gap above documentation sidebar in standard layout mode.
      * Fixed SVG path stroke crossing artifact on mega menu inverse radius ears.
      * Fixed layout blowout and container width overflow on mobile for `GitHubActivity`.
    </ChangelogChange>

    <ChangelogChange kind="Docs">
      * Reorganized Library documentation structure under `src/content/ui-kit/`.
      * Added comprehensive MDX documentation and interactive demos for all new components, blocks, and templates.
    </ChangelogChange>
  </ChangelogItem>

  <ChangelogItem date="2026-08-31" version="0.0.11" title="Application UI Layout Design" summary="Improvements to application UI layout design, navigation structure, and documentation clarity.">
    <ChangelogChange kind="improved">
      * Refactored application layout and navigation structure.
      * Streamlined documentation content with direct AI workflow integration.
      * Polished visual consistency and squircle styling across UI kit views.
    </ChangelogChange>
  </ChangelogItem>

  <ChangelogItem date="2026-08-22" version="0.0.10" title="Initial Release" summary="Initial launch of Space UI with open-source components, primitives, sensory hooks, and shadcn registry support.">
    <ChangelogChange kind="new">
      * Initial release of Space UI component distribution.
      * Added animated primitives powered by Base UI and Motion.
      * Integrated shadcn registry support with custom style presets.
      * Added sensory hooks, sound system, squircle tokens, and AI tooling (`llms.txt`).
    </ChangelogChange>
  </ChangelogItem>
</Changelog>


# Colors
URL: https://www.spaceui.one/docs/fundamentals/colors

***

title: Colors
description: Color palette, semantic tokens, alpha translucent borders, and contrast standards.
-----------------------------------------------------------------------------------------------

## Overview

Space UI relies on high-contrast semantic color tokens paired with subtle alpha-translucent borders (`--alpha(...)`) and layered drop shadows to produce visual hierarchy and depth.

## Palette & Semantic Tokens

| Token         | Light Mode                                               | Dark Mode                                                | Usage                         |
| :------------ | :------------------------------------------------------- | :------------------------------------------------------- | :---------------------------- |
| `background`  | <ColorSwatch value="hsl(0 0% 100%)" />                   | <ColorSwatch value="hsl(0 0% 9%)" />                     | Application canvas background |
| `foreground`  | <ColorSwatch value="hsl(222 46% 11%)" />                 | <ColorSwatch value="hsl(0 0% 100%)" />                   | Default body text             |
| `card`        | <ColorSwatch value="hsl(0 0% 100%)" />                   | <ColorSwatch value="hsl(0 0% 4%)" />                     | Cards, panels, surfaces       |
| `primary`     | <ColorSwatch value="hsl(0 0% 4%)" />                     | <ColorSwatch value="hsl(0 0% 98%)" />                    | Primary buttons & highlights  |
| `secondary`   | <ColorSwatch value="hsl(240 5% 96%)" />                  | <ColorSwatch value="hsl(240 4% 16%)" />                  | Secondary actions & badges    |
| `muted`       | <ColorSwatch value="hsl(240 5% 96%)" />                  | <ColorSwatch value="hsl(240 4% 16%)" />                  | Subtle container backgrounds  |
| `destructive` | <ColorSwatch value="hsl(0 84% 60%)" />                   | <ColorSwatch value="hsl(0 84% 60%)" />                   | Errors, delete actions        |
| `info`        | <ColorSwatch value="hsl(220 96% 57%)" />                 | <ColorSwatch value="hsl(220 96% 57%)" />                 | Informational callouts        |
| `success`     | <ColorSwatch value="hsl(122 61% 42%)" />                 | <ColorSwatch value="hsl(122 61% 42%)" />                 | Completed/success states      |
| `warning`     | <ColorSwatch value="hsl(38 95% 50%)" />                  | <ColorSwatch value="hsl(38 95% 50%)" />                  | Cautionary warnings           |
| `border`      | <ColorSwatch value="--alpha(var(--color-black) / 8%)" /> | <ColorSwatch value="--alpha(var(--color-white) / 8%)" /> | Translucent borders           |

## CSS Variables Definition

```css title="app/globals.css"
:root {
  --radius: 0.625rem;
  --background: hsl(0 0% 100%);
  --foreground: hsl(222 46% 11%);
  --card: hsl(0 0% 100%);
  --card-foreground: hsl(0 0% 4%);
  --popover: hsl(0 0% 100%);
  --popover-foreground: hsl(0 0% 4%);
  --primary: hsl(0 0% 4%);
  --primary-foreground: hsl(0 0% 100%);
  --secondary: hsl(240 5% 96%);
  --secondary-foreground: hsl(240 5% 34%);
  --muted: hsl(0 0% 96%);
  --muted-foreground: hsl(0 0% 45%);
  --accent: hsl(240 5% 96%);
  --accent-foreground: hsl(0 0% 4%);
  --destructive: var(--color-red-500);
  --destructive-foreground: var(--color-red-500);
  --info: var(--color-blue-500);
  --info-foreground: var(--color-blue-500);
  --success: var(--color-emerald-500);
  --success-foreground: var(--color-emerald-500);
  --warning: var(--color-amber-500);
  --warning-foreground: var(--color-amber-500);
  --border: --alpha(var(--color-black) / 8%);
  --input: --alpha(var(--color-black) / 8%);
  --ring: transparent;
  --pill-active-bg: --alpha(var(--color-black) / 10%);
}

.dark {
  --background: hsl(0 0% 9%);
  --foreground: hsl(0 0% 100%);
  --card: hsl(0 0% 4%);
  --card-foreground: hsl(0 0% 98%);
  --popover: hsl(0 0% 4%);
  --popover-foreground: hsl(0 0% 98%);
  --primary: hsl(0 0% 98%);
  --primary-foreground: hsl(0 0% 4%);
  --secondary: hsl(240 4% 16%);
  --secondary-foreground: hsl(0 0% 98%);
  --muted: hsl(240 4% 16%);
  --muted-foreground: hsl(0 0% 64%);
  --accent: hsl(0 0% 9%);
  --accent-foreground: hsl(0 0% 98%);
  --destructive: var(--color-red-900);
  --destructive-foreground: var(--color-red-400);
  --info: var(--color-blue-500);
  --info-foreground: var(--color-blue-400);
  --success: var(--color-emerald-500);
  --success-foreground: var(--color-emerald-400);
  --warning: var(--color-amber-500);
  --warning-foreground: var(--color-amber-400);
  --border: --alpha(var(--color-white) / 8%);
  --input: --alpha(var(--color-white) / 15%);
  --ring: transparent;
  --pill-active-bg: --alpha(var(--color-white) / 14%);
}
```


# Iconography
URL: https://www.spaceui.one/docs/fundamentals/iconography

***

title: Iconography
description: Icon standards for Space UI using Tabler Icons for components and Lucide Icons for primitives.
-----------------------------------------------------------------------------------------------------------

## Overview

Space UI relies on clean, static vector iconography designed for clarity, visual balance, and performance. We adopt a dual-library approach where each icon set serves a distinct structural role:

<Cards className="sm:grid-cols-2">
  <Card title="Tabler Icons" description="Primary icon language for components, showcases, and blocks. Softened terminals and balanced stroke weights harmonize with squircle geometry." category="Components & Blocks" badge="@tabler/icons-react" dotColor="bg-blue-400" ringColor="bg-blue-300" actionLabel="Tabler Specs" href="#1-tabler-in-components--blocks" />

  <Card title="Lucide Icons" description="Dedicated to low-level primitives (Accordion, Select, Dialog, Breadcrumb) to provide lightweight, standard UI state indicators." category="Headless Primitives" badge="lucide-react" dotColor="bg-emerald-400" ringColor="bg-emerald-300" actionLabel="Lucide Specs" href="#2-lucide-in-headless-primitives" />
</Cards>

***

## Dual Iconography Comparison

Explore side-by-side examples of identical icon concepts implemented with **Tabler Icons** versus **Lucide Icons** to understand the design decisions and aesthetic differences:

| Icon Concept          | Tabler Icons (Components & Blocks)                                | Lucide Icons (Primitives)                                 | Usage Context                                 |
| :-------------------- | :---------------------------------------------------------------- | :-------------------------------------------------------- | :-------------------------------------------- |
| **Settings**          | <IconPreview library="tabler" name="IconSettings" />              | <IconPreview library="lucide" name="Settings" />          | Administration, user preferences, options     |
| **Calendar**          | <IconPreview library="tabler" name="IconCalendar" />              | <IconPreview library="lucide" name="Calendar" />          | Date pickers, event scheduling, timelines     |
| **Notifications**     | <IconPreview library="tabler" name="IconBell" />                  | <IconPreview library="lucide" name="Bell" />              | Alert center, bell counters, status tags      |
| **Search**            | <IconPreview library="tabler" name="IconSearch" />                | <IconPreview library="lucide" name="Search" />            | Command menu, search inputs, filters          |
| **User / Profile**    | <IconPreview library="tabler" name="IconUser" />                  | <IconPreview library="lucide" name="User" />              | Account dropdown, avatars, member lists       |
| **Folder**            | <IconPreview library="tabler" name="IconFolder" />                | <IconPreview library="lucide" name="Folder" />            | File tree, directory explorers, project items |
| **Mail**              | <IconPreview library="tabler" name="IconMail" />                  | <IconPreview library="lucide" name="Mail" />              | Contact forms, inbox rows, email inputs       |
| **Sparkles / AI**     | <IconPreview library="tabler" name="IconSparkle" />               | <IconPreview library="lucide" name="Sparkles" />          | AI assistants, prompt generators, highlights  |
| **Shield / Security** | <IconPreview library="tabler" name="IconShield" />                | <IconPreview library="lucide" name="Shield" />            | Security banners, permissions, auth status    |
| **Layout Grid**       | <IconPreview library="tabler" name="IconLayoutGrid" />            | <IconPreview library="lucide" name="LayoutGrid" />        | Grid views, dashboard switchers, catalogs     |
| **Sliders / Filters** | <IconPreview library="tabler" name="IconAdjustmentsHorizontal" /> | <IconPreview library="lucide" name="SlidersHorizontal" /> | Filter controls, configuration panels         |
| **Trash / Delete**    | <IconPreview library="tabler" name="IconTrash" />                 | <IconPreview library="lucide" name="Trash" />             | Destructive actions, item removal             |

***

## Installation

Install both libraries to support primitives and compound components in your application:

### Tabler Icons (Components & Blocks)

<InstallCommandBlock packages="@tabler/icons-react" />

### Lucide Icons (Primitives)

<InstallCommandBlock packages="lucide-react" />

***

## Usage Guidelines

### 1. Tabler in Components & Blocks

When building custom UI sections, feature cards, dashboards, or buttons, import icons from `@tabler/icons-react`:

```tsx
import { IconRocket, IconBrandGithub, IconArrowRight } from '@tabler/icons-react'
import { Button } from '@/components/ui/button'

export function HeroActions() {
  return (
    <div className="flex items-center gap-3">
      <Button>
        <IconRocket className="size-4" />
        <span>Get Started</span>
        <IconArrowRight className="size-4" />
      </Button>
      <Button variant="outline">
        <IconBrandGithub className="size-4" />
        <span>GitHub</span>
      </Button>
    </div>
  )
}
```

### 2. Lucide in Headless Primitives

Primitives use `lucide-react` for standard UI indicators and state controls:

```tsx
import { ChevronDown } from 'lucide-react'
import { AccordionPrimitive } from '@/components/ui/accordion'

export function AccordionTrigger({ children, ...props }: AccordionPrimitive.Trigger.Props) {
  return (
    <AccordionPrimitive.Trigger {...props}>
      {children}
      <ChevronDown className="size-4 shrink-0 transition-transform duration-200" />
    </AccordionPrimitive.Trigger>
  )
}
```

***

## Icon Sizing Standards

To maintain consistent vertical rhythm across your application, adhere to the standard Space UI icon scale:

| Context                          | Tailwind Class         | Pixel Size  | Stroke Width   |
| :------------------------------- | :--------------------- | :---------- | :------------- |
| **Badges & Micro tags**          | `size-3` or `size-3.5` | 12px – 14px | `1.5` – `1.75` |
| **Buttons & Form Controls**      | `size-4`               | 16px        | `1.75` – `2.0` |
| **Section & Card Headers**       | `size-4.5` or `size-5` | 18px – 20px | `1.5` – `2.0`  |
| **Empty States & Feature Tiles** | `size-8` or `size-10`  | 32px – 40px | `1.25` – `1.5` |

***

## Optical Alignment

When pairing icons with text inside buttons or badges:

* Always apply `shrink-0` to prevent icon distortion inside flex containers.
* Use `pointer-events-none` on decorative icons to ensure click events pass cleanly to the parent trigger.
* Keep icon colors inherited or muted with `text-muted-foreground` to preserve high visual hierarchy on the label text.


# Typography
URL: https://www.spaceui.one/docs/fundamentals/typography

***

title: Typography
description: Responsive type scale, font variables, heading hierarchy, optical line-heights, and interactive typography specs.
------------------------------------------------------------------------------------------------------------------------------

## Overview

Space UI typography is built on the principles of **restraint, precision, and responsive scalability**. Rather than arbitrary one-off font sizes, the system uses a mathematically grounded type scale with descending heading levels, optical line-heights, and dedicated tokens for body and interface controls.

The design system is powered by three primary font families:

<Cards className="sm:grid-cols-3">
  <Card title="Sans Serif" description="Default body copy, navigation menus, inputs, tables, dialogs, and general interface controls." category="Body & UI" badge="--font-sans" dotColor="bg-blue-400" ringColor="bg-blue-300" actionLabel="Body Specs" href="#body--ui-font-specs" />

  <Card title="Heading Display" description="Display hero titles, section headlines, modal titles, and prominent editorial headers." category="Display Titles" badge="--font-heading" dotColor="bg-purple-400" ringColor="bg-purple-300" actionLabel="Heading Specs" href="#heading-font-specs" />

  <Card title="Monospace" description="Dedicated to codeblocks, terminal snippets, keyboard shortcuts, and dynamic tabular numbers." category="Technical" badge="--font-mono" dotColor="bg-amber-400" ringColor="bg-amber-300" actionLabel="Type Scale" href="#type-scale-reference" />
</Cards>

***

## Text Playground

Test how headings, body paragraphs, blockquotes, lists, and interactive accordion widgets respond across different screen sizes and typeface configurations.

<TypographyPlayground />

***

## Heading Font Specs

Headings feature tight, optical line-heights (`1.10–1.35`) and proportional negative letter-spacing (tracking) to produce dense, punchy titles that balance neatly across lines.

<HeadingSpecs />

***

## Body & UI Font Specs

Body and interface typography is calibrated for maximum legibility at high reading speeds. Line-heights are relaxed (`1.40–1.60`) to provide comfortable vertical rhythm.

<BodySpecs />

***

## Type Scale Reference

A quick-reference matrix mapping typographic roles to rem/pixel sizes, line-heights, weights, tracking, and Tailwind CSS v4 utility classes:

| Role                    | Size (Desktop)   | Line Height | Weight                        | Tracking | Tailwind v4            | Description                                    |
| :---------------------- | :--------------- | :---------- | :---------------------------- | :------- | :--------------------- | :--------------------------------------------- |
| **H1 Title**            | 64px / 4.0rem    | 72px / 1.12 | SemiBold / 600                | -0.025em | `text-5xl lg:text-6xl` | Display hero headlines & major page titles     |
| **H2 Section**          | 48px / 3.0rem    | 56px / 1.16 | SemiBold / 600                | -0.020em | `text-4xl lg:text-5xl` | Main content sections & feature headings       |
| **H3 Subsection**       | 36px / 2.25rem   | 44px / 1.22 | SemiBold / 600                | -0.015em | `text-3xl`             | Subsections & card headers                     |
| **H4 Card Title**       | 28px / 1.75rem   | 36px / 1.28 | SemiBold / 600                | -0.010em | `text-2xl`             | Panel titles, dialog headers, modal titles     |
| **H5 Subhead**          | 22px / 1.375rem  | 30px / 1.36 | SemiBold / 600                | -0.005em | `text-xl`              | Feature group titles & small card headings     |
| **H6 Group Header**     | 18px / 1.125rem  | 26px / 1.44 | SemiBold / 600                | 0em      | `text-lg`              | List section titles & sub-labels               |
| **Body Large**          | 18px / 1.125rem  | 28px / 1.55 | Regular / 400 • Medium / 500  | -0.005em | `text-lg`              | Lead paragraphs & hero descriptions            |
| **Body Base**           | 16px / 1.0rem    | 24px / 1.50 | Regular / 400 • Medium / 500  | -0.005em | `text-base`            | Default documentation copy & blog paragraphs   |
| **UI Small / Controls** | 14px / 0.875rem  | 20px / 1.43 | Regular / 400 • Medium / 500  | 0em      | `text-sm`              | Buttons, form controls, table cells, dropdowns |
| **Subtext / Caption**   | 13px / 0.8125rem | 18px / 1.38 | Regular / 400 • Medium / 500  | 0em      | `text-[13px]`          | Helper texts, breadcrumbs, timestamp strings   |
| **Badge / Micro**       | 12px / 0.75rem   | 16px / 1.33 | Medium / 500 • SemiBold / 600 | +0.010em | `text-xs`              | Keyboard shortcuts, status badges, micro tags  |

***

## Typographic Principles

When styling components or long-form documentation, follow these core guidelines:

### 1. Line-Height by Role

* **Headings**: Keep line-height tight (around `1.10–1.25`) so multiline headlines read as cohesive units.
* **Body & Paragraphs**: Use generous line-height (`1.50–1.60`) so the eye easily transitions to the next line.
* **Single-line Controls**: Use `leading-none` or `leading-normal` with centered flex alignment.

### 2. Cap the Measure (Line Length)

Unbounded paragraph widths fatigue the reader. Cap long-form reading copy around **60–75 characters per line** using `max-w-[65ch]` or `max-w-2xl`.

### 3. Deliberate Text Wrapping

* Apply `text-wrap: balance` on headings and card titles to distribute line lengths evenly.
* Apply `text-wrap: pretty` on lead paragraphs and descriptions to prevent single-word orphans on the final line.

### 4. Tabular Numbers on Changing Values

Proportional digits have variable widths, causing layout jitter when counters, prices, or timers tick. Use `font-variant-numeric: tabular-nums` (Tailwind `tabular-nums`) for dynamic numeric values:

```tsx
<span className="font-mono tabular-nums text-foreground">${price.toFixed(2)}</span>
```

### 5. iOS Mobile Input 16px Rule

iOS Safari automatically zooms the viewport if a form input has a font size smaller than `16px`. Always start mobile inputs at `16px` and scale down on larger viewports:

```tsx
<input className="text-base sm:text-sm" />
```

***

## Configuration & Custom Fonts

### 1. Setup with `next/font` (Next.js)

Configure Google Fonts or local variable fonts in your root layout:

```tsx title="app/layout.tsx"
import { Inter, Geist, JetBrains_Mono } from 'next/font/google'
import '@/styles/globals.css'

const fontSans = Inter({
  subsets: ['latin'],
  variable: '--font-sans',
  display: 'swap',
})

const fontHeading = Geist({
  subsets: ['latin'],
  variable: '--font-heading',
  display: 'swap',
})

const fontMono = JetBrains_Mono({
  subsets: ['latin'],
  variable: '--font-mono',
  display: 'swap',
})

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html
      lang="en"
      className={`${fontSans.variable} ${fontHeading.variable} ${fontMono.variable}`}
      suppressHydrationWarning
    >
      <body className="font-sans antialiased bg-background text-foreground">{children}</body>
    </html>
  )
}
```

### 2. Tailwind CSS v4 Theme Integration

In Tailwind CSS v4, map your font variables inside `@theme` in `globals.css`:

```css title="app/globals.css"
@import 'tailwindcss';

@theme {
  --font-sans: var(--font-sans), system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  --font-heading: var(--font-heading), var(--font-sans), system-ui, sans-serif;
  --font-mono: var(--font-mono), ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
}

@layer base {
  body {
    font-family: var(--font-sans);
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
  }

  h1,
  h2,
  h3,
  h4,
  h5,
  h6 {
    font-family: var(--font-heading);
    text-wrap: balance;
  }
}
```


# Introduction
URL: https://www.spaceui.one/docs

***

title: Introduction
description: An open-source design library built for humans and AI to create expressive, polished, and high-quality interfaces.
-------------------------------------------------------------------------------------------------------------------------------

**Space UI is a distribution of React components** built with [Tailwind CSS](https://tailwindcss.com/), [Motion](https://motion.dev/), and [Base UI](https://base-ui.com/), based on the shadcn registry format. Our goal is to help anyone build tasteful, accessible, Motion‑powered interfaces while keeping sites ultra-fast, sensory, and maintainable.

## Not a library—an open component distribution

Like [shadcn/ui](https://ui.shadcn.com/), **Space UI is not a typical install‑from‑NPM library**. It’s an open collection you can **copy, modify, and customize** directly in your codebase. This “open code” approach gives you maximum flexibility without wrapper overhead or styling workarounds.

## What’s included

<Cards className="sm:grid-cols-2">
  <Card title="Animated Primitives" description="Core building blocks with physics and fluid animation baked in, ported and extended from Base UI." href="/ui-kit/primitives/dialog" category="Foundations" badge="Base UI" dotColor="bg-emerald-400" ringColor="bg-emerald-300" actionLabel="Explore Primitives" />

  <Card title="Components & Blocks" description="Sensory avatars, charts, counters, carousels, tickers, and ready-to-use application blocks." href="/showcase" category="Compound" badge="Interactive" dotColor="bg-blue-400" ringColor="bg-blue-300" actionLabel="View Showcase" />

  <Card title="Sensory Hooks & DX" description="Sensory UI feedback, tactile sound system, direction controllers, and squircle tokens." href="/tools" category="Experience" badge="Sensory" dotColor="bg-purple-400" ringColor="bg-purple-300" actionLabel="Try Tools" />

  <Card title="Dual Iconography" description="Clean vector icons harmonized with Tabler Icons for components and Lucide for headless primitives." href="/docs/fundamentals/iconography" category="Visuals" badge="Tabler & Lucide" dotColor="bg-amber-400" ringColor="bg-amber-300" actionLabel="Icon Standards" />
</Cards>

## Why Space UI?

1. **Open source & copy‑first**: Direct access to source so you can adapt components at their core to your design system.
2. **Sensory & Animation‑first**: Consistent, composable physics and micro-interactions that make interfaces feel alive.
3. **Performance & accessibility**: Sensible defaults, WCAG compliance, and reduced-motion safety.
4. **Base UI & Radix support**: Built on headless primitives while keeping source open and fully customizable.

## AI-Enhanced Workflow

Space UI is designed from the ground up to be **AI-friendly**, making it easier for language models to understand and modify your UI.

<Cards className="sm:grid-cols-2">
  <Card title="Global llms.txt Standard" description="Access our structured index of documentation, primitives, and architecture optimized for AI agents and RAG." href="/llms.txt" category="AI Standard" badge="llms.txt" dotColor="bg-emerald-400" ringColor="bg-emerald-300" actionLabel="Open Index" />

  <Card title="Agent Integration & Skills" description="Equip Claude Code, Cursor, Windsurf, or Antigravity with Space UI agent skills they apply on their own." href="/docs/agents" category="AI Agents" badge="Full Workflow" dotColor="bg-indigo-400" ringColor="bg-indigo-300" actionLabel="Read Guide" />
</Cards>


# Installation
URL: https://www.spaceui.one/docs/installation

***

title: Installation
description: How to install dependencies, configure registries, and add Space UI components to your project.
------------------------------------------------------------------------------------------------------------

Space UI is an open distribution of React components built on top of **React 19**, **Base UI**, **Tailwind CSS v4**, and **Motion**. It works seamlessly with the official `shadcn` CLI through custom registries.

<Callout>
  **Zero-lockin open code:** Space UI components are not a heavy NPM dependency. They install directly into your
  codebase, giving you full ownership to inspect, edit, and style every line of code.
</Callout>

## Choose Your Integration

Select your framework or development workflow to get started:

<Cards>
  <Card href="/docs/installation/nextjs" title="Next.js" category="Framework" badge="App Router" dotColor="bg-emerald-400" ringColor="bg-emerald-300" actionLabel="Setup Next.js">
    Next.js 15/16 App Router, React 19 Server Components, and Tailwind CSS v4 setup.
  </Card>

  <Card href="/docs/installation/vite" title="Vite + React" category="Bundler" badge="Client SPA" dotColor="bg-purple-400" ringColor="bg-purple-300" actionLabel="Setup Vite">
    Client-side React 19 SPA with Vite, `@tailwindcss/vite`, and TypeScript aliases.
  </Card>

  <Card href="/docs/installation/lovable" title="Lovable, Bolt & AI IDEs" category="AI Generation" badge="Prompts & Context" dotColor="bg-blue-400" ringColor="bg-blue-300" actionLabel="Configure AI">
    Prompting rules, custom registries, and `llms.txt` integration for Lovable, Bolt.new, v0, Cursor & Windsurf.
  </Card>

  <Card href="/docs/installation/manual" title="Manual Installation" category="Setup" badge="Direct CLI" dotColor="bg-orange-400" ringColor="bg-orange-300" actionLabel="Manual guide">
    Step-by-step manual setup, components.json configuration, and custom registry reference.
  </Card>

  <Card href="/docs/mcp" title="Model Context Protocol (MCP)" category="Automation" badge="IDE Protocol" dotColor="bg-blue-400" ringColor="bg-blue-300" actionLabel="Connect MCP">
    Connect Claude Code, Cursor, Windsurf, and VS Code directly to Space UI's registry.
  </Card>

  <Card href="/ui-kit/primitives" title="Explore Primitives" category="Components" badge="Base UI Primitives" dotColor="bg-emerald-400" ringColor="bg-emerald-300" actionLabel="Browse library">
    Browse all animated Base UI primitives, interactive demos, and component sources.
  </Card>
</Cards>

***

## Prerequisites & Compatibility

Ensure your project environment meets the minimum version requirements:

| Technology       | Minimum Version | Notes                                                                 |
| :--------------- | :-------------- | :-------------------------------------------------------------------- |
| **React**        | `≥ 19.0.0`      | Full support for React 19 Actions, Server Components, and Transitions |
| **Tailwind CSS** | `≥ 4.0.0`       | Built natively for CSS-first `@import "tailwindcss";` architecture    |
| **Motion**       | `≥ 12.0.0`      | Fluid physics, layout animations, and gesture interactions            |
| **Base UI**      | `≥ 1.7.0`       | Headless, accessible primitives powering menus, dialogs, and popovers |

***

## Quick Start (CLI)

If you already have a React project with Tailwind CSS configured, integrate Space UI in three simple steps:

<Steps>
  <Step>
    ### Initialize the Space UI Preset

    Run the `init` command to automatically configure your `components.json`, color variables, and squircle utility classes:

    <InstallCommandBlock
      commands={{
  pnpm: 'pnpm dlx shadcn@latest init https://www.spaceui.one/r/lib-style.json',
  npm: 'npx shadcn@latest init https://www.spaceui.one/r/lib-style.json',
  yarn: 'yarn dlx shadcn@latest init https://www.spaceui.one/r/lib-style.json',
  bun: 'bunx --bun shadcn@latest init https://www.spaceui.one/r/lib-style.json',
}}
    />
  </Step>

  <Step>
    ### Add Components

    Install any primitive or component directly from the `@spaceui` registry:

    <InstallCommandBlock isShadcn packages="@spaceui/dialog @spaceui/button" />

    <Callout type="info">
      Shared dependencies like `@base-ui/react`, `motion`, and `@spaceui/*` primitives are resolved and downloaded
      automatically by the CLI.
    </Callout>
  </Step>

  <Step>
    ### Import and Use

    Import the installed component into your layout or page:

    ```tsx title="app/page.tsx"
    import { Dialog, DialogTrigger, DialogPopup, DialogTitle, DialogDescription, DialogClose } from '@/components/ui/dialog'
    import { Button } from '@/components/ui/button'

    export default function Page() {
      return (
        <Dialog>
          <DialogTrigger render={<Button variant="primary">Open Dialog</Button>} />
          <DialogPopup>
            <DialogTitle>Welcome to Space UI</DialogTitle>
            <DialogDescription>
              State of the art animations, accessible Base UI primitives, and sensory micro-interactions.
            </DialogDescription>
            <div className="flex justify-end gap-2 mt-4">
              <DialogClose render={<Button variant="secondary">Dismiss</Button>} />
              <Button variant="primary">Confirm</Button>
            </div>
          </DialogPopup>
        </Dialog>
      )
    }
    ```
  </Step>
</Steps>

***

## Next Steps

Explore the core foundations and available component categories:

* [Explore Primitives](/ui-kit/primitives) — Base UI animated primitives (Dialog, Menu, Tooltip, Tabs, Popover).
* [Explore Components](/ui-kit/components) — High-level UI components, charts, and interactive tables.
* [Sensory Hooks & Sounds](/ui-kit/hooks) — Haptic audio feedback and interaction utilities.
* [Fundamentals & Theming](/docs/fundamentals/colors) — Color palettes, typography scales, and token systems.


# Lovable, Bolt & AI Builders
URL: https://www.spaceui.one/docs/installation/lovable

***

title: Lovable, Bolt & AI Builders
description: Build faster with Space UI in Lovable, Bolt.new, v0, Cursor, Windsurf, and Claude Code.
----------------------------------------------------------------------------------------------------

Space UI is engineered from the ground up for the AI-assisted development era. Thanks to standard **shadcn registry** formatting, strict **React 19** typing, and a dedicated **`llms.txt`** index, language models and AI IDEs understand and generate Space UI components effortlessly.

<Cards className="sm:grid-cols-3">
  <Card title="Lovable.dev" description="Connect the @spaceui registry endpoint directly in project settings to generate full-stack views." category="AI Builder" badge="Native Registry" dotColor="bg-purple-400" ringColor="bg-purple-300" actionLabel="Setup Lovable" href="#lovabledev" />

  <Card title="Bolt.new" description="Scaffold and preview Space UI components directly in browser WebContainer environments." category="WebContainer" badge="In-Browser" dotColor="bg-blue-400" ringColor="bg-blue-300" actionLabel="Setup Bolt" href="#boltnew" />

  <Card title="Cursor & Windsurf" description="Configure tailored .cursorrules to give agents deep architectural knowledge of Space UI tokens." category="AI IDEs" badge=".cursorrules" dotColor="bg-emerald-400" ringColor="bg-emerald-300" actionLabel="Setup Rules" href="#cursor--windsurf-rules-cursorrules" />
</Cards>

***

## Lovable.dev

**Lovable** natively supports custom shadcn registries. You can add the Space UI registry directly in your project settings:

<Steps>
  <Step>
    ### Configure the Registry Endpoint

    In your Lovable project, open **Settings → Registries** (or in `components.json`) and add:

    ```json title="components.json"
    {
      "registries": {
        "@spaceui": "https://www.spaceui.one/r/{name}.json"
      }
    }
    ```
  </Step>

  <Step>
    ### Prompt Lovable with Space UI Primitives

    Use specific component handles in your prompt instructions:

    ```text
    Build a modern dashboard settings view with:
    - Tabs using @spaceui/tabs
    - Modal dialog for user invitations using @spaceui/dialog
    - Button controls from @spaceui/button with squircle radius
    - Follow the design tokens and dark mode styling from Space UI
    ```
  </Step>
</Steps>

***

## Bolt.new

**Bolt.new** runs in-browser WebContainer environments. To use Space UI inside Bolt:

<Steps>
  <Step>
    ### Initialize Space UI in WebContainer Terminal

    Run the standard initialization in the Bolt terminal:

    ```bash
    npx shadcn@latest init https://www.spaceui.one/r/lib-style.json -y
    ```
  </Step>

  <Step>
    ### Add Space UI Components

    Install any required primitives directly:

    ```bash
    npx shadcn@latest add https://www.spaceui.one/r/primitives-dialog.json https://www.spaceui.one/r/primitives-button.json -y
    ```
  </Step>
</Steps>

***

## v0.dev (by Vercel)

When generating UI blocks with **v0**, pass Space UI's documentation context or ask v0 to use Base UI primitives:

```text
Generate a multi-step checkout dialog using Base UI (@base-ui/react) and Motion.
Use Space UI semantic tokens (--background, --foreground, --card, --primary).
Ensure dialogs use Base UI Portal and Backdrop with smooth scale-in animations.
```

***

## Cursor & Windsurf Rules (`.cursorrules`)

Save a `.cursorrules` (or `.windsurfrules`) file in the root of your repository to ensure your AI assistant always recommends and writes Space UI code:

```markdown title=".cursorrules"
# Space UI Project Guidelines

You are an expert React 19 & Tailwind CSS v4 developer working with Space UI.

## Core Stack

- React 19 (Server & Client Components)
- Base UI headless primitives (@base-ui/react)
- Motion for fluid physics and micro-interactions (motion)
- Tailwind CSS v4 (@import "tailwindcss")

## Component Installation

When asked to add or use new UI components:

1. Always check if the component exists in the Space UI registry (@spaceui).
2. Install via shadcn CLI:
   npx shadcn@latest add @spaceui/<component-name>
3. Import from `@/components/ui/<component-name>`

## Theming & Styling Rules

- Use semantic color tokens: `bg-background`, `text-foreground`, `border-border`, `bg-muted`, `text-muted-foreground`.
- Use squircle corner classes (`rounded-sm`, `rounded-md`, `rounded-lg`) for cards and dialogs.
- Use `relative isolate` on page wrappers to prevent portal z-index collisions.
- Reference documentation schemas from: https://www.spaceui.one/llms.txt
```

***

## Direct `llms.txt` Context

Feed our structured AI documentation directly into **Claude Projects**, **ChatGPT Custom GPTs**, or **OpenAI Assistant API**:

* **Structured Map**: [https://www.spaceui.one/llms.txt](https://www.spaceui.one/llms.txt)
* **Full Documentation**: Every page on Space UI includes a **Copy Markdown** action in the header to instantly grab the raw source for your LLM prompts.


# Manual Installation
URL: https://www.spaceui.one/docs/installation/manual

***

title: Manual Installation
description: Step-by-step manual setup, components.json configuration, and custom registry reference.
-----------------------------------------------------------------------------------------------------

This guide covers setting up Space UI manually—from configuring **`components.json`** for registry resolution to zero-CLI copy-pasting for custom stacks and monorepos.

<Callout>
  **Full Code Ownership:** Space UI components are open and unbundled. You have complete freedom to customize, tweak
  styles, and adapt them directly in your codebase.
</Callout>

<Steps>
  <Step>
    ### Install Core Dependencies

    Install Base UI, Motion, and class utility dependencies:

    <InstallCommandBlock
      commands={{
  pnpm: 'pnpm add @base-ui/react motion cn class-variance-authority lucide-react @tabler/icons-react',
  npm: 'npm install @base-ui/react motion cn class-variance-authority lucide-react @tabler/icons-react',
  yarn: 'yarn add @base-ui/react motion cn class-variance-authority lucide-react @tabler/icons-react',
  bun: 'bun add @base-ui/react motion cn class-variance-authority lucide-react @tabler/icons-react',
}}
    />
  </Step>

  <Step>
    ### Configure `components.json`

    Create or update `components.json` at the root of your project to connect the `@spaceui` registry namespace:

    ```json title="components.json"
    {
      "$schema": "https://ui.shadcn.com/schema.json",
      "style": "base-nova",
      "rsc": true,
      "tsx": true,
      "tailwind": {
        "config": "",
        "css": "app/globals.css",
        "baseColor": "neutral",
        "cssVariables": true
      },
      "aliases": {
        "components": "@/components",
        "ui": "@/components/ui",
        "blocks": "@/components/blocks",
        "lib": "@/lib",
        "utils": "@/lib/utils",
        "hooks": "@/hooks"
      },
      "registries": {
        "@spaceui": "https://www.spaceui.one/r/{name}.json"
      }
    }
    ```
  </Step>

  <Step>
    ### Add Class Merging Utility (`lib/utils.ts`)

    Create `lib/utils.ts` to provide the `cn()` helper used throughout all Space UI primitives:

    ```ts title="lib/utils.ts"
    export { cn, type ClassValue } from 'cn'
    ```
  </Step>

  <Step>
    ### Configure Theme & CSS Variables (`globals.css`)

    Add the standard design tokens to your global CSS stylesheet (`app/globals.css` or `src/index.css`):

    ```css title="globals.css"
    @import 'tailwindcss';

    @layer base {
      :root {
        --background: 0 0% 100%;
        --foreground: 240 10% 3.9%;
        --card: 0 0% 100%;
        --card-foreground: 240 10% 3.9%;
        --popover: 0 0% 100%;
        --popover-foreground: 240 10% 3.9%;
        --primary: 240 5.9% 10%;
        --primary-foreground: 0 0% 98%;
        --secondary: 240 4.8% 95.9%;
        --secondary-foreground: 240 5.9% 10%;
        --muted: 240 4.8% 95.9%;
        --muted-foreground: 240 3.8% 46.1%;
        --accent: 240 4.8% 95.9%;
        --accent-foreground: 240 5.9% 10%;
        --destructive: 0 84.2% 60.2%;
        --destructive-foreground: 0 0% 98%;
        --border: 240 5.9% 90%;
        --input: 240 5.9% 90%;
        --ring: 240 5.9% 10%;
        --radius: 0.75rem;
      }

      .dark {
        --background: 240 10% 3.9%;
        --foreground: 0 0% 98%;
        --card: 240 10% 3.9%;
        --card-foreground: 0 0% 98%;
        --popover: 240 10% 3.9%;
        --popover-foreground: 0 0% 98%;
        --primary: 0 0% 98%;
        --primary-foreground: 240 5.9% 10%;
        --secondary: 240 3.7% 15.9%;
        --secondary-foreground: 0 0% 98%;
        --muted: 240 3.7% 15.9%;
        --muted-foreground: 240 5% 64.9%;
        --accent: 240 3.7% 15.9%;
        --accent-foreground: 0 0% 98%;
        --destructive: 0 62.8% 30.6%;
        --destructive-foreground: 0 0% 98%;
        --border: 240 3.7% 15.9%;
        --input: 240 3.7% 15.9%;
        --ring: 240 4.9% 83.9%;
      }
    }
    ```
  </Step>

  <Step>
    ### Add Components

    Install via shadcn CLI or copy the primitive code directly:

    <InstallCommandBlock isShadcn packages="@spaceui/dialog @spaceui/button" />

    *(Or click the **Code** tab on any component documentation page and copy the source into your `components/ui/` directory).*
  </Step>

  <Step>
    ### Render and Verify

    Import your component and verify its behavior:

    ```tsx title="app/page.tsx"
    import { Button } from '@/components/ui/button'

    export default function Page() {
      return (
        <div className="p-6">
          <Button variant="primary" size="md">
            Space UI Active
          </Button>
        </div>
      )
    }
    ```
  </Step>
</Steps>

***

## `components.json` Schema Reference

| Property                    | Type      | Description                                                                                              |
| :-------------------------- | :-------- | :------------------------------------------------------------------------------------------------------- |
| **`style`**                 | `string`  | Style preset. Set to `"base-nova"` for Base UI and squircle token support.                               |
| **`rsc`**                   | `boolean` | Set to `true` for Next.js App Router (React Server Components). When `false`, all files are client-only. |
| **`tsx`**                   | `boolean` | Set to `true` to generate `.tsx`/`.ts` files, or `false` for `.jsx`/`.js`.                               |
| **`tailwind.css`**          | `string`  | Relative path to your global CSS stylesheet (e.g. `app/globals.css` or `src/index.css`).                 |
| **`tailwind.baseColor`**    | `string`  | Base palette color (`neutral`, `zinc`, `slate`, `gray`, `stone`).                                        |
| **`tailwind.cssVariables`** | `boolean` | Set to `true` to enable CSS variables (`--background`, `--foreground`).                                  |
| **`aliases`**               | `object`  | Mapping between logical imports and your project directory structure.                                    |
| **`registries`**            | `object`  | Remote registry namespace mapping (e.g. `"@spaceui": "https://www.spaceui.one/r/{name}.json"`).          |

***

## Multi-Registry Namespaces

With the `@spaceui` registry configured, you can install any component with:

```bash
npx shadcn@latest add @spaceui/dialog @spaceui/button
```

The CLI queries `https://www.spaceui.one/r/{name}.json`, resolves the component code and sub-dependencies, rewrites imports according to your local `aliases`, and places files into your `components/ui/` directory.

***

## Custom Path Aliases & Monorepos

For monorepo structures (e.g. Turborepo, Nx) or custom folder hierarchies, adjust the `aliases` block:

```json title="components.json"
{
  "aliases": {
    "components": "@/shared/components",
    "ui": "@/shared/components/ui",
    "blocks": "@/shared/components/blocks",
    "lib": "@/shared/lib",
    "utils": "@/shared/utils",
    "hooks": "@/shared/hooks"
  }
}
```


# Next.js
URL: https://www.spaceui.one/docs/installation/nextjs

***

title: Next.js
description: Complete step-by-step integration for Next.js 15/16 App Router, React 19, and Tailwind CSS v4.
-----------------------------------------------------------------------------------------------------------

This guide walks you through setting up Space UI in a modern **Next.js** application with the **App Router**, **React 19**, and **Tailwind CSS v4**.

<Callout>
  Space UI components are fully compatible with Next.js Server Components. Interactive primitives automatically contain
  the `'use client'` directive where necessary.
</Callout>

<Steps>
  <Step>
    ### Create a Next.js Project

    Initialize a new Next.js application with TypeScript, Tailwind CSS, and App Router:

    <InstallCommandBlock
      commands={{
  pnpm: 'pnpm create next-app@latest my-app --typescript --tailwind --eslint --app',
  npm: 'npx create-next-app@latest my-app --typescript --tailwind --eslint --app',
  yarn: 'yarn create next-app my-app --typescript --tailwind --eslint --app',
  bun: 'bun create next-app my-app --typescript --tailwind --eslint --app',
}}
    />
  </Step>

  <Step>
    ### Initialize Space UI Preset

    Run the official initialization command to configure the Space UI design tokens, Base UI dependencies, and squircle utilities:

    <InstallCommandBlock
      commands={{
  pnpm: 'pnpm dlx shadcn@latest init https://www.spaceui.one/r/lib-style.json',
  npm: 'npx shadcn@latest init https://www.spaceui.one/r/lib-style.json',
  yarn: 'yarn dlx shadcn@latest init https://www.spaceui.one/r/lib-style.json',
  bun: 'bunx --bun shadcn@latest init https://www.spaceui.one/r/lib-style.json',
}}
    />
  </Step>

  <Step>
    ### Configure `components.json`

    Ensure your `components.json` includes the `@spaceui` registry namespace alongside your project path aliases:

    ```json title="components.json"
    {
      "$schema": "https://ui.shadcn.com/schema.json",
      "style": "base-nova",
      "rsc": true,
      "tsx": true,
      "tailwind": {
        "config": "",
        "css": "app/globals.css",
        "baseColor": "neutral",
        "cssVariables": true
      },
      "aliases": {
        "components": "@/components",
        "ui": "@/components/ui",
        "blocks": "@/components/blocks",
        "lib": "@/lib",
        "utils": "@/lib/utils",
        "hooks": "@/hooks"
      },
      "registries": {
        "@spaceui": "https://www.spaceui.one/r/{name}.json"
      }
    }
    ```
  </Step>

  <Step>
    ### Configure Tailwind CSS v4 in `globals.css`

    Tailwind CSS v4 uses CSS-first configuration. Verify that `app/globals.css` imports Tailwind and defines the Space UI theme tokens:

    ```css title="app/globals.css"
    @import 'tailwindcss';

    @layer base {
      :root {
        --background: 0 0% 100%;
        --foreground: 240 10% 3.9%;
        --card: 0 0% 100%;
        --card-foreground: 240 10% 3.9%;
        --popover: 0 0% 100%;
        --popover-foreground: 240 10% 3.9%;
        --primary: 240 5.9% 10%;
        --primary-foreground: 0 0% 98%;
        --secondary: 240 4.8% 95.9%;
        --secondary-foreground: 240 5.9% 10%;
        --muted: 240 4.8% 95.9%;
        --muted-foreground: 240 3.8% 46.1%;
        --accent: 240 4.8% 95.9%;
        --accent-foreground: 240 5.9% 10%;
        --destructive: 0 84.2% 60.2%;
        --destructive-foreground: 0 0% 98%;
        --border: 240 5.9% 90%;
        --input: 240 5.9% 90%;
        --ring: 240 5.9% 10%;
        --radius: 0.75rem;
      }

      .dark {
        --background: 240 10% 3.9%;
        --foreground: 0 0% 98%;
        --card: 240 10% 3.9%;
        --card-foreground: 0 0% 98%;
        --popover: 240 10% 3.9%;
        --popover-foreground: 0 0% 98%;
        --primary: 0 0% 98%;
        --primary-foreground: 240 5.9% 10%;
        --secondary: 240 3.7% 15.9%;
        --secondary-foreground: 0 0% 98%;
        --muted: 240 3.7% 15.9%;
        --muted-foreground: 240 5% 64.9%;
        --accent: 240 3.7% 15.9%;
        --accent-foreground: 0 0% 98%;
        --destructive: 0 62.8% 30.6%;
        --destructive-foreground: 0 0% 98%;
        --border: 240 3.7% 15.9%;
        --input: 240 3.7% 15.9%;
        --ring: 240 4.9% 83.9%;
      }
    }
    ```
  </Step>

  <Step>
    ### Setup Stacking Context in `app/layout.tsx`

    Add the `relative isolate` utility class to your application wrapper. This ensures portaled elements (dialogs, tooltips, select menus) layer above sticky headers without `z-index` conflicts:

    ```tsx title="app/layout.tsx"
    import type { Metadata } from 'next'
    import { Inter } from 'next/font/google'
    import './globals.css'

    const inter = Inter({ subsets: ['latin'] })

    export const metadata: Metadata = {
      title: 'My App',
      description: 'Built with Space UI and Next.js',
    }

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en" suppressHydrationWarning>
          <body className={`${inter.className} min-h-screen bg-background text-foreground antialiased`}>
            <div className="relative isolate flex min-h-svh flex-col">{children}</div>
          </body>
        </html>
      )
    }
    ```
  </Step>

  <Step>
    ### Add Components

    Install any component from the catalog:

    <InstallCommandBlock isShadcn packages="@spaceui/dialog @spaceui/button" />
  </Step>

  <Step>
    ### Test in Your Page

    Create a test page to verify smooth animations and styling:

    ```tsx title="app/page.tsx"
    import { Dialog, DialogTrigger, DialogPopup, DialogTitle, DialogDescription, DialogClose } from '@/components/ui/dialog'
    import { Button } from '@/components/ui/button'

    export default function HomePage() {
      return (
        <main className="flex min-h-svh flex-col items-center justify-center p-6">
          <div className="flex flex-col items-center gap-4 text-center">
            <h1 className="text-3xl font-bold tracking-tight">Space UI + Next.js</h1>
            <p className="text-muted-foreground max-w-md">
              Sensory interactions, accessible Base UI primitives, and fluid Motion physics.
            </p>

            <Dialog>
              <DialogTrigger
                render={
                  <Button variant="primary" size="lg">
                    Open Interactive Dialog
                  </Button>
                }
              />
              <DialogPopup>
                <DialogTitle>Hello from Space UI</DialogTitle>
                <DialogDescription>This dialog uses Base UI portal management and fluid Motion physics.</DialogDescription>
                <div className="flex justify-end gap-2 mt-4">
                  <DialogClose render={<Button variant="secondary">Cancel</Button>} />
                  <Button variant="primary">Confirm Action</Button>
                </div>
              </DialogPopup>
            </Dialog>
          </div>
        </main>
      )
    }
    ```
  </Step>
</Steps>

***

## Tips & Best Practices

<Callout type="tip">
  **React 19 Server Components:** You can import and render Space UI primitives in Server Components without adding
  `'use client'` to your page file, because the internal primitives encapsulate client boundaries directly.
</Callout>


# Vite + React
URL: https://www.spaceui.one/docs/installation/vite

***

title: Vite + React
description: Setup Space UI in a modern Vite React SPA with Tailwind CSS v4 and TypeScript path aliases.
--------------------------------------------------------------------------------------------------------

This guide walks you through setting up Space UI in a **Vite + React 19** Single Page Application using **Tailwind CSS v4** and the official `@tailwindcss/vite` plugin.

<Callout>
  **Path Aliases:** Vite requires configuring path resolution in `vite.config.ts` and `tsconfig.json` so that the
  `@/components` aliases work seamlessly with the `shadcn` CLI.
</Callout>

<Steps>
  <Step>
    ### Create a Vite Project

    Scaffold a new Vite React application with TypeScript:

    <InstallCommandBlock
      commands={{
  pnpm: 'pnpm create vite my-app --template react-ts',
  npm: 'npm create vite@latest my-app -- --template react-ts',
  yarn: 'yarn create vite my-app --template react-ts',
  bun: 'bun create vite my-app --template react-ts',
}}
    />
  </Step>

  <Step>
    ### Install Tailwind CSS v4 & Core Dependencies

    Install `@tailwindcss/vite`, Tailwind CSS v4, Base UI, Motion, and utility libraries:

    <InstallCommandBlock
      commands={{
  pnpm: 'pnpm add -D @tailwindcss/vite tailwindcss @types/node && pnpm add @base-ui/react motion cn class-variance-authority lucide-react @tabler/icons-react',
  npm: 'npm install -D @tailwindcss/vite tailwindcss @types/node && npm install @base-ui/react motion cn class-variance-authority lucide-react @tabler/icons-react',
  yarn: 'yarn add -D @tailwindcss/vite tailwindcss @types/node && yarn add @base-ui/react motion cn class-variance-authority lucide-react @tabler/icons-react',
  bun: 'bun add -d @tailwindcss/vite tailwindcss @types/node && bun add @base-ui/react motion cn class-variance-authority lucide-react @tabler/icons-react',
}}
    />
  </Step>

  <Step>
    ### Configure Path Aliases in `vite.config.ts`

    Update `vite.config.ts` to add the `@` path alias and load the Tailwind CSS plugin:

    ```ts title="vite.config.ts"
    import path from 'path'
    import { defineConfig } from 'vite'
    import react from '@vitejs/plugin-react'
    import tailwindcss from '@tailwindcss/vite'

    export default defineConfig({
      plugins: [react(), tailwindcss()],
      resolve: {
        alias: {
          '@': path.resolve(__dirname, './src'),
        },
      },
    })
    ```
  </Step>

  <Step>
    ### Update `tsconfig.json` and `tsconfig.app.json`

    Add path mappings to `tsconfig.app.json` (or `tsconfig.json`):

    ```json title="tsconfig.app.json"
    {
      "compilerOptions": {
        "baseUrl": ".",
        "paths": {
          "@/*": ["./src/*"]
        }
      }
    }
    ```
  </Step>

  <Step>
    ### Configure `src/index.css`

    Import Tailwind CSS and declare the theme variables in `src/index.css`:

    ```css title="src/index.css"
    @import 'tailwindcss';

    @layer base {
      :root {
        --background: 0 0% 100%;
        --foreground: 240 10% 3.9%;
        --card: 0 0% 100%;
        --card-foreground: 240 10% 3.9%;
        --popover: 0 0% 100%;
        --popover-foreground: 240 10% 3.9%;
        --primary: 240 5.9% 10%;
        --primary-foreground: 0 0% 98%;
        --secondary: 240 4.8% 95.9%;
        --secondary-foreground: 240 5.9% 10%;
        --muted: 240 4.8% 95.9%;
        --muted-foreground: 240 3.8% 46.1%;
        --accent: 240 4.8% 95.9%;
        --accent-foreground: 240 5.9% 10%;
        --destructive: 0 84.2% 60.2%;
        --destructive-foreground: 0 0% 98%;
        --border: 240 5.9% 90%;
        --input: 240 5.9% 90%;
        --ring: 240 5.9% 10%;
        --radius: 0.75rem;
      }

      .dark {
        --background: 240 10% 3.9%;
        --foreground: 0 0% 98%;
        --card: 240 10% 3.9%;
        --card-foreground: 0 0% 98%;
        --popover: 240 10% 3.9%;
        --popover-foreground: 0 0% 98%;
        --primary: 0 0% 98%;
        --primary-foreground: 240 5.9% 10%;
        --secondary: 240 3.7% 15.9%;
        --secondary-foreground: 0 0% 98%;
        --muted: 240 3.7% 15.9%;
        --muted-foreground: 240 5% 64.9%;
        --accent: 240 3.7% 15.9%;
        --accent-foreground: 0 0% 98%;
        --destructive: 0 62.8% 30.6%;
        --destructive-foreground: 0 0% 98%;
        --border: 240 3.7% 15.9%;
        --input: 240 3.7% 15.9%;
        --ring: 240 4.9% 83.9%;
      }
    }
    ```
  </Step>

  <Step>
    ### Initialize Space UI Preset

    Run the preset initializer to create `components.json`:

    <InstallCommandBlock
      commands={{
  pnpm: 'pnpm dlx shadcn@latest init https://www.spaceui.one/r/lib-style.json',
  npm: 'npx shadcn@latest init https://www.spaceui.one/r/lib-style.json',
  yarn: 'yarn dlx shadcn@latest init https://www.spaceui.one/r/lib-style.json',
  bun: 'bunx --bun shadcn@latest init https://www.spaceui.one/r/lib-style.json',
}}
    />
  </Step>

  <Step>
    ### Add Components

    Install components into your Vite project:

    <InstallCommandBlock isShadcn packages="@spaceui/button @spaceui/dialog" />
  </Step>

  <Step>
    ### Test in `src/App.tsx`

    Import and test your component:

    ```tsx title="src/App.tsx"
    import { Dialog, DialogTrigger, DialogPopup, DialogTitle, DialogDescription, DialogClose } from '@/components/ui/dialog'
    import { Button } from '@/components/ui/button'

    export default function App() {
      return (
        <div className="flex min-h-screen flex-col items-center justify-center p-8 bg-background text-foreground">
          <div className="flex flex-col items-center gap-4 text-center max-w-md">
            <h1 className="text-3xl font-bold tracking-tight">Space UI + Vite</h1>
            <p className="text-muted-foreground text-sm">
              Ultra-fast development with React 19, Tailwind v4, and Motion primitives.
            </p>

            <Dialog>
              <DialogTrigger render={<Button variant="primary">Open Dialog</Button>} />
              <DialogPopup>
                <DialogTitle>Vite Integration Active</DialogTitle>
                <DialogDescription>
                  Space UI components are rendered with native physics and Base UI accessibility.
                </DialogDescription>
                <div className="flex justify-end gap-2 mt-4">
                  <DialogClose render={<Button variant="secondary">Close</Button>} />
                  <Button variant="primary">Great!</Button>
                </div>
              </DialogPopup>
            </Dialog>
          </div>
        </div>
      )
    }
    ```
  </Step>
</Steps>


# LLMs & AI Context
URL: https://www.spaceui.one/docs/llms

***

title: LLMs & AI Context
description: Access full LLM context, global documentation dumps, and per-component markdown endpoints.
-------------------------------------------------------------------------------------------------------

## Overview

Space UI is engineered to be **machine-readable and AI-friendly**. We provide dedicated endpoints that output clean, LLM-optimized markdown without HTML noise or navigation clutter.

## Endpoints

<Cards className="sm:grid-cols-3">
  <Card title="Global Index" description="A structured index of all available components, utilities, and doc pages formatted to llms.txt standard." href="/llms.txt" category="AI Standard" badge="llms.txt" dotColor="bg-emerald-400" ringColor="bg-emerald-300" actionLabel="Open llms.txt" />

  <Card title="Full Doc Corpus" description="The entire documentation corpus concatenated into a single plain-text stream, perfect for RAG and prompts." href="/llms-full.txt" category="Full Corpus" badge="llms-full.txt" dotColor="bg-blue-400" ringColor="bg-blue-300" actionLabel="Open llms-full.txt" />

  <Card title="Per-Component Stream" description="Every documentation page and primitive can be fetched directly as clean Markdown with the /llms.mdx/ prefix." href="/docs/agents" category="Live Feed" badge="/llms.mdx/*" dotColor="bg-purple-400" ringColor="bg-purple-300" actionLabel="Agent Guide" />
</Cards>

### How Per-Component Markdown Works

Every documentation page and primitive can be fetched directly as clean Markdown by prefixing the route with `/llms.mdx/`:

* Example: `https://www.spaceui.one/llms.mdx/ui-kit/primitives/dialog`
* Example: `https://www.spaceui.one/llms.mdx/ui-kit/primitives/tabs`
* Example: `https://www.spaceui.one/llms.mdx/docs/fundamentals/colors`

## Copy Markdown Feature

Every component page in the web UI includes an instant **"Copy Markdown"** button in the header, allowing you to copy the entire page's prompt-ready context into your clipboard in one click.


# Model Context Protocol (MCP)
URL: https://www.spaceui.one/docs/mcp

***

title: Model Context Protocol (MCP)
description: Connect Claude Code, Cursor, VS Code, and Windsurf to Space UI's component registry using MCP.
-----------------------------------------------------------------------------------------------------------

The **Model Context Protocol (MCP)** allows AI assistants to query the Space UI registry directly inside your editor. When enabled, your AI coding agent can search components, inspect TypeScript signatures, and install primitives without leaving the chat.

<Callout>
  Space UI leverages the official **shadcn MCP server**. Once configured, any `@spaceui` primitive can be discovered and
  installed autonomously by your AI tools.
</Callout>

***

## Automatic Configuration (Recommended)

Run the initialization command for your preferred editor to automatically write the MCP configuration file:

<SpaceCodeTabs defaultValue="claude">
  <TabsList>
    <TabsTab value="claude">Claude Code</TabsTab>
    <TabsTab value="cursor">Cursor</TabsTab>
    <TabsTab value="vscode">VS Code</TabsTab>
  </TabsList>

  <TabsPanel value="claude">
    <InstallCommandBlock
      commands={{
      pnpm: 'pnpm dlx shadcn@latest mcp init --client claude',
      npm: 'npx shadcn@latest mcp init --client claude',
      yarn: 'yarn shadcn@latest mcp init --client claude',
      bun: 'bunx --bun shadcn@latest mcp init --client claude',
    }}
    />
  </TabsPanel>

  <TabsPanel value="cursor">
    <InstallCommandBlock
      commands={{
      pnpm: 'pnpm dlx shadcn@latest mcp init --client cursor',
      npm: 'npx shadcn@latest mcp init --client cursor',
      yarn: 'yarn shadcn@latest mcp init --client cursor',
      bun: 'bunx --bun shadcn@latest mcp init --client cursor',
    }}
    />
  </TabsPanel>

  <TabsPanel value="vscode">
    <InstallCommandBlock
      commands={{
      pnpm: 'pnpm dlx shadcn@latest mcp init --client vscode',
      npm: 'npx shadcn@latest mcp init --client vscode',
      yarn: 'yarn shadcn@latest mcp init --client vscode',
      bun: 'bunx --bun shadcn@latest mcp init --client vscode',
    }}
    />
  </TabsPanel>
</SpaceCodeTabs>

***

## Manual Configuration

If you prefer adding the MCP server manually, save the corresponding JSON snippet in your project or global configuration directory:

<SpaceCodeTabs defaultValue="claude">
  <TabsList>
    <TabsTab value="claude">Claude Code</TabsTab>
    <TabsTab value="cursor">Cursor</TabsTab>
    <TabsTab value="vscode">VS Code</TabsTab>
    <TabsTab value="windsurf">Windsurf</TabsTab>
  </TabsList>

  <TabsPanel value="claude">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "shadcn": {
          "command": "npx",
          "args": ["shadcn@latest", "mcp"]
        }
      }
    }
    ```
  </TabsPanel>

  <TabsPanel value="cursor">
    ```json title=".cursor/mcp.json"
    {
      "mcpServers": {
        "shadcn": {
          "command": "npx",
          "args": ["shadcn@latest", "mcp"]
        }
      }
    }
    ```
  </TabsPanel>

  <TabsPanel value="vscode">
    ```json title=".vscode/mcp.json"
    {
      "mcpServers": {
        "shadcn": {
          "command": "npx",
          "args": ["shadcn@latest", "mcp"]
        }
      }
    }
    ```
  </TabsPanel>

  <TabsPanel value="windsurf">
    ```json title=".codeium/windsurf/mcp_config.json"
    {
      "mcpServers": {
        "shadcn": {
          "command": "npx",
          "args": ["shadcn@latest", "mcp"]
        }
      }
    }
    ```
  </TabsPanel>
</SpaceCodeTabs>

***

## Available MCP Capabilities

When the MCP server is active, your AI agent has access to these capabilities:

<Cards className="sm:grid-cols-3">
  <Card title="search_components" description="Finds matching primitives, interactive blocks, and sensory hooks directly inside your prompt." category="Discovery" badge="Instant Search" dotColor="bg-blue-400" ringColor="bg-blue-300" actionLabel="Agent Guide" href="/docs/agents" />

  <Card title="get_component" description="Inspects TypeScript props, imports, sub-components, and design tokens without context pollution." category="Inspection" badge="Props & API" dotColor="bg-purple-400" ringColor="bg-purple-300" actionLabel="Agent Guide" href="/docs/agents" />

  <Card title="add_component" description="Directly executes shadcn CLI commands to scaffold and customize primitives in your workspace." category="Installation" badge="Auto Install" dotColor="bg-emerald-400" ringColor="bg-emerald-300" actionLabel="Agent Guide" href="/docs/agents" />
</Cards>

***

## Example Prompts with MCP

Try prompting your AI assistant with natural language instructions:

```text
1. Search Space UI for animated tab primitives and install @spaceui/tabs.
2. Build a project settings view with 3 tabs: General, Members, and Billing.
3. Add a delete confirmation dialog using @spaceui/dialog with destructive styling.
```


# Registry
URL: https://www.spaceui.one/docs/registry

***

title: Registry
description: Learn how to use the Space UI Registry with shadcn/ui.
-------------------------------------------------------------------

The catalog uses the `@spaceui` namespace. The shadcn CLI resolves the full alias suffix into the registry URL, so you can install everything from one namespace.

## Setup Space UI Registry

Add the Space UI registry namespace to your `components.json`. Learn more about registry config from [shadcn registry docs](https://ui.shadcn.com/docs/registry).

```json
{
  "registries": {
    "@spaceui": "https://www.spaceui.one/r/{name}.json"
  }
}
```

## Installing Components

Component examples use the `c-*` naming pattern and install with no license key or account:

```bash
npx shadcn@latest add @spaceui/components-spaceui-c-alert-1
```

Some `c-*` items pull shared `@spaceui/*` primitives as registry dependencies. Those supporting files are resolved automatically, so installs keep working out of the box.


# Roadmap
URL: https://www.spaceui.one/docs/roadmap

***

title: Roadmap
description: Roadmap for Space UI.
----------------------------------

import { Roadmap, RoadmapGroup, RoadmapItem } from '@/components/docs/mdx/roadmap'

This roadmap provides a high-level overview of our current objectives and what's coming next for Space UI.

<Roadmap>
  <RoadmapGroup title="Key Objectives">
    <RoadmapItem title="Space UI Proprietary Components & Shaders" status="done" />

    <RoadmapItem title="Production Blocks & Templates Collection" status="done" />

    <RoadmapItem title="Base UI Animated Primitives Coverage" status="done" />

    <RoadmapItem title="Interactive Design Tools Suite" status="in-progress" />

    <RoadmapItem title="Animated Tabler & Sensory Icons" status="in-progress" />

    <RoadmapItem title="Vercel OSS Program" status="planned" />

    <RoadmapItem title="Space UI CLI & Registry Distribution" status="planned" />
  </RoadmapGroup>

  <RoadmapGroup title="Components & Shaders (Space UI)">
    <RoadmapItem title="Liquid Metal & Silk Borders" status="done" />

    <RoadmapItem title="Procedural WGSL Shaders (HeatShade, SilkGradient)" status="done" />

    <RoadmapItem title="Fluid Physics Controls (LiquidSwitch, SloshSlider, SlideToConfirm)" status="done" />

    <RoadmapItem title="Kinetic Text & Search (MorphingText, BlurRevealText, SearchPill)" status="done" />

    <RoadmapItem title="Adaptive Density Grid & Chroma Palette" status="done" />

    <RoadmapItem title="Magnetic Cursor & Hover Physics" status="in-progress" />

    <RoadmapItem title="Dropzone with File Spring Physics" status="in-progress" />

    <RoadmapItem title="3D Canvas & WebGL Depth Shaders" status="experimental" />

    <RoadmapItem title="Sensory Sound FX System v2" status="experimental" />

    <RoadmapItem title="Multi-touch Gesture Surface" status="to-define" />
  </RoadmapGroup>

  <RoadmapGroup title="Blocks & Sections">
    <RoadmapItem title="Community Wall Infinite Canvas" status="done" />

    <RoadmapItem title="Interactive Grid Hero with Proximity Detection" status="done" />

    <RoadmapItem title="Advanced Carousels (Lens, Dither, Liquid Gooey, Prism)" status="done" />

    <RoadmapItem title="Pricing Section with Interactive Savings Calculator" status="done" />

    <RoadmapItem title="Stats & Analytics Dashboard Cards" status="done" />

    <RoadmapItem title="Interactive Fun Facts & Feature Bento" status="in-progress" />

    <RoadmapItem title="Multi-step Onboarding & Flow Wizards" status="planned" />

    <RoadmapItem title="Floating Dock & Dynamic Island Navbars" status="planned" />

    <RoadmapItem title="AI Chat & Streaming Reasoning Block" status="experimental" />

    <RoadmapItem title="Interactive Product Tour" status="to-define" />
  </RoadmapGroup>

  <RoadmapGroup title="Templates">
    <RoadmapItem title="Space UI Library Templates Suite (20+ Templates)" status="done" />

    <RoadmapItem title="Interactive Template Playground Canvas" status="in-progress" />

    <RoadmapItem title="Next-gen AI SaaS Application Template" status="planned" />

    <RoadmapItem title="Mobile-first Web App & PWA Template" status="to-define" />
  </RoadmapGroup>

  <RoadmapGroup title="Design Tools">
    <RoadmapItem title="Flags Explorer & Vector Export" status="done" />

    <RoadmapItem title="Image Split Grid Tool" status="done" />

    <RoadmapItem title="Plush Studio 3D Playground" status="done" />

    <RoadmapItem title="Emoji Explorer (30K+ Unicode Assets)" status="done" />

    <RoadmapItem title="OG Image Generator Studio" status="in-progress" />

    <RoadmapItem title="SVG to WebGPU Shader Playground" status="experimental" />

    <RoadmapItem title="Palette Harmonizer & Contrast Studio" status="to-define" />
  </RoadmapGroup>

  <RoadmapGroup title="Ecosystem & Developer Experience">
    <RoadmapItem title="Fumadocs Library Integration & Auto-Registry" status="done" />

    <RoadmapItem title="Custom shadcn/ui Registry CLI Generator" status="planned" />

    <RoadmapItem title="Figma UI Kit & Design Token Sync" status="to-define" />
  </RoadmapGroup>
</Roadmap>


# Skills
URL: https://www.spaceui.one/docs/skills

***

title: Skills
description: Agent skills that teach your AI assistant how Space UI builds, animates and ships interfaces.
----------------------------------------------------------------------------------------------------------

Your agent can already write code. Space UI skills give it the judgement: the rules, values and hard-won lessons behind our components, written down so Claude Code, Cursor, Windsurf, Codex or Antigravity apply them on their own.

Each skill installs through the shadcn CLI into `.agents/skills/`, where agents discover it automatically. No Space UI code is required: the rules work with any stack and any design system.

***

## Available Skills

<Cards className="sm:grid-cols-2">
  <Card title="Space Motion" description="Timing, transitions, pacing and storytelling, plus frame-perfect 4K export for launch films built in code." href="#space-motion" category="Motion" badge="@spaceui/motion" dotColor="bg-blue-400" ringColor="bg-blue-300" actionLabel="View details" />
</Cards>

More skills are on the way.

***

## Space Motion

Teaches your agent how things should move: arrivals in 350ms, text that comes into focus, scenes that arrive over the last frame instead of fading out, sound only on key actions, and exports rendered frame by frame instead of screen-recorded.

```bash
npx shadcn@latest add @spaceui/motion
```

* **Timing**: exact durations, easings, distances, blur and stagger, and when each one applies.
* **Films**: scrubbable timelines, transitions, pre-mounting, driving live components, sound cues.
* **Storytelling**: beat order, copy that sells, emoji as punctuation, layout per scene.
* **Rendering**: 4K 60fps exports with zero dropped frames on a virtual clock.

It also points your agent to [`@usespaceui/emoji`](https://www.npmjs.com/package/@usespaceui/emoji), [`@usespaceui/sounds`](https://www.npmjs.com/package/@usespaceui/sounds) and these docs for components to film.

### Prompt to start

Paste this into your agent, swap the brackets, and it installs the skill before it starts:

```text
Hey! I want to make a [10-second] opener for my product [Product name]: [one line on what it does and who it's for].

First install the Space Motion skill and follow it for everything that moves:
npx shadcn@latest add https://www.spaceui.one/r/motion.json

Then:
1. Propose the beats and the copy, one line per scene, and wait for my OK before animating.
2. Build it as a scrubbable page with one clock (?t= jumps to a moment).
3. Use animated emoji from @usespaceui/emoji and sounds from @usespaceui/sounds on key actions only.
4. When I approve it, export it frame by frame in 4K 60fps, not by recording the screen.
```

### System prompt

For agents and tools that take standing instructions (Claude Projects, custom GPTs, Cursor rules, `CLAUDE.md`):

```text
You are a motion designer who ships in code. For any animation, transition, product video or opener, follow the Space Motion skill: read .agents/skills/space-motion/SKILL.md, or fetch https://www.spaceui.one/r/motion.json and read its files if it isn't installed.

- Arrivals take ~350ms with a smooth ease-out; close faster than you open; never fade a scene out, let the next one arrive over it.
- Reveal text by focus: word by word, 12px rise, 8px blur, 40ms stagger. Swap words with a blur swap, never a jump.
- One idea per scene, two lines max, no dead air past 0.4s. Copy sells a concrete benefit, no filler adjectives.
- Film the real product and drive it; don't mock it up. Fit each component to its frame.
- No borders or shadows for depth; two tones and soft continuous corners.
- Sound only on key actions. At most one animated emoji per line.
- Everything is a function of one clock, so playback, scrubbing and export match. Warm heavy scenes up before they appear.
- Agree on the beats and copy before animating. Check your work frame by frame at specific timestamps.
- Export by rendering frames on a virtual clock, never by screen recording.
```

***

## Using Skills

Skills in `.agents/skills/` are picked up automatically. Describe the job and the matching skill kicks in:

```text
Make a 45-second launch video of our landing page, then export it in 4K.
```

To call one explicitly, name it:

```text
Review the transitions of this dialog with space-motion.
```

In editors that don't discover skills on their own, point to the file:

```markdown
Follow the rules in .agents/skills/space-motion/SKILL.md for every animation in this PR.
```


# Card Info
URL: https://www.spaceui.one/blocks/card-info

***

title: Card Info
description: Responsive feature and philosophy cards with gradient icons, clean typography, and layered container aesthetics.
preview: block-card-info-1
--------------------------

## Installation

<ComponentInstallation name="block-card-info-1" />

## Examples

### Philosophy & Values

A variation tailored for core principles and philosophical tenets with balanced gradient icon accents.

<ComponentPreview name="block-card-info-2" iframe={false} />


# Community Wall
URL: https://www.spaceui.one/blocks/community-wall

***

title: Community Wall
description: An interactive 2D draggable infinite canvas community board featuring radial bloom distribution, tilt controls, card pattern styles, and real-time note pinning.
preview:
name: block-community-wall-1
contained: false
----------------

## Installation

<ComponentInstallation name="block-community-wall-1" />

## Features

* **Draggable Infinite Canvas**: Smooth 2D drag-to-pan physics with boundary clamping and recenter GPS trigger.
* **Radial Bloom Distribution**: Newly added notes automatically find empty coordinates via logarithmic spiral placement, avoiding overlapping cards.
* **Geometric Card Patterns**: Choose between 6 bespoke SVGs (waves, dots, circuit, isometric grid, rings, radial bursts) styled with subtle OKLCH accents.
* **Micro-Interactions & Audio**: Hover elevations, card tilt angles (-12° to +12°), and audio feedback powered by `@usespaceui/sounds`.
* **Responsive Layout**: Infinite canvas on desktop and seamless vertical list/masonry on mobile devices.
* **Flexible Backend**: Ready to connect to Supabase, PostgreSQL, or any REST/GraphQL backend with support for verified creator badges and guest postings.

## Structure

The block includes:

* `CommunityWall`: Main wrapper combining the canvas, floating action bar, stats counter, and submission dialog.
* `InfiniteCanvas`: Draggable 2D viewport handling panning, collision avoidance, and card rendering.
* `CommunityWallCard`: The memo note card with rotation, background patterns, and author avatar.
* `LeaveNoteDialog`: Modal form with live real-time card preview, angle slider, and pattern picker.
* `WALL_PATTERNS`: Array of 6 decorative SVGs for card backgrounds.

## Supabase Schema

If you want to persist notes to Supabase with mixed guest and authenticated postings, use the following SQL schema:

```sql
create table if not exists public.community_wall (
  id uuid primary key default gen_random_uuid(),
  user_id uuid references auth.users(id) on delete set null,
  creator_name text not null,
  creator_avatar_url text,
  message text not null check (char_length(message) <= 140),
  pattern_index int default 0,
  rotation int default 0,
  is_verified boolean default false,
  created_at timestamptz default now()
);

alter table public.community_wall enable row level security;

create policy "Anyone can read community notes"
  on public.community_wall for select
  using (true);

create policy "Anyone can insert community notes"
  on public.community_wall for insert
  with check (char_length(message) <= 140);
```


# Dither Carousel
URL: https://www.spaceui.one/blocks/dither-carousel

***

title: Dither Carousel
description: A 3D cylindrical spiral column of cards in WebGL2 with curved perspective, directional blur, and matrix dither grain.
preview:
name: block-dither-carousel
contained: false
----------------

Cards mapped onto the surface of an orbital cylinder. As cards travel away, they pass through an axial blur and dissolve into an ordered threshold dither pattern.

## Installation

<ComponentInstallation name="block-dither-carousel" />

## Usage

```tsx
import BlockDitherCarousel from '@/components/blocks/dither-carousel'

export default function Showcase() {
  return <BlockDitherCarousel />
}
```


# Eleven Labs Landing
URL: https://www.spaceui.one/blocks/eleven-labs

***

title: Eleven Labs Landing
description: ElevenLabs-inspired landing page block with a live Smooth Orb hero, product families, audio player, and voice cards.
preview: block-eleven-labs
--------------------------

## Installation

<ComponentInstallation name="block-eleven-labs" />

## Files

| File                                                         | Role                                       |
| ------------------------------------------------------------ | ------------------------------------------ |
| `components/blocks/eleven-labs/index.tsx`                    | Main landing page & hero orb carousel      |
| `components/blocks/eleven-labs/data/flags.ts`                | Language codes, flag mappings & SVG assets |
| `components/blocks/eleven-labs/data/index.ts`                | Voices, products, agents & initial data    |
| `components/blocks/eleven-labs/components/shared.tsx`        | Shared icons, buttons & layout primitives  |
| `components/blocks/eleven-labs/components/speech-select.tsx` | Accessible portal-based dropdown select    |
| `components/blocks/eleven-labs/components/code-controls.tsx` | All-in-one AI editor code controls         |
| `components/blocks/eleven-labs/sections/creative-platform/`  | ElevenCreative section & feature cards     |
| `components/blocks/eleven-labs/sections/product-tabs/`       | Product tabs (Agents, API, Creative)       |
| `components/orb/smooth`                                      | Hero orb (registry dependency)             |
| `components/shader/silk-gradient`                            | Silk gradient shader (registry dependency) |
| `public/mastermind/`                                         | Product and voice artwork                  |

The orb in the hero uses ambient audio. Point `textureUrl` at another image if you replace the creative stills.


# Blocks
URL: https://www.spaceui.one/blocks

***

title: Blocks
description: Complete UI sections and page blocks ready to drop into a product.
-------------------------------------------------------------------------------


# Interactive Fun Facts
URL: https://www.spaceui.one/blocks/interactive-fun-facts

***

title: Interactive Fun Facts
description: Interactive 3D stacked quiz game block with True/False feedback, live score counter, progression indicators, and flip-to-reveal grid.
preview: block-interactive-fun-facts
------------------------------------

## Installation

<ComponentInstallation name="block-interactive-fun-facts" />


# Interactive Grid Hero
URL: https://www.spaceui.one/blocks/interactive-grid-hero

***

title: Interactive Grid Hero
description: Interactive proximity-reactive square cell grid canvas that softly rounds and insets cells within a focused radius around the cursor.
preview: block-interactive-grid-hero-1
--------------------------------------

## Installation

<ComponentInstallation name="block-interactive-grid-hero-1" />

## Features

* **Dynamic Proximity Physics**: Cells smoothly adjust border-radius and inset within a configurable radius around the pointer.
* **Shape Controls**: Switch seamlessly between `square`, `rounded`, and `full` (circle) corner styles.
* **Responsive Layout**: Automatically calculates rows and columns to fill 100% of container width and height.


# Lens Carousel
URL: https://www.spaceui.one/blocks/lens-carousel

***

title: Lens Carousel
description: Vertical WebGL lens gallery from the Immersive Lens template. Scroll-linked planes, not a horizontal card strip.
isPro: true
preview:
name: block-lens-carousel
contained: false
----------------

## Installation

<ComponentInstallation name="block-lens-carousel" />

## Usage

```tsx
import BlockLensCarousel from '@/components/blocks/lens-carousel'

export default function Showcase() {
  return <BlockLensCarousel />
}
```


# Liquid Gooey Carousel
URL: https://www.spaceui.one/blocks/liquid-gooey-carousel

***

title: Liquid Gooey Carousel
description: A WebGL2 signed distance field carousel where cards behave like drops of liquid held on glass, fusing together and stretching organic strands.
isPro: true
preview:
name: block-liquid-gooey-carousel
contained: false
----------------

Each card is a rounded-box distance field. A fullscreen pass evaluates a smooth minimum (smin) across all cards, allowing them to fuse seamlessly like drops of liquid metal.

## Installation

<ComponentInstallation name="block-liquid-gooey-carousel" />

## Usage

```tsx
import BlockLiquidGooeyCarousel from '@/components/blocks/liquid-gooey-carousel'

export default function Showcase() {
  return <BlockLiquidGooeyCarousel />
}
```


# Prism Carousel
URL: https://www.spaceui.one/blocks/prism-carousel

***

title: Prism Carousel
description: A looping image strip viewed through a thick optical glass element with radial zoom, refraction, and chromatic RGB aberration.
isPro: true
preview:
name: block-prism-carousel
contained: false
----------------

The image strip renders to an offscreen texture, then a fullscreen WebGL pass samples it through an optical lens shader with dispersion and refraction.

## Installation

<ComponentInstallation name="block-prism-carousel" />

## Usage

```tsx
import BlockPrismCarousel from '@/components/blocks/prism-carousel'

export default function Showcase() {
  return <BlockPrismCarousel />
}
```


# Showcase Gallery
URL: https://www.spaceui.one/blocks/showcase-gallery

***

title: Showcase Gallery
description: Justified gallery of stills and looping videos. Point at a piece, tap it or tab to it and it steps forward on a spring while the rest makes room.
isPro: true
preview:
name: block-showcase-gallery
contained: false
----------------

## Installation

<ComponentInstallation name="block-showcase-gallery" />

## Usage

```tsx
import { ShowcaseGallery } from '@/components/blocks/showcase-gallery'

const rows = [
  [
    { title: 'Launch film', category: 'Motion', image: '/work/launch.webp', video: '/work/launch.mp4', aspect: 16 / 9 },
    { title: 'Watch face', category: 'Product', image: '/work/watch.webp', video: '/work/watch.mp4', aspect: 0.8 },
  ],
  [
    { title: 'Dashboard', category: 'Product', image: '/work/dashboard.webp', aspect: 16 / 9 },
    { title: 'Mobile app', category: 'Product', image: '/work/app.webp', aspect: 1 },
  ],
]

export default function Work() {
  return <ShowcaseGallery rows={rows} />
}
```

Each row is justified to the full width, with tiles sized by their `aspect` (width / height). In a narrow container the same items regroup two per row and keep their real proportions.

Focus a tile and it steps forward on a spring: it widens, its row grows taller, its neighbours give way without changing the gallery's height, the media pans slightly toward the focus point and a caption with its `title` and `category` comes into focus. Only the focused tile's video plays; with nothing focused, videos play while they're on screen.

* **Mouse**: the focus follows the pointer.
* **Touch**: tap a tile to focus it, tap it again or anywhere else to let go.
* **Keyboard**: tab through the tiles; Escape lets go.

With reduced motion the focus still works, without the animation. Videos only load their metadata once they're about to scroll into view.

Remote images go through `next/image`, so add their host to `images.remotePatterns` in `next.config`.


# Sign In Page
URL: https://www.spaceui.one/blocks/sign-in

***

title: Sign In Page
description: A complete sign in page block using our space components and primitives.
preview:
name: block-sign-in
iframe: false
-------------

## Installation

<ComponentInstallation name="block-sign-in" />


# Stats
URL: https://www.spaceui.one/blocks/stats

***

title: Stats
description: Comprehensive portfolio statistics and analytics blocks featuring KPI cards, GitHub activity heatmap, publication analytics, Lighthouse benchmarks, and reader engagement.
preview: block-stats-general
----------------------------

## Installation

<ComponentInstallation name="block-stats-general" />

## Blocks

### GitHub Activity & Heatmap

GitHub ecosystem metrics (stars, forks, commits) with floating particle shapes and an interactive 52-week contribution heatmap matrix.

<ComponentPreview name="block-stats-github" />

### Blog & Writing Analytics

Publication statistics tracking published articles, cumulative word counts, community messages, and reading time estimates.

<ComponentPreview name="block-stats-blog" />

### Lighthouse Performance Audit

Mobile and desktop performance scorecards featuring SVG concentric radar charts and animated category benchmark progress bars.

<ComponentPreview name="block-stats-performance" />

### Reader Engagement

Audience interaction dashboard featuring most-viewed articles, top community reactions, interactive emoji counters, topic distribution tags, and recent changelog milestones.

<ComponentPreview name="block-stats-engagement" />


# Velocity Hover Preview
URL: https://www.spaceui.one/blocks/velocity-hover-preview

***

title: Velocity Hover Preview
description: Interactive kinetic list and hover carousel projecting a floating WebGL preview with inertial momentum mesh-warping and pixel block entry/exit wave crossfading.
isPro: true
preview:
name: demo-c-velocity-hover-preview-01
contained: false
----------------

Interactive kinetic hover carousel. Hovering list items projects an orthographic WebGL preview that trails pointer velocity with inertia, vertex momentum distortion, and pixel wave entrance and exit dissolves.

## Installation

<ComponentInstallation name="components-spaceui-velocity-hover-preview" />

## Usage

```tsx
import { VelocityHoverPreview } from '@/components/spaceui/velocity-hover-preview'

const sampleServices = [
  {
    id: '01',
    num: '01',
    title: 'Space UI Twilight Ring',
    subtitle: 'Luminous Coastal Horizon & Twilight Shaders',
    mediaUrl: 'https://cdn.spaceui.one/atom/samples/image-1.png',
  },
  {
    id: '02',
    num: '02',
    title: 'Flora Kinetic Portrait',
    subtitle: 'Botanical Florals & Reactive Micro-interactions',
    mediaUrl: 'https://cdn.spaceui.one/atom/samples/image-2.png',
  },
]

export default function Example() {
  return <VelocityHoverPreview items={sampleServices} accentColor="#ffe9a8" />
}
```

## Props

| Prop            | Type                          | Default     | Description                                                     |
| --------------- | ----------------------------- | ----------- | --------------------------------------------------------------- |
| `items`         | `PreviewItem[]`               | `[]`        | Array of items with title, subtitle, mediaUrl, and num.         |
| `accentColor`   | `string`                      | `'#ffe9a8'` | Accent color of pixel wave transition bands (Aurum by default). |
| `gridDensity`   | `number`                      | `32`        | Density of matrix blocks in transition waves.                   |
| `warpIntensity` | `number`                      | `0.45`      | Inertial momentum mesh distortion scale.                        |
| `onItemSelect`  | `(item: PreviewItem) => void` | —           | Callback when a list item is clicked.                           |


# Adaptive Density Grid
URL: https://www.spaceui.one/components/adaptive-density-grid

***

title: Adaptive Density Grid
description: A fluid polymorphic grid featuring velocity-driven spring pill tabs, staggered layout reflow animations, and built-in memory optimization.
preview:
name: demo-c-adaptive-density-grid-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-adaptive-density-grid" />

## Usage

```tsx
import { AdaptiveDensityGrid } from '@/components/spaceui/adaptive-density-grid'
```

```tsx
<AdaptiveDensityGrid
  items={items}
  options={[
    { id: 'spacious', label: 'Spacious', columns: { desktop: 2, tablet: 2, mobile: 1 } },
    { id: 'normal', label: 'Normal', columns: { desktop: 3, tablet: 2, mobile: 1 } },
    { id: 'compact', label: 'Compact', columns: { desktop: 4, tablet: 3, mobile: 2 } },
  ]}
  renderItem={(item) => <div className="rounded-xl border p-4 bg-muted">{item.title}</div>}
/>
```

## API Reference

### AdaptiveDensityGrid Props

| Prop              | Type                                                                       | Default           | Description                                                        |
| ----------------- | -------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------ |
| `items`           | `T[]`                                                                      | `undefined`       | Array of data items to render                                      |
| `renderItem`      | `(item: T, index: number, state: { isRearranging: boolean }) => ReactNode` | `undefined`       | Custom item render function                                        |
| `children`        | `ReactNode`                                                                | `undefined`       | Direct children components (alternative to `items`)                |
| `options`         | `DensityOption[]`                                                          | `DEFAULT_OPTIONS` | Array of layout density or category filter options                 |
| `activeId`        | `string \| number`                                                         | `undefined`       | Controlled active option id                                        |
| `defaultActiveId` | `string \| number`                                                         | `options[0]?.id`  | Default active option id                                           |
| `onOptionChange`  | `(id: string \| number) => void`                                           | `undefined`       | Callback fired when option selection changes                       |
| `showControls`    | `boolean`                                                                  | `true`            | Show or hide the top selector bar                                  |
| `controlsExtra`   | `ReactNode`                                                                | `undefined`       | Extra elements rendered alongside the controls (e.g. search input) |
| `staggerDelay`    | `number`                                                                   | `0.012`           | Stagger delay in seconds between tile animations                   |
| `duration`        | `number`                                                                   | `0.55`            | Layout reflow transition duration in seconds                       |
| `memoryOptimized` | `boolean`                                                                  | `true`            | Enables `content-visibility: auto` to prevent memory saturation    |

***

### Category Filter & Cards Reflow

Use the adaptive density grid as an animated tab reflow system with search integration and interactive cards.

<ComponentPreview name="demo-c-adaptive-density-grid-02" contained={false} />


# Textmoji Animated
URL: https://www.spaceui.one/components/animoji

***

title: Textmoji Animated
description: Renders every Unicode emoji in a string as an animated image sized to the surrounding text.
preview:
name: demo-c-animoji-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-animoji" />

## Usage

```tsx
import { Animoji } from '@/components/spaceui/animoji'

export default function Example() {
  return (
    <p>
      <Animoji source="telegram">Ship your ideas faster 🚀</Animoji>
    </p>
  )
}
```

For static emoji, use [Textmoji](/components/textmoji) instead — same API, different provider list.

## Examples

### Sources

<ComponentPreview name="demo-c-animoji-02" contained={false} />

### Unicode escapes & flags

<ComponentPreview name="demo-c-animoji-03" contained={false} />

### With Blur Reveal Text

<ComponentPreview name="demo-c-animoji-04" contained={false} />

## Props

| Prop             | Type                               | Default    | Description                                               |
| ---------------- | ---------------------------------- | ---------- | --------------------------------------------------------- |
| `children`       | `string`                           | —          | The text to scan                                          |
| `source`         | `'fluent' \| 'telegram' \| 'noto'` | `'fluent'` | Provider to render — only the ones with an animated style |
| `className`      | `string`                           | —          | Class on the outer wrapper                                |
| `emojiClassName` | `string`                           | —          | Class applied to each rendered emoji image                |


# Aurora Glow Button
URL: https://www.spaceui.one/components/aurora-glow-button

***

title: Aurora Glow Button
description: A button with a hover-reactive radial aurora gradient, an animated conic-gradient border, and a rotating shine sweep.
preview:
name: demo-c-aurora-glow-button-01
----------------------------------

## Installation

<ComponentInstallation name="components-spaceui-aurora-glow-button" />


# Autoscale Input
URL: https://www.spaceui.one/components/autoscale-input

***

title: Autoscale Input
description: Input that binary-searches a font size so the value always fills the available width, with locale number formats.
preview: demo-c-autoscale-input-01
----------------------------------

## Installation

<ComponentInstallation name="components-spaceui-autoscale-input" />

## Usage

```tsx
import { AutoscaleInput } from '@/components/spaceui/autoscale-input'

export default function SpaceUI() {
  return <AutoscaleInput defaultValue="1234567.89" prefix="$" numberFormat="us" aria-label="Amount" />
}
```

## Files

| File                        | Role                                             |
| --------------------------- | ------------------------------------------------ |
| `autoscale-input/index.tsx` | Format helpers, `useAutoscale`, `AutoscaleInput` |

## API Reference

| Prop                 | Type                                                            | Default | Description                             |
| -------------------- | --------------------------------------------------------------- | ------- | --------------------------------------- |
| `numberFormat`       | `'us' \| 'eu' \| 'space' \| 'ch' \| 'in' \| 'none' \| 'string'` | `'us'`  | Grouping / decimal style                |
| `prefix`             | `string`                                                        | `'$'`   | Leading glyph, scales with the value    |
| `suffix`             | `string`                                                        | `''`    | Trailing glyph                          |
| `minSize`            | `number`                                                        | `18`    | Minimum font size in px                 |
| `maxSize`            | `number`                                                        | `100`   | Maximum font size in px                 |
| `containerClassName` | `string`                                                        | —       | Outer width wrapper                     |
| `wrapperClassName`   | `string`                                                        | —       | Flex row around prefix / input / suffix |

All native `<input>` props are forwarded. Mobile text stays `text-base`.


# Avatar Extended
URL: https://www.spaceui.one/components/avatar-extended

***

title: Avatar Extended
description: Extended Avatar components with rings, status badges, indicators, icons, and a built-in procedural fallback powered by the SpaceUI Avatars API.
preview: demo-p-avatar-05
-------------------------

## Installation

<ComponentInstallation name="components-spaceui-avatar-extended" />

## Anatomy

```tsx
import { Avatar, AvatarImage } from '@/components/ui/avatar'
import {
  AvatarExtended,
  AvatarFallback,
  AvatarRing,
  AvatarBadge,
  AvatarIndicator,
  AvatarIcon,
} from '@/components/spaceui/avatar-extended'

export default () => (
  <AvatarExtended>
    <Avatar>
      <AvatarImage />
      <AvatarFallback>U</AvatarFallback>
    </Avatar>

    <AvatarRing className="ring-primary" />
    <AvatarIndicator className="bg-emerald-500" />
    <AvatarBadge>+6</AvatarBadge>
    <AvatarIcon>
      <IconCheck className="size-3" />
    </AvatarIcon>
  </AvatarExtended>
)
```

## Features

### Verified Icon & Company Logo

Use the `AvatarIcon` component to display small status indicators, verified badges, or company logos at the corner of the avatar.

<ComponentPreview name="demo-p-avatar-06" />

### Avatar Rings

Apply custom selection states or decorative borders using the `AvatarRing` component with standard utility classes.

<ComponentPreview name="demo-p-avatar-03" />

### AvatarFallback

Generates a procedural avatar image from a name via the [SpaceUI Avatars API](https://avatars.spaceui.one). It replaces the primitive `<AvatarFallback>` with a rich, generated image instead of initials.

<ComponentPreview name="demo-p-avatar-10" />

#### AvatarFallback Variants

Pass a `variant` prop to choose a specific style family. Defaults to `'all'` which lets the API pick a random style.

<ComponentPreview name="demo-p-avatar-11" />

### Avatar Badges (Counts)

Display unread notifications or counters cleanly over the avatar using the `AvatarBadge` component.

<ComponentPreview name="demo-p-avatar-08" />

## API Reference

### AvatarFallback

Generates a procedural avatar image from the SpaceUI Avatars API. Extends `React.ImgHTMLAttributes<HTMLImageElement>`.

| Prop      | Type            | Default | Description                                                             |
| :-------- | :-------------- | :------ | :---------------------------------------------------------------------- |
| `name`    | `string`        | -       | The name used to seed the avatar. Falls back to `children` if a string. |
| `variant` | `AvatarVariant` | `'all'` | The visual style family. `'all'` picks a random variant.                |

**`AvatarVariant`** values:

| Family      | Variants                                                               |
| :---------- | :--------------------------------------------------------------------- |
| Gradient    | `lumina` `shaula` `singularity` `triton` `solar-flare` `titan` `glass` |
| Fluid       | `splash` `astronaut` `ghost` `bot` `glitch` `animals`                  |
| Classic     | `pebble` `invader` `grunge` `bored` `doodle` `squiggle`                |
| Paletteless | `critter` `kendo`                                                      |
| All         | `all` (random — default)                                               |

***

### AvatarExtended

The root wrapper component that establishes the relative positioning context. Extends `React.HTMLAttributes<HTMLDivElement>`.

| Prop       | Type        | Default | Description                                                   |
| :--------- | :---------- | :------ | :------------------------------------------------------------ |
| `children` | `ReactNode` | -       | Must contain an `Avatar` and any of the extension components. |

***

### AvatarRing

An absolute overlay that applies a decorative ring or focus outline around the avatar. Extends `React.HTMLAttributes<HTMLSpanElement>`.

*No specific props. Use `className` to pass Tailwind ring utility classes (e.g. `ring-primary ring-offset-2`).*

***

### AvatarIndicator

A small status dot positioned at the bottom right by default, used for online/offline states. Extends `React.HTMLAttributes<HTMLSpanElement>`.

*No specific props. Use `className` to set the color (e.g. `bg-emerald-500`).*

***

### AvatarBadge

A notification counter or badge positioned at the top right. It wraps the standard `Badge` primitive. Extends `BadgeProps`.

| Prop      | Type                                                                                                    | Default     | Description                                         |
| :-------- | :------------------------------------------------------------------------------------------------------ | :---------- | :-------------------------------------------------- |
| `variant` | `"default" \| "destructive" \| "error" \| "info" \| "outline" \| "secondary" \| "success" \| "warning"` | `"default"` | The visual variant of the badge.                    |
| `size`    | `"default" \| "sm" \| "lg"`                                                                             | `"sm"`      | The size of the badge.                              |
| `square`  | `boolean`                                                                                               | `true`      | Forces a square ratio for numbers. Fixed to `true`. |

***

### AvatarIcon

A wrapper used to absolutely position small icons, logos, or verified checkmarks at the bottom right. Extends `React.HTMLAttributes<HTMLDivElement>`.

| Prop       | Type        | Default | Description                          |
| :--------- | :---------- | :------ | :----------------------------------- |
| `children` | `ReactNode` | -       | The icon or logo element to display. |


# Avatar Group
URL: https://www.spaceui.one/components/avatar-group

***

title: Avatar Group
description: A component for rendering a group of avatars, supporting different stacking directions and action buttons.
preview: demo-p-avatar-07
-------------------------

## Installation

<ComponentInstallation name="components-spaceui-avatar-group" />

## Usage

```tsx
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar'
import { AvatarGroup, AvatarGroupAction } from '@/components/spaceui/avatar-group'
```

```tsx
<AvatarGroup stacking="left">
  <Avatar>
    <AvatarImage />
    <AvatarFallback>U1</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage />
    <AvatarFallback>U2</AvatarFallback>
  </Avatar>
  <AvatarGroupAction>+4</AvatarGroupAction>
</AvatarGroup>
```

## Features

### With Actions

Use the `AvatarGroupAction` component to add an interactive trailing element. It can contain text indicating remaining users or an icon for interaction (e.g., a plus button to add members).

<ComponentPreview name="demo-p-avatar-09" />

## API Reference

### AvatarGroup Props

| Prop       | Type                | Default   | Description                                        |
| ---------- | ------------------- | --------- | -------------------------------------------------- |
| `stacking` | `"left" \| "right"` | `"right"` | Controls the visual z-index overlap of the avatars |


# Badge Squircle
URL: https://www.spaceui.one/components/badge-squircle

***

title: Badge Squircle
description: Tactile squircle badge components featuring dynamic curvature morphing on hover with polymorphic Base UI render support.
preview:
name: demo-c-badge-squircle-01
------------------------------

## Installation

<ComponentInstallation name="components-spaceui-badge-squircle" />

## Anatomy

```tsx
import { Badge } from '@/components/spaceui/badge-squircle'

export default function Example() {
  return (
    <Badge variant="default">
      <span>Badge label</span>
    </Badge>
  )
}
```

## Features

### Sizes

<ComponentPreview name="demo-c-badge-squircle-02" />

### Icons & Polymorphic Links

<ComponentPreview name="demo-c-badge-squircle-03" />

## Props

### BadgeSquircle

| Prop       | Type                                                                                            | Default     | Description                                                          |
| ---------- | ----------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------- |
| `variant`  | `'default' \| 'primary' \| 'secondary' \| 'outline' \| 'destructive' \| 'inverted' \| 'accent'` | `'default'` | Visual styling variant                                               |
| `size`     | `'xs' \| 'sm' \| 'default' \| 'md' \| 'lg'`                                                     | `'default'` | Dimensions and font scaling scale                                    |
| `squircle` | `boolean`                                                                                       | `true`      | Enables continuous curvature corner squircle mask                    |
| `circle`   | `boolean`                                                                                       | `false`     | Aspect ratio square modifier                                         |
| `render`   | `React.ReactElement \| ((props: any) => React.ReactNode)`                                       | -           | Polymorphic Base UI render element (e.g. Next.js Link or `<button>`) |


# Bloop Orb
URL: https://www.spaceui.one/components/bloop

***

title: Bloop Orb
description: Compact assistant orb with listen, think, and speak states, voice palettes, and audio input.
preview: demo-c-orb-bloop-01
----------------------------

## Installation

<ComponentInstallation name="components-orb-bloop" />

## Usage

```tsx
import { OrbBloop } from '@/components/orb/bloop'
import { BLOOP_PALETTES } from '@/components/orb/bloop-palettes'

export default function SpaceUI() {
  const palette = BLOOP_PALETTES.BLUE

  return (
    <OrbBloop
      size={220}
      audioMode="ambient"
      state="speak"
      bloopColorMain={palette.main}
      bloopColorLow={palette.low}
      bloopColorMid={palette.mid}
      bloopColorHigh={palette.high}
    />
  )
}
```

## Files

| File                           | Role                                                 |
| ------------------------------ | ---------------------------------------------------- |
| `bloop/index.tsx`              | WebGL2 bloop shader, state springs, audio hook       |
| `bloop/palettes.ts`            | `BLOOP_PALETTES` (Cove, Sky, Juniper, Ember, Breeze) |
| `orb/smooth/audio-analyzer.ts` | Shared analyser (registry dependency)                |

## API Reference

### OrbBloop

| Prop                 | Type                                       | Default     | Description                               |
| -------------------- | ------------------------------------------ | ----------- | ----------------------------------------- |
| `size`               | `number`                                   | `144`       | CSS pixel size of the canvas              |
| `audioMode`          | `'ambient' \| 'mic' \| 'file'`             | `'ambient'` | Audio driver                              |
| `audioElement`       | `RefObject<HTMLAudioElement>`              | —           | File mode source                          |
| `state`              | `'idle' \| 'listen' \| 'think' \| 'speak'` | `'idle'`    | Active pose                               |
| `bloopColorMain`     | `[number, number, number]`                 | blue        | Main fill, 0–1 RGB                        |
| `bloopColorLow`      | `[number, number, number]`                 | —           | Low band                                  |
| `bloopColorMid`      | `[number, number, number]`                 | —           | Mid band                                  |
| `bloopColorHigh`     | `[number, number, number]`                 | —           | High band                                 |
| `watercolorStrength` | `number`                                   | `0.5`       | Watercolor warp amount (min = 0, max = 1) |
| `watercolorAnimated` | `boolean`                                  | `false`     | Drift the watercolor field                |

Drive states from your assistant FSM. The demo buttons set one state at a time.


# Blur Reveal Text
URL: https://www.spaceui.one/components/blur-reveal-text

***

title: Blur Reveal Text
description: A progressive word, character, or line-by-line blur reveal animation with customizable motion vectors and viewport triggers.
preview:
name: demo-c-blur-reveal-text-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-blur-reveal-text" />

## Usage

```tsx
import { BlurRevealText } from '@/components/spaceui/blur-reveal-text'

export default function HeroStatement() {
  return (
    <BlurRevealText
      text="Great design is not just what looks good. It is how every detail feels alive."
      splitBy="words"
      stagger={0.05}
      blurAmount="12px"
      direction="up"
      className="text-3xl font-semibold tracking-tight"
    />
  )
}
```

## Props

| Prop            | Type                                 | Default      | Description                                                                      |
| --------------- | ------------------------------------ | ------------ | -------------------------------------------------------------------------------- |
| `text`          | `string`                             | **required** | The sentence or paragraph to animate.                                            |
| `splitBy`       | `'words' \| 'characters' \| 'lines'` | `'words'`    | Splitting strategy for the animation tokens.                                     |
| `stagger`       | `number`                             | `0.05`       | Delay in seconds between consecutive tokens.                                     |
| `delay`         | `number`                             | `0.1`        | Initial delay in seconds before animation begins.                                |
| `blurAmount`    | `string`                             | `'12px'`     | Starting CSS blur radius for obscured tokens.                                    |
| `duration`      | `number`                             | `0.35`       | Duration of the transition for each individual token.                            |
| `direction`     | `'up' \| 'down' \| 'none'`           | `'up'`       | Direction along the vertical axis from which tokens slide.                       |
| `yOffset`       | `number`                             | `8`          | Travel distance in pixels for the slide transition.                              |
| `inView`        | `boolean`                            | `true`       | When true, animation triggers only once the element scrolls into view.           |
| `once`          | `boolean`                            | `true`       | Whether viewport triggering fires only on first view.                            |
| `replayKey`     | `string \| number`                   | `undefined`  | Change this value to programmatically re-trigger the animation.                  |
| `renderSegment` | `(segment: string) => ReactNode`     | `undefined`  | Overrides how each segment renders — e.g. through Textmoji so emoji stay styled. |


# Bouncy Accordion
URL: https://www.spaceui.one/components/bouncy-accordion

***

title: Bouncy Accordion
description: Spring accordion that splits rounded rows when a panel opens.
preview:
name: demo-c-bouncy-accordion-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-bouncy-accordion" />

## Usage

```tsx
import { BouncyAccordion } from '@/components/spaceui/bouncy-accordion'

export default function SpaceUI() {
  return (
    <BouncyAccordion
      items={[
        { title: 'Families', description: 'Pick a variant.' },
        { title: 'Capabilities', description: 'Inspect supported effects.' },
      ]}
    />
  )
}
```

## API Reference

### BouncyAccordion

| Prop            | Type                      | Default | Description            |
| --------------- | ------------------------- | ------- | ---------------------- |
| `items`         | `BouncyAccordionItem[]`   | —       | Rows to render         |
| `defaultValue`  | `number \| null`          | `0`     | Initially open index   |
| `value`         | `number \| null`          | —       | Controlled open index  |
| `onValueChange` | `(index: number \| null)` | —       | Fired when a row opens |
| `className`     | `string`                  | —       | Root class             |

### BouncyAccordionItem

| Prop          | Type        | Default | Description      |
| ------------- | ----------- | ------- | ---------------- |
| `icon`        | `ReactNode` | —       | Optional leading |
| `title`       | `string`    | —       | Trigger label    |
| `description` | `ReactNode` | —       | Open panel body  |


# Bubble Background
URL: https://www.spaceui.one/components/bubble

***

title: Bubble Background
description: Renders floating animated bubbles across the background that smoothly move and drift away when users move their mouse.
preview: demo-c-backgrounds-bubble-01
-------------------------------------

## Installation

<ComponentInstallation name="components-backgrounds-bubble" />

## Usage

```tsx
<BubbleBackground />
```

## API Reference

### BubbleBackground

<TypeTable
  type={{
  interactive: {
    description: 'Whether the background is interactive with mouse movement.',
    type: 'boolean',
    required: false,
    default: 'false',
  },
  transition: {
    description: 'The transition of the background.',
    type: 'SpringOptions',
    required: false,
    default: '{ stiffness: 100, damping: 20 }',
  },
  colors: {
    description: 'The colors of the background.',
    type: 'BubbleColors',
    required: false,
    default:
      '{ first: "18,113,255", second: "221,74,255", third: "0,220,255", fourth: "200,50,50", fifth: "180,180,50", sixth: "140,100,255" }',
  },
  '...props': {
    description: 'The props of the BubbleBackground.',
    type: 'React.ComponentProps<"div">',
    required: false,
  },
}}
/>

## Credits

* Credits to [GlitchWorker](https://codepen.io/glitchworker/pen/jENZGOV) for the inspiration


# Button Squircle
URL: https://www.spaceui.one/components/button-squircle

***

title: Button Squircle
description: Tactile squircle button components featuring dynamic curvature morphing on hover with polymorphic Base UI render support.
preview:
name: demo-c-button-squircle-01
-------------------------------

## Installation

<ComponentInstallation name="components-spaceui-button-squircle" />

## Anatomy

```tsx
import { Button } from '@/components/spaceui/button-squircle'

export default function Example() {
  return (
    <Button variant="primary">
      <span>Click me</span>
    </Button>
  )
}
```

## Features

### Sizes

<ComponentPreview name="demo-c-button-squircle-02" />

### Icon Sizes

<ComponentPreview name="demo-c-button-squircle-03" />

## Props

### ButtonSquircle

| Prop       | Type                                                                                    | Default     | Description                                                                  |
| ---------- | --------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------- |
| `variant`  | `'primary' \| 'secondary' \| 'destructive' \| 'outline' \| 'ghost' \| 'icon' \| 'link'` | `'primary'` | Visual styling variant                                                       |
| `size`     | `'xs' \| 'sm' \| 'default' \| 'lg' \| 'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg'`    | `'default'` | Dimensions and padding                                                       |
| `squircle` | `boolean`                                                                               | `true`      | Enables continuous curvature corner squircle mask                            |
| `render`   | `React.ReactElement \| ((props: any) => React.ReactNode)`                               | -           | Polymorphic Base UI render element (e.g. Next.js Link or `<a>`)              |
| `full`     | `boolean`                                                                               | `false`     | Stretches button to 100% width (supports legacy `asFull`)                    |
| `icon`     | `boolean`                                                                               | `false`     | Adjusts svg sizing behavior for pure icon content (supports legacy `asIcon`) |
| `pointer`  | `boolean`                                                                               | `false`     | Applies explicit cursor-pointer styling (supports legacy `asPointer`)        |
| `hover`    | `boolean`                                                                               | `false`     | Subtle hover scale tactile feedback (supports legacy `whileTap`)             |


# Chroma Palette
URL: https://www.spaceui.one/components/chroma-palette

***

title: Chroma Palette
description: Perceptually uniform color generator and interactive swatch palette with organic gooey fluid morph and one-click copy.
preview: demo-c-chroma-palette-01
---------------------------------

## Installation

<ComponentInstallation name="components-spaceui-chroma-palette" />

## Usage

```tsx
import { ChromaPalette } from '@/components/spaceui/chroma-palette'

export default function Example() {
  return <ChromaPalette count={5} />
}
```

## Props

| Prop              | Type                         | Default     | Description                                     |
| ----------------- | ---------------------------- | ----------- | ----------------------------------------------- |
| `count`           | `number`                     | `5`         | Number of color swatches (min 2, max 5)         |
| `corner`          | `number`                     | `14`        | Swatch corner radius                            |
| `morph`           | `number`                     | `50`        | Morphing animation speed / intensity (0-100)    |
| `palettes`        | `string[][]`                 | `undefined` | Optional array of preset color palettes         |
| `onGenerate`      | `() => string[]`             | `undefined` | Custom palette generation callback              |
| `onPaletteChange` | `(colors: string[]) => void` | `undefined` | Callback invoked when a new palette is selected |


# Cloud
URL: https://www.spaceui.one/components/cloud

***

title: Cloud
description: Volumetric cloud material. Color the sky, sun, and shadows, then fly the camera with mouse or touch.
preview: demo-c-cloud-01
defaultMode: split
------------------

Volumetric Vanta CLOUDS math in WGSL (`vgpu`). The canvas renders at `devicePixelRatio / 3` (desktop) like the original Vanta runtime — full retina would raymarch \~115 steps per pixel and stall the page.

## Installation

<ComponentInstallation name="components-shader-cloud" />

Depends on `vgpu`. WebGPU required.

## Files

| File                   | Role                                            |
| ---------------------- | ----------------------------------------------- |
| `cloud/index.tsx`      | vgpu surface, mouse ease, low-DPR backing store |
| `cloud/clouds.wgsl.ts` | Raymarched fbm clouds (map2–map5)               |

## Usage

```tsx
import { Cloud } from '@/components/shader/cloud'

export default function SpaceUI() {
  return <Cloud className="h-96 w-full" sky="#68b8d7" cloudColor="#adc1de" sun="#ff9919" speed={1} />
}
```

## API Reference

### Cloud

| Prop         | Type     | Default   | Description      |
| ------------ | -------- | --------- | ---------------- |
| `bg`         | `string` | `#ffffff` | Scene background |
| `sky`        | `string` | `#68b8d7` | Sky tint         |
| `cloudColor` | `string` | `#adc1de` | Cloud volume     |
| `shadow`     | `string` | `#183550` | Cloud shadow     |
| `sun`        | `string` | `#ff9919` | Sun disc         |
| `glare`      | `string` | `#ff6633` | Sun glare        |
| `sunlight`   | `string` | `#ff9933` | Direct light     |
| `speed`      | `number` | `1`       | Drift speed      |
| `className`  | `string` | —         | Wrapper class    |


# Data Grid
URL: https://www.spaceui.one/components/data-grid

***

title: Data Grid
description: Displays large datasets in an interactive table where users can sort, filter, paginate, and resize columns to analyze data efficiently.
component: true
base: base
links:
api: [https://tanstack.com/table/latest](https://tanstack.com/table/latest)
preview:
name: demo-c-data-grid-01
align: start
className: '\*\*:\[.preview]:h-auto'
------------------------------------

The current `data-grid` package ships the shared grid context, table renderers, pagination, column controls, drag-and-drop helpers, virtualization, infinite scroll, footer helpers, and row-pinning support. Footer components (`DataGridTableFoot`, `DataGridTableFootRow`, `DataGridTableFootRowCell`) and the `DataGridTableRowPin` toggle are exported from `data-grid-table.tsx`.

In the base build, `data-grid-scroll-area.tsx` is also included and exports `DataGridScrollArea` for dedicated scroll handling around sticky-header or wide tables.

## Installation

<ComponentInstallation name="components-spaceui-data-grid" />

## React Compiler

<Callout title="React Compiler" variant="warning">
  TanStack Table v8 returns a stable table instance whose state mutates internally (the reference itself never changes). React Compiler memoizes reads against that stable reference, so state updates can be skipped. In practice that shows up as stale row-selection checkboxes, frozen sort arrows, and unresponsive pin or pagination controls. The fix is the `"use no memo"` directive, which opts a file out of the compiler. It is an inert no-op when React Compiler is not enabled, and is the recommended interim until TanStack Table v9's compiler-native API lands.

  **Already handled for you.** Every Space UI data-grid file you install (the primitive and the examples) already ships with `"use no memo"`, so installed Space UI code is safe out of the box.

  **What you must do.** If you enable React Compiler, add `"use no memo"` to your own component that calls `useReactTable`, the one file Space UI cannot reach:
</Callout>

```tsx
'use client'
'use no memo' // required only when React Compiler is enabled

export function MyTable() {
  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
  })

  return (
    <DataGrid table={table} recordCount={data.length}>
      {/* ... */}
    </DataGrid>
  )
}
```

Prefer excluding a whole directory over a per-file directive? Configure it in your compiler setup instead (Vite example):

```ts
babel({
  presets: [reactCompilerPreset()],
  exclude: ['**/components/spaceui/data-grid/**', '**/your-tables/**'],
})
```

On Next.js, prefer the per-file `"use no memo"` directive, since its SWC compiler exclusion is more limited.

## Usage

```tsx
import {
  DataGrid,
  DataGridContainer,
  DataGridPagination,
  DataGridTable,
  DataGridTableFootRow,
  DataGridTableFootRowCell,
} from '@/components/spaceui/data-grid'

export default function SpaceUI() {
  const footer = (
    <DataGridTableFootRow>
      <DataGridTableFootRowCell colSpan={columns.length}>Showing {data.length} rows</DataGridTableFootRowCell>
    </DataGridTableFootRow>
  )

  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
  })

  return (
    <DataGrid table={table} recordCount={data.length} tableLayout={{ rowsPinnable: true }}>
      <DataGridContainer>
        <DataGridTable footerContent={footer} />
      </DataGridContainer>
      <DataGridPagination />
    </DataGrid>
  )
}
```

Use `DataGridTableRowPin` inside a column definition to let users pin rows, swap in `DataGridTableVirtual` when you need virtualization or infinite scroll, and wrap sticky-header tables with `DataGridScrollArea` when you want the dedicated base scroll wrapper. When rows can be pinned or virtualized, provide a stable `getRowId` so row identity stays intact across reordering.

## Examples

### Cell Border

<ComponentPreview name="demo-c-data-grid-02" className="**:[.preview]:h-auto" align="start" />

### Dense Table

<ComponentPreview name="demo-c-data-grid-03" className="**:[.preview]:h-auto" align="start" />

### Light Table

<ComponentPreview name="demo-c-data-grid-04" className="**:[.preview]:h-auto" align="start" />

### Striped Table

<ComponentPreview name="demo-c-data-grid-05" className="**:[.preview]:h-auto" align="start" />

### Auto Width

<ComponentPreview name="demo-c-data-grid-06" className="**:[.preview]:h-auto" align="start" />

### Row Selection

<ComponentPreview name="demo-c-data-grid-07" className="**:[.preview]:h-auto" align="start" />

For the full set of variations — expandable rows, sub-grids, sortable / movable /
draggable / resizable / pinnable columns, sticky header, column controls and
visibility, loading skeleton, CRUD in frame, footer totals / summary /
aggregates, infinite scroll, and row pinning — browse the
[Data Grid components](/ui-kit/components/spaceui/data-grid).

## API Reference

### DataGrid

The root component that provides the table context.

| Prop                   | Type                      | Default                | Description                                                            |
| :--------------------- | :------------------------ | :--------------------- | :--------------------------------------------------------------------- |
| `table`                | `Table<TData>`            | -                      | `Required`. The TanStack Table instance.                               |
| `recordCount`          | `number`                  | -                      | `Required`. Total number of records.                                   |
| `isLoading`            | `boolean`                 | `false`                | Whether the table is in a loading state.                               |
| `loadingMode`          | `"skeleton" \| "spinner"` | `"skeleton"`           | The visual style of the loading state.                                 |
| `loadingMessage`       | `ReactNode \| string`     | `"Loading..."`         | Message to display when `loadingMode` is `"spinner"`.                  |
| `fetchingMoreMessage`  | `ReactNode \| string`     | `loadingMessage`       | Message to display while `DataGridTableVirtual` is fetching more rows. |
| `allRowsLoadedMessage` | `ReactNode \| string`     | `"All records loaded"` | Message to display when virtual infinite scroll reaches the end.       |
| `emptyMessage`         | `ReactNode \| string`     | `"No data available"`  | Message to display when the table is empty.                            |
| `onRowClick`           | `(row: TData) => void`    | -                      | Callback function triggered when a row is clicked.                     |
| `tableLayout`          | `DataGridTableLayout`     | -                      | Configuration for table layout and features.                           |
| `tableClassNames`      | `DataGridTableClassNames` | -                      | Custom CSS classes for various table parts.                            |
| `className`            | `string`                  | -                      | Additional CSS classes for the root grid component.                    |

***

### DataGridTableLayout

Configuration object for the table's behavior and appearance.

| Property            | Type                | Default   | Description                                                 |
| :------------------ | :------------------ | :-------- | :---------------------------------------------------------- |
| `dense`             | `boolean`           | `false`   | Whether to use dense padding for cells.                     |
| `cellBorder`        | `boolean`           | `false`   | Whether to show vertical borders between cells.             |
| `rowBorder`         | `boolean`           | `true`    | Whether to show horizontal borders between rows.            |
| `rowRounded`        | `boolean`           | `false`   | Whether to add rounded corners to rows.                     |
| `stripped`          | `boolean`           | `false`   | Whether to use zebra-striping for rows.                     |
| `headerBackground`  | `boolean`           | `true`    | Whether to show a background color for the header.          |
| `headerBorder`      | `boolean`           | `true`    | Whether to show a border below the header.                  |
| `headerSticky`      | `boolean`           | `false`   | Whether the header should be sticky during scroll.          |
| `width`             | `"auto" \| "fixed"` | `"fixed"` | The table layout algorithm (`table-auto` vs `table-fixed`). |
| `columnsVisibility` | `boolean`           | `false`   | Enables column visibility toggling.                         |
| `columnsResizable`  | `boolean`           | `false`   | Enables column resizing.                                    |
| `columnsPinnable`   | `boolean`           | `false`   | Enables column pinning.                                     |
| `columnsMovable`    | `boolean`           | `false`   | Enables moving columns via menu.                            |
| `columnsDraggable`  | `boolean`           | `false`   | Enables drag-and-drop for columns.                          |
| `rowsDraggable`     | `boolean`           | `false`   | Enables drag-and-drop for rows.                             |
| `rowsPinnable`      | `boolean`           | `false`   | Enables row pinning (top/bottom).                           |

***

### DataGridTableClassNames

Custom CSS classes for different parts of the table.

| Property       | Type     | Default | Description                                        |
| :------------- | :------- | :------ | :------------------------------------------------- |
| `base`         | `string` | -       | CSS classes for the `<table>` element.             |
| `header`       | `string` | -       | CSS classes for the `<thead>` element.             |
| `headerRow`    | `string` | -       | CSS classes for header rows.                       |
| `headerSticky` | `string` | -       | CSS classes for sticky header state.               |
| `body`         | `string` | -       | CSS classes for the `<tbody>` element.             |
| `bodyRow`      | `string` | -       | CSS classes for body rows.                         |
| `footer`       | `string` | -       | CSS classes for the `<tfoot>` element.             |
| `edgeCell`     | `string` | -       | CSS classes for the first and last cells in a row. |

***

### DataGridContainer

A scrollable container for the table.

| Prop        | Type      | Default | Description                                    |
| :---------- | :-------- | :------ | :--------------------------------------------- |
| `border`    | `boolean` | `true`  | Whether to show a border around the container. |
| `className` | `string`  | -       | Additional CSS classes for the container.      |

***

### DataGridScrollArea

Dedicated scroll wrapper for wide grids and sticky headers.

| Prop          | Type                                   | Default  | Description                             |
| :------------ | :------------------------------------- | :------- | :-------------------------------------- |
| `children`    | `ReactNode`                            | -        | `Required`. The grid content to wrap.   |
| `orientation` | `"horizontal" \| "vertical" \| "both"` | `"both"` | Which scrollbars to render.             |
| `className`   | `string`                               | -        | Additional CSS classes for the wrapper. |

***

### DataGridTable

The component that renders the actual HTML table. It automatically handles data rendering, loading states (skeletons/spinners), empty states, footer rows, and pinned rows when `rowsPinnable` is enabled on the parent `DataGrid`.

| Prop            | Type        | Default | Description                                        |
| :-------------- | :---------- | :------ | :------------------------------------------------- |
| `footerContent` | `ReactNode` | -       | Optional footer content rendered inside `<tfoot>`. |
| `renderHeader`  | `boolean`   | `true`  | Whether to render the table header.                |

***

### DataGridPagination

The component for table pagination controls.

| Prop                | Type       | Default                      | Description                                           |
| :------------------ | :--------- | :--------------------------- | :---------------------------------------------------- |
| `sizes`             | `number[]` | `[5, 10, 25, 50, 100]`       | Array of available page sizes.                        |
| `sizesLabel`        | `string`   | `"Show"`                     | Label for the page size selector.                     |
| `sizesDescription`  | `string`   | `"per page"`                 | Description following the page size selector.         |
| `rowsPerPageLabel`  | `string`   | `"Rows per page"`            | Accessible label for the rows per page selector.      |
| `info`              | `string`   | `"{from} - {to} of {count}"` | Template for displaying record info.                  |
| `more`              | `boolean`  | `false`                      | Whether to show ellipsis for more pages.              |
| `moreLimit`         | `number`   | `5`                          | The number of page buttons to show before truncating. |
| `previousPageLabel` | `string`   | `"Go to previous page"`      | Accessible label for the previous page button.        |
| `nextPageLabel`     | `string`   | `"Go to next page"`          | Accessible label for the next page button.            |
| `ellipsisText`      | `string`   | `"..."`                      | Text to display for the ellipsis button.              |
| `className`         | `string`   | -                            | Additional CSS classes for the pagination container.  |

***

### DataGridColumnHeader

A flexible column header component with built-in support for sorting, pinning, and moving columns.

| Prop         | Type                    | Default | Description                                                |
| :----------- | :---------------------- | :------ | :--------------------------------------------------------- |
| `column`     | `Column<TData, TValue>` | -       | `Required`. The TanStack Column instance.                  |
| `title`      | `string`                | -       | The title to display in the header.                        |
| `icon`       | `ReactNode`             | -       | Optional icon to display next to the title.                |
| `filter`     | `ReactNode`             | -       | Optional filter component to display in the header menu.   |
| `visibility` | `boolean`               | `false` | Whether to include column visibility controls in the menu. |

***

### DataGridColumnFilter

A popover-based multi-select filter for columns.

| Prop      | Type                                                            | Default | Description                                       |
| :-------- | :-------------------------------------------------------------- | :------ | :------------------------------------------------ |
| `column`  | `Column<TData, TValue>`                                         | -       | The TanStack Column instance to filter.           |
| `title`   | `string`                                                        | -       | The title for the filter trigger and placeholder. |
| `options` | `Array<{ label: string, value: string, icon?: ComponentType }>` | -       | `Required`. The list of options to filter by.     |

***

### DataGridColumnVisibility

A dropdown component to toggle column visibility.

| Prop      | Type           | Default | Description                                              |
| :-------- | :------------- | :------ | :------------------------------------------------------- |
| `table`   | `Table<TData>` | -       | `Required`. The TanStack Table instance.                 |
| `trigger` | `ReactElement` | -       | `Required`. The trigger element for the visibility menu. |

***

### DataGridTableDnd

Used for enabling column drag-and-drop reordering with optional footer rendering.

| Prop            | Type                            | Default | Description                                                       |
| :-------------- | :------------------------------ | :------ | :---------------------------------------------------------------- |
| `handleDragEnd` | `(event: DragEndEvent) => void` | -       | `Required`. Callback triggered when a column drag operation ends. |
| `footerContent` | `ReactNode`                     | -       | Optional footer content rendered inside `<tfoot>`.                |

***

### DataGridTableDndRows

Used for enabling row drag-and-drop reordering with optional footer rendering.

| Prop            | Type                            | Default | Description                                                        |
| :-------------- | :------------------------------ | :------ | :----------------------------------------------------------------- |
| `dataIds`       | `UniqueIdentifier[]`            | -       | `Required`. Array of unique identifiers for the current page data. |
| `handleDragEnd` | `(event: DragEndEvent) => void` | -       | `Required`. Callback triggered when a row drag operation ends.     |
| `footerContent` | `ReactNode`                     | -       | Optional footer content rendered inside `<tfoot>`.                 |

***

### DataGridTableVirtual

A virtualized table renderer using `@tanstack/react-virtual` for row virtualization, infinite scroll, optional footer rows, and pinned rows when `rowsPinnable` is enabled. The wrapper manages row count and the scroll element for you, while `virtualizerOptions` lets you customize the underlying TanStack Virtual instance. Set `scrollToRowIndex` to reveal a controlled center row; `"auto"` alignment keeps already-visible rows in place and accounts for sticky headers.

| Prop                 | Type                                     | Default  | Description                                                                                                                          |
| :------------------- | :--------------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| `height`             | `number \| string`                       | -        | Optional fixed height when not using an outer scroll container.                                                                      |
| `estimateSize`       | `number`                                 | `48`     | Estimated row height in pixels for the virtualizer.                                                                                  |
| `overscan`           | `number`                                 | `10`     | Number of rows to render outside the visible area.                                                                                   |
| `scrollBehavior`     | `ScrollBehavior`                         | `"auto"` | Scroll animation used when revealing `scrollToRowIndex`.                                                                             |
| `scrollToRowAlign`   | `"auto" \| "center" \| "start" \| "end"` | `"auto"` | Alignment used when revealing the target row. `"auto"` only scrolls when the row is outside the visible area.                        |
| `scrollToRowIndex`   | `number`                                 | -        | Index within the center (non-pinned) row section to reveal. Supports custom scroll elements and disabled virtualization.             |
| `footerContent`      | `ReactNode`                              | -        | Optional footer content rendered inside `<tfoot>`.                                                                                   |
| `renderHeader`       | `boolean`                                | `true`   | Whether to render the table header.                                                                                                  |
| `onFetchMore`        | `() => void`                             | -        | Callback triggered when user scrolls near the bottom.                                                                                |
| `isFetchingMore`     | `boolean`                                | -        | Whether additional data is currently being loaded.                                                                                   |
| `hasMore`            | `boolean`                                | -        | Whether there are more records available to fetch.                                                                                   |
| `fetchMoreOffset`    | `number`                                 | `0`      | How many rows before the end should trigger `onFetchMore`.                                                                           |
| `virtualizerOptions` | `DataGridTableVirtualizerOptions<TData>` | -        | Optional passthrough for TanStack Virtual settings like `enabled`, `getItemKey`, `measureElement`, `rangeExtractor`, and `onChange`. |

***

### DataGridTableRowPin

A pin/unpin toggle button for use in column definitions to enable row pinning.

| Prop  | Type         | Default | Description                                  |
| :---- | :----------- | :------ | :------------------------------------------- |
| `row` | `Row<TData>` | -       | `Required`. The TanStack Table row instance. |

***

### DataGridTableFoot

Wrapper component for the table footer (`<tfoot>`).

***

### DataGridTableFootRow

A row inside the table footer.

***

### DataGridTableFootRowCell

A cell inside a footer row.

| Prop        | Type        | Default | Description                      |
| :---------- | :---------- | :------ | :------------------------------- |
| `colSpan`   | `number`    | -       | Column span for the footer cell. |
| `className` | `string`    | -       | Additional CSS classes.          |
| `children`  | `ReactNode` | -       | Content of the footer cell.      |

***

### DOM Attributes

Data rows carry these attributes so you can target them from queries, tests, and styles. They are applied by the shared row renderer, so they appear on standard, virtualized, pinned, and draggable rows alike. Spacer, skeleton, empty, and expanded-detail rows are rendered separately and carry none of them.

| Attribute         | Value               | Description                                                                                                                            |
| :---------------- | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------- |
| `data-row-id`     | `string`            | The resolved TanStack Table row id, respecting any `getRowId` configuration. Stable across sorting and pagination.                     |
| `data-index`      | `number`            | Position of the row within the rendered rows, used for virtual measurement and striping. Omitted when the renderer does not supply it. |
| `data-row-pinned` | `"top" \| "bottom"` | Which edge the row is pinned to. Omitted entirely when the row is not pinned.                                                          |

## All 29 variations

### Data grid with expandable rows

<ComponentPreview name="demo-c-data-grid-08" />

### Data grid with sub table

<ComponentPreview name="demo-c-data-grid-09" />

### Data grid with column icons

<ComponentPreview name="demo-c-data-grid-10" />

### Data grid with sortable columns

<ComponentPreview name="demo-c-data-grid-11" />

### Data grid with movable columns

<ComponentPreview name="demo-c-data-grid-12" />

### Data grid with draggable columns

<ComponentPreview name="demo-c-data-grid-13" />

### Data grid with draggable rows

<ComponentPreview name="demo-c-data-grid-14" />

### Data grid with column resizing

<ComponentPreview name="demo-c-data-grid-15" />

### Data grid with pinnable columns

<ComponentPreview name="demo-c-data-grid-16" />

### Data grid with sticky header

<ComponentPreview name="demo-c-data-grid-17" />

### Data grid with column controls

<ComponentPreview name="demo-c-data-grid-18" />

### Data grid with card container

<ComponentPreview name="demo-c-data-grid-19" />

### Data grid with column visibility controls

<ComponentPreview name="demo-c-data-grid-20" />

### Data grid with loading skeleton

<ComponentPreview name="demo-c-data-grid-21" />

### Data grid with CRUD features

<ComponentPreview name="demo-c-data-grid-22" />

### Data grid with CRUD in frame container

<ComponentPreview name="demo-c-data-grid-23" />

### Data grid with column totals footer

<ComponentPreview name="demo-c-data-grid-24" />

### Data grid with summary stats footer

<ComponentPreview name="demo-c-data-grid-25" />

### Data grid with per-column aggregate footer

<ComponentPreview name="demo-c-data-grid-26" />

### Data grid with local infinite scroll

<ComponentPreview name="demo-c-data-grid-27" />

### Data grid with remote infinite scroll

<ComponentPreview name="demo-c-data-grid-28" />

### Data grid with row pinning support

<ComponentPreview name="demo-c-data-grid-29" />


# Date Selector
URL: https://www.spaceui.one/components/date-selector

***

title: Date Selector
description: Allows users to quickly choose single dates or time ranges using interactive timeline scrubbers and preset shortcut buttons.
component: true
base: base
preview:
name: demo-c-date-selector-01
align: start
className: '\*\*:\[.preview]:h-auto!'
-------------------------------------

## Installation

<ComponentInstallation name="components-spaceui-date-selector" />

## Usage

```tsx
import * as React from 'react'
import { DateSelector, type DateSelectorValue } from '@/components/spaceui/date-selector'

export default function SpaceUI() {
  const [value, setValue] = React.useState<DateSelectorValue | undefined>()

  return <DateSelector value={value} onChange={setValue} label="Due date" />
}
```

## Examples

### With Popover

<ComponentPreview name="demo-c-date-selector-02" />

### With Dialog

<ComponentPreview name="demo-c-date-selector-03" />

### With i18n Support

<ComponentPreview name="demo-c-date-selector-04" />

## API Reference

### DateSelector

The main component for selecting dates and time periods.

| Prop                | Type                                 | Default                    | Description                                                              |
| :------------------ | :----------------------------------- | :------------------------- | :----------------------------------------------------------------------- |
| `value`             | `DateSelectorValue`                  | -                          | The current value of the selector.                                       |
| `onChange`          | `(value: DateSelectorValue) => void` | -                          | Callback fired when the value changes.                                   |
| `allowRange`        | `boolean`                            | `true`                     | Whether to allow selecting date ranges (using "between" operator).       |
| `periodTypes`       | `DateSelectorPeriodType[]`           | -                          | List of available period types (day, month, etc.).                       |
| `defaultPeriodType` | `DateSelectorPeriodType`             | `"day"`                    | The initial period type.                                                 |
| `defaultFilterType` | `DateSelectorFilterType`             | `"is"`                     | The initial filter operator.                                             |
| `presetMode`        | `DateSelectorFilterType`             | -                          | If set, locks the selector to this specific filter mode.                 |
| `showInput`         | `boolean`                            | `true`                     | Whether to show the text input field above the selector.                 |
| `showTwoMonths`     | `boolean`                            | `true`                     | Whether to show two months in the calendar view (desktop only).          |
| `label`             | `string`                             | -                          | Optional label to display above the filter toggle.                       |
| `yearRange`         | `number`                             | `10`                       | The number of years to show in the year/month/quarter list.              |
| `baseYear`          | `number`                             | `new Date().getFullYear()` | The reference year for the year selection list.                          |
| `minYear`           | `number`                             | `2015`                     | The minimum selectable year.                                             |
| `maxYear`           | `number`                             | `2026`                     | The maximum selectable year.                                             |
| `i18n`              | `Partial<DateSelectorI18nConfig>`    | -                          | Custom labels and operators for internationalization.                    |
| `inputHint`         | `string`                             | -                          | Optional hint text to display in the input field when empty and focused. |
| `dayDateFormat`     | `string`                             | `"MM/dd/yyyy"`             | The format used to display single days.                                  |
| `className`         | `string`                             | -                          | Additional CSS classes for the container.                                |

***

### Interfaces

#### DateSelectorValue

The structure of the value returned by the `onChange` callback.

| Property     | Type                              | Description                                                                |
| :----------- | :-------------------------------- | :------------------------------------------------------------------------- |
| `period`     | `DateSelectorPeriodType`          | The selected period type (`day`, `month`, `quarter`, `half-year`, `year`). |
| `operator`   | `DateSelectorFilterType`          | The selected operator (`is`, `before`, `after`, `between`).                |
| `startDate`  | `Date`                            | The selected start date (for `day` period).                                |
| `endDate`    | `Date`                            | The selected end date (for `day` period range).                            |
| `year`       | `number`                          | The selected year.                                                         |
| `month`      | `number`                          | The selected month (0-11).                                                 |
| `quarter`    | `number`                          | The selected quarter (0-3).                                                |
| `halfYear`   | `number`                          | The selected half-year (0-1).                                              |
| `rangeStart` | `{ year: number; value: number }` | The start of a period range.                                               |
| `rangeEnd`   | `{ year: number; value: number }` | The end of a period range.                                                 |


# Detachable Accordion
URL: https://www.spaceui.one/components/detachable-accordion

***

title: Detachable Accordion
description: An interactive accordion with spring motion where the expanded item physically detaches with animated gaps and rounded corners.
preview:
name: demo-c-detachable-accordion-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-detachable-accordion" />

## Usage

```tsx
import { DetachableAccordion } from '@/components/spaceui/detachable-accordion'
```

```tsx
<DetachableAccordion defaultValue="favorites" detachGap={16} cornerRadius={24} />
```

## API Reference

### DetachableAccordion Props

| Prop            | Type                                   | Default                                 | Description                                                               |
| --------------- | -------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------- |
| `items`         | `DetachableAccordionItem[]`            | `DEFAULT_ITEMS`                         | List of items containing `value`, `title`, `content`, and optional `icon` |
| `value`         | `string`                               | -                                       | Controlled expanded item value                                            |
| `defaultValue`  | `string`                               | `""`                                    | Initial expanded item value                                               |
| `onValueChange` | `(value: string \| undefined) => void` | -                                       | Callback triggered when the expanded item changes                         |
| `detachGap`     | `number`                               | `16`                                    | Spacing in pixels created above and below the active item                 |
| `cornerRadius`  | `number`                               | `24`                                    | Border radius in pixels applied to the active item and neighboring edges  |
| `spring`        | `Transition`                           | `mass: 10, stiffness: 900, damping: 80` | Motion spring configuration for detachment and icon rotation              |
| `className`     | `string`                               | -                                       | Additional class name applied to outer container                          |


# Dirt Carousel
URL: https://www.spaceui.one/components/dirt-carousel

***

title: Dirt Carousel
description: 3D ring of video worlds. Drag, wheel, or snap. Open the gear panel to change radius, tilt, and auto-rotate.
preview: demo-c-dirt-carousel-01
--------------------------------

Interactive 3D cylindrical ring carousel. Drag, wheel, or snap between cards. Items, dimensions, and motion physics are configurable via props.

## Installation

<ComponentInstallation name="components-spaceui-dirt-carousel" />

## Usage

```tsx
import { DirtCarousel, type DirtCarouselItem } from '@/components/spaceui/dirt-carousel'

const items: DirtCarouselItem[] = [
  {
    name: 'Brand',
    mediaType: 'video',
    videoLink: 'https://...',
    thumbnail: 'https://...',
  },
  {
    name: 'Showcase',
    mediaType: 'image',
    imageLink: 'https://...',
  },
]

export default function Example() {
  return <DirtCarousel items={items} radius={800} ballSize={800} bounce={false} snap={true} />
}
```

## Props

| Prop              | Type                       | Default  | Description                                   |
| ----------------- | -------------------------- | -------- | --------------------------------------------- |
| `items`           | `DirtCarouselItem[]`       | `[]`     | Array of media items (video or image).        |
| `direction`       | `'flat' \| 'up' \| 'down'` | `'flat'` | Orbital tilt angle of the 3D ring.            |
| `radius`          | `number`                   | `800`    | Radius of the circular orbit in pixels.       |
| `perspective`     | `number`                   | `800`    | 3D CSS perspective camera distance.           |
| `ballSize`        | `number`                   | `800`    | Size of each carousel item container.         |
| `dragSensitivity` | `number`                   | `0.5`    | Drag speed multiplier.                        |
| `bounce`          | `boolean`                  | `false`  | Floating / bounce animation up and down.      |
| `mouseTilt`       | `boolean`                  | `false`  | Tilts carousel towards the mouse pointer.     |
| `snap`            | `boolean`                  | `true`   | Snaps smoothly to nearest item when released. |
| `autoRotate`      | `boolean`                  | `false`  | Enables continuous automatic rotation.        |
| `autoRotateSpeed` | `number`                   | `0.3`    | Speed of auto rotation (items/second).        |


# Doodle Callout
URL: https://www.spaceui.one/components/doodle-callout

***

title: Doodle Callout
description: A hand-drawn arrow that draws itself next to a handwritten label, replaying on a loop.
preview: demo-c-doodle-callout-01
---------------------------------

## Installation

<ComponentInstallation name="components-spaceui-doodle-callout" />

## Usage

```tsx
import { DoodleCallout } from '@/components/spaceui/doodle-callout'

export default function PricingCard() {
  return (
    <div className="relative">
      <div className="rounded-2xl bg-muted px-6 py-3">Complete plan</div>
      <DoodleCallout label="Most popular" className="absolute top-full left-1/2" />
    </div>
  )
}
```

The stroke draws from start to end, then the label blur-reveals in place above it. The whole sequence replays every `loopInterval`.

## Props

| Prop              | Type     | Default               | Description                                                               |
| ----------------- | -------- | --------------------- | ------------------------------------------------------------------------- |
| `label`           | `string` | —                     | The handwritten annotation text                                           |
| `path`            | `string` | the hand-drawn stroke | SVG path `d`, animated from start to end                                  |
| `viewBox`         | `string` | `'0 0 457 101'`       | viewBox matching the path's coordinate space                              |
| `width`           | `number` | `280`                 | SVG width                                                                 |
| `height`          | `number` | `62`                  | SVG height                                                                |
| `strokeWidth`     | `number` | `5`                   | Stroke width                                                              |
| `revealGap`       | `number` | `400`                 | Delay in ms between the stroke finishing and the label revealing          |
| `loopInterval`    | `number` | `8000`                | How often the sequence replays once settled, in ms — `0` disables looping |
| `className`       | `string` | —                     | Class on the outer wrapper                                                |
| `labelClassName`  | `string` | —                     | Class on the label — pass your own script/cursive font here               |
| `strokeClassName` | `string` | —                     | Class on the SVG                                                          |


# Event Calendar
URL: https://www.spaceui.one/components/event-calendar

***

title: Event Calendar
description: Displays scheduled events across day, week, and month views, making it easy for users to create and manage appointments.
component: true
base: base
preview:
name: demo-c-event-calendar-01
align: start
------------

The demo above is the whole feature surface in one example: every view (month, week, day, N-days, agenda, and the resource time grid), a multi-day all-day bar, custom chips via `renderEvent`, and a tabbed Settings panel driving view settings, time-grid options, and interactions as controlled props - with a reset back to defaults.

The `event-calendar` package separates the calendar engine from the calendar UI. A subscribable store (`useEventCalendarState`) owns events, view, date, selection, and interactions with controlled and uncontrolled modes for every state pair; the shipped view components (month, week, day, N-days, agenda, and a resource day grid) render from that store through fine-grained selector hooks. Events are yours: the calendar never persists anything, it proposes changes through `onEventUpdate` and you accept, adjust, or reject them.

The composition contract is a provider plus slots: `<EventCalendar>` wraps `<EventCalendarNav />`, an optional `<EventCalendarToolbar />`, and `<EventCalendarContent />`. Recurrence (an RFC 5545 subset, structured rules or raw `RRULE` strings), display time zones via `@date-fns/tz`, pointer-based drag, resize, and drag-create, and per-key i18n overrides are built in.

## Installation

<ComponentInstallation name="components-spaceui-event-calendar" />

## Usage

```tsx
import * as React from 'react'
import { EventCalendar } from '@/components/spaceui/event-calendar/event-calendar'
import { EventCalendarContent } from '@/components/spaceui/event-calendar/event-calendar-content'
import { EventCalendarNav } from '@/components/spaceui/event-calendar/event-calendar-nav'
import type { CalendarEvent } from '@/components/spaceui/event-calendar/event-calendar-types'

export default function SpaceUI() {
  const [events, setEvents] = React.useState<CalendarEvent[]>(initialEvents)

  return (
    <EventCalendar events={events} onEventsChange={setEvents} defaultView="week" className="h-[600px]">
      <EventCalendarNav />
      <EventCalendarContent />
    </EventCalendar>
  )
}
```

Pass `defaultEvents` for uncontrolled state or `events` + `onEventsChange` for controlled state; the same pairing exists for `view`, `date`, `dayCount`, `selection`, `interactions`, and `viewSettings`. In the default `scrollMode="contained"` the calendar fills its container and scrolls internally, so give the root an explicit height (the examples use `h-[560px]`). Every timing change, whether from a drag, a resize, or `api.updateEvent`, funnels through `onEventUpdate`: return `false` to reject and revert, return nothing (or `true`) to accept, or return `{ start, end, allDay }` to accept with an adjustment, then persist to your backend from `onEventsChange` or inside `onEventUpdate` itself. Use `onRangeChange` to fetch remote events for the visible range, and `apiRef` (or a hoisted `useEventCalendarState` instance passed as `calendar`) for imperative control from outside the tree.

For more variations, browse the [Event Calendar components](/ui-kit/components/spaceui/event-calendar).

## API Reference

### EventCalendar

The root provider and container. It creates (or adopts) the calendar instance, provides it via context, and renders a flex-column `div` (customizable through `render`). Besides the props below, it accepts every option and callback listed under [State options](#state-options) and [Callbacks](#callbacks), and every display prop listed under [View configuration](#view-configuration).

| Prop        | Type                                         | Default | Description                                                                                                               |
| :---------- | :------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------ |
| `calendar`  | `EventCalendarInstance<TData>`               | -       | Adopt a hoisted `useEventCalendarState` instance; option props are then ignored (a dev warning fires if both are passed). |
| `apiRef`    | `RefObject<EventCalendarApi<TData> \| null>` | -       | Imperative escape hatch; receives the instance API for use outside the tree.                                              |
| `children`  | `ReactNode`                                  | -       | Composed slots, typically `EventCalendarNav`, `EventCalendarToolbar`, and `EventCalendarContent`.                         |
| `className` | `string`                                     | -       | Additional CSS classes for the root element.                                                                              |
| `render`    | `useRender` render prop                      | -       | Replace the rendered root element.                                                                                        |

***

### EventCalendarNav

Default composed navigation: Today, view switcher, prev/next, title, and a trailing spacer. Pass `children` to use it as a pure layout shell and compose the nav parts yourself. Renders as a `div` with `useRender` support.

| Prop               | Type        | Default | Description                                                                      |
| :----------------- | :---------- | :------ | :------------------------------------------------------------------------------- |
| `showViewSwitcher` | `boolean`   | `true`  | Render the view switcher in the composed layout; turn off for fixed-view embeds. |
| `children`         | `ReactNode` | -       | Replaces the default composed layout entirely.                                   |
| `className`        | `string`    | -       | Additional CSS classes for the nav container.                                    |

***

### EventCalendarNavToday

The "Today" navigation button; resets the calendar to now. It follows the configured `navButtonVariant` / `navButtonSize` and the `classNames.navButton` hook, and gets `data-active` while the anchor period contains now. `EventCalendarNavPrev` and `EventCalendarNavNext` share the same props.

| Prop       | Type                    | Default | Description                                                                                                                                   |
| :--------- | :---------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| `tooltip`  | `ReactNode \| null`     | -       | Hover/focus-visible hint. Today defaults to the current date; Prev/Next default to their i18n labels. Pass `null` to disable this one button. |
| `children` | `ReactNode`             | -       | Replaces the default label or chevron icon.                                                                                                   |
| `render`   | `useRender` render prop | -       | Replace the rendered button element.                                                                                                          |

***

### EventCalendarNavPrev

The previous-period navigation button; steps the anchor date one period back for the current view. Same props as [`EventCalendarNavToday`](#eventcalendarnavtoday), except `tooltip` defaults to the i18n "previous" label and `children` replaces the default chevron icon.

***

### EventCalendarNavNext

The next-period navigation button; steps the anchor date one period forward for the current view. Same props as [`EventCalendarNavToday`](#eventcalendarnavtoday), except `tooltip` defaults to the i18n "next" label and `children` replaces the default chevron icon.

***

### EventCalendarTitle

The current period title (from `i18n.functions.formatTitle`), marked `aria-live="polite"`.

| Prop     | Type                                    | Default | Description                                |
| :------- | :-------------------------------------- | :------ | :----------------------------------------- |
| `format` | `(ctx: { title: string }) => ReactNode` | -       | Wrap or transform the computed title text. |

***

### EventCalendarViewSwitcher

Dropdown listing the available views (the resolved `views` option) with optional keyboard-shortcut hints; when the `days` view is enabled, one item per `dayCountPresets` entry is offered.

| Prop       | Type                | Default | Description                                                                                 |
| :--------- | :------------------ | :------ | :------------------------------------------------------------------------------------------ |
| `tooltip`  | `ReactNode \| null` | -       | Hover-only hint (force-closed while the menu is open); defaults to the "Select view" label. |
| `children` | `ReactNode`         | -       | Replaces the default trigger content (current view name + chevron).                         |

***

### EventCalendarDatePicker

Optional go-to-date popover (shadcn Calendar), not part of the default nav; compose it yourself. It is view-aware: week, N-days, and agenda highlight the whole active range, other views select a single date.

| Prop       | Type                            | Default  | Description                                                                     |
| :--------- | :------------------------------ | :------- | :------------------------------------------------------------------------------ |
| `mode`     | `"auto" \| "single" \| "range"` | `"auto"` | `"auto"` resolves to `"range"` for week/N-days/agenda and `"single"` otherwise. |
| `tooltip`  | `ReactNode \| null`             | `null`   | No tooltip by default (the button opens an overlay); pass a node to opt in.     |
| `children` | `ReactNode`                     | -        | Replaces the default calendar icon.                                             |

***

### EventCalendarToolbar

Free slot for consumer toolbar buttons; a pure layout shell (`flex items-center gap-2`) with `useRender` support and the `classNames.toolbar` hook. No props beyond standard `div` props.

***

### EventCalendarContent

Active-view switchboard: renders the component registered for the current view and exposes `data-view` / `data-loading` attributes. While `loading` is true it dims and disables pointer events.

| Prop         | Type                                           | Default | Description                                                                    |
| :----------- | :--------------------------------------------- | :------ | :----------------------------------------------------------------------------- |
| `components` | `Partial<Record<CalendarView, ComponentType>>` | -       | Swap individual view implementations (merged over the root `components` prop). |
| `children`   | `ReactNode`                                    | -       | Replaces the switchboard entirely; read `useEventCalendarView()` inside.       |

***

### EventCalendarMonthView

ARIA-grid month view: week rows, day cells, continuous multi-day bars in a lane overlay, "+N more" overflow, week numbers, and the day add affordance.

| Prop               | Type               | Default | Description                                                                |
| :----------------- | :----------------- | :------ | :------------------------------------------------------------------------- |
| `maxEventsPerCell` | `number \| "auto"` | -       | Per-view override of the `maxEventsPerCell` view config (bars plus chips). |

***

### EventCalendarTimeGrid

The shared week/day/N-days engine: hour gutter, minute-positioned event blocks with overlap packing, the all-day row, drag ghosts, and the now indicator. You usually render one of the wrappers below instead.

| Prop           | Type                        | Default | Description                                                                                     |
| :------------- | :-------------------------- | :------ | :---------------------------------------------------------------------------------------------- |
| `view`         | `"week" \| "day" \| "days"` | -       | `Required`. Which time-based view this grid renders.                                            |
| `dayStartHour` | `number`                    | -       | Per-view override of the `dayStartHour` option.                                                 |
| `dayEndHour`   | `number`                    | -       | Per-view override of the `dayEndHour` option.                                                   |
| `showAllDay`   | `boolean`                   | `true`  | Render the all-day row above the time track.                                                    |
| `interval`     | `number`                    | -       | Gutter/gridline interval in minutes (clamped 5 to 240); defaults to the `interval` view config. |

***

### EventCalendarWeekView

Thin wrapper around [`EventCalendarTimeGrid`](#eventcalendartimegrid) with `view` preset to `"week"`. Accepts every `EventCalendarTimeGrid` prop except `view`.

***

### EventCalendarDayView

Thin wrapper around [`EventCalendarTimeGrid`](#eventcalendartimegrid) with `view` preset to `"day"`. Accepts every `EventCalendarTimeGrid` prop except `view`.

***

### EventCalendarDaysView

Thin wrapper around [`EventCalendarTimeGrid`](#eventcalendartimegrid) with `view` preset to `"days"`. Accepts every `EventCalendarTimeGrid` prop except `view`.

***

### EventCalendarAgendaView

Chronological list grouped by day: sticky date gutters, collapsible days with a color-dot summary row, expandable per-event details (via `renderAgendaEventDetails`), and a compact empty state. The agenda window length comes from the `agendaDayCount` option, so the view has no props beyond standard `div` props.

***

### EventCalendarResourceView

Resource-columns day grid for booking scenarios: one time axis, one column per leaf resource (from the `resources` option, flattened depth-first), with full drag, resize, and drag-create across columns.

| Prop           | Type      | Default | Description                                                                                     |
| :------------- | :-------- | :------ | :---------------------------------------------------------------------------------------------- |
| `dayStartHour` | `number`  | -       | Per-view override of the `dayStartHour` option.                                                 |
| `dayEndHour`   | `number`  | -       | Per-view override of the `dayEndHour` option.                                                   |
| `showAllDay`   | `boolean` | `true`  | Render the all-day row above the time track.                                                    |
| `interval`     | `number`  | -       | Gutter/gridline interval in minutes (clamped 5 to 240); defaults to the `interval` view config. |

***

### EventCalendarApi

The imperative API, available as `instance.api`, through `apiRef`, or from any hook's instance. Reading methods reflect the current snapshot; writing methods respect controlled props (they call the matching `on*Change` callback and only mutate internal state for uncontrolled fields).

| Method                 | Signature                                                                                              | Description                                                                                |
| :--------------------- | :----------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- |
| `next` / `prev`        | `() => void`                                                                                           | Step the anchor date one period forward or backward for the current view.                  |
| `today`                | `() => void`                                                                                           | Jump to now.                                                                               |
| `goTo`                 | `(date: Date) => void`                                                                                 | Jump to a date.                                                                            |
| `setView`              | `(view: CalendarView, opts?: { dayCount?: number }) => void`                                           | Switch view; unknown views fall back to the first enabled view with a dev warning.         |
| `setDayCount`          | `(count: number) => void`                                                                              | Set the N-day count (min 1).                                                               |
| `getEvents`            | `() => CalendarEvent<TData>[]`                                                                         | Current events array.                                                                      |
| `getEvent`             | `(id: string) => CalendarEvent<TData> \| undefined`                                                    | Find one event by id.                                                                      |
| `setEvents`            | `(events: CalendarEvent<TData>[]) => void`                                                             | Replace the events array.                                                                  |
| `addEvent`             | `(event: CalendarEvent<TData>) => void`                                                                | Append an event.                                                                           |
| `updateEvent`          | `(id: string, patch: Partial<CalendarEvent<TData>>) => void`                                           | Patch an event; timing patches route through `onEventUpdate` with `source: "api"`.         |
| `removeEvent`          | `(id: string) => void`                                                                                 | Remove an event.                                                                           |
| `getOccurrences`       | `(range?: EventCalendarDateRange) => EventCalendarOccurrence<TData>[]`                                 | Expanded, sorted occurrences; defaults to the visible range.                               |
| `getOccurrencesForDay` | `(day: Date) => EventCalendarOccurrence<TData>[]`                                                      | Deduplicated occurrences touching one day.                                                 |
| `findOverlapping`      | `(candidate: { start: Date; end: Date; excludeEventId?: string }) => EventCalendarOccurrence<TData>[]` | Occurrences overlapping a candidate range.                                                 |
| `select`               | `(selection: Partial<EventCalendarSelection>) => void`                                                 | Patch the selection.                                                                       |
| `selectEvent`          | `(key: string, opts?: { additive?: boolean }) => void`                                                 | Select an occurrence key; `additive` toggles it within the current set.                    |
| `clearSelection`       | `() => void`                                                                                           | Clear event keys and the committed slot.                                                   |
| `setInteractions`      | `(patch: Partial<EventCalendarInteractions>) => void`                                                  | Toggle drag, resize, or slot selection.                                                    |
| `setViewSettings`      | `(patch: EventCalendarViewSettings) => void`                                                           | Patch the user display toggles.                                                            |
| `getVisibleRange`      | `() => EventCalendarDateRange`                                                                         | The full rendered grid range (including outside days); fetch remote data for this.         |
| `getActiveRange`       | `() => EventCalendarDateRange`                                                                         | The logical period (the month or week itself).                                             |
| `toZoned`              | `(date: Date) => Date`                                                                                 | The instant re-expressed in the calendar's display time zone (a `TZDate`).                 |
| `scrollToTime`         | `(time: Date \| number) => void`                                                                       | Scroll a time grid to an instant or minutes-from-day-start; no-op outside time-grid views. |

***

### CalendarEvent

Your event objects. `TData` is a fully generic consumer payload.

| Property           | Type                                    | Default | Description                                                                    |
| :----------------- | :-------------------------------------- | :------ | :----------------------------------------------------------------------------- |
| `id`               | `string`                                | -       | `Required`. Stable event id.                                                   |
| `title`            | `string`                                | -       | `Required`. Display title.                                                     |
| `start`            | `Date`                                  | -       | `Required`. Start instant (consumers parse ISO strings themselves).            |
| `end`              | `Date`                                  | -       | `Required`. Exclusive end instant; must be greater than or equal to `start`.   |
| `allDay`           | `boolean`                               | -       | Render as an all-day bar; date comparison is day-granular in the display zone. |
| `recurrence`       | `EventCalendarRecurrenceRule \| string` | -       | Structured rule or a raw `"RRULE:..."` line.                                   |
| `recurringEventId` | `string`                                | -       | Marks this event as an edited single occurrence of that series.                |
| `originalStart`    | `Date`                                  | -       | Which occurrence it replaces (RECURRENCE-ID semantics).                        |
| `color`            | `string`                                | -       | Token or CSS color; flows to the `--ec-event-color` CSS variable.              |
| `readOnly`         | `boolean`                               | -       | Excluded from drag and resize regardless of the interactions state.            |
| `draggable`        | `boolean`                               | -       | Per-event override; the default comes from `interactions.drag`.                |
| `resizable`        | `boolean`                               | -       | Per-event override; the default comes from `interactions.resize`.              |
| `priority`         | `number`                                | -       | Packing prominence; feeds the `getEventPriority` ordering.                     |
| `zIndex`           | `number`                                | -       | Explicit stacking override; wins over the computed z-index.                    |
| `resourceId`       | `string`                                | -       | Bookable resource this event belongs to (resource view).                       |
| `data`             | `TData`                                 | -       | Consumer payload, fully generic.                                               |

***

### EventCalendarResource

A bookable resource (room, person, equipment). Nested resources render their leaves as booking columns in the resource view.

| Property   | Type                      | Default | Description                                                 |
| :--------- | :------------------------ | :------ | :---------------------------------------------------------- |
| `id`       | `string`                  | -       | `Required`. Stable resource id.                             |
| `title`    | `string`                  | -       | `Required`. Column header text (or `renderResourceHeader`). |
| `color`    | `string`                  | -       | Token or CSS color for subtle row/column accents.           |
| `children` | `EventCalendarResource[]` | -       | Child resources; only leaves become booking columns.        |

***

### EventCalendarRecurrenceRule

The structured RFC 5545 subset. A raw `RRULE` string with the same parts is equally accepted on `event.recurrence`.

| Property     | Type                                                                            | Default | Description                                                                                  |
| :----------- | :------------------------------------------------------------------------------ | :------ | :------------------------------------------------------------------------------------------- |
| `freq`       | `"daily" \| "weekly" \| "monthly" \| "yearly"`                                  | -       | `Required`. Recurrence frequency.                                                            |
| `interval`   | `number`                                                                        | `1`     | Every N periods.                                                                             |
| `count`      | `number`                                                                        | -       | Total number of occurrences.                                                                 |
| `until`      | `Date`                                                                          | -       | Inclusive end instant.                                                                       |
| `byWeekday`  | `Array<EventCalendarWeekday \| { day: EventCalendarWeekday; ordinal: number }>` | -       | Weekdays; ordinals (`2TU`, `-1FR`) apply to monthly/yearly rules.                            |
| `byMonthDay` | `number[]`                                                                      | -       | Days of the month; negative values count back from month end.                                |
| `byMonth`    | `number[]`                                                                      | -       | Months (1 to 12) for yearly rules.                                                           |
| `weekStart`  | `EventCalendarWeekday`                                                          | -       | WKST equivalent.                                                                             |
| `exDates`    | `Date[]`                                                                        | -       | Excluded instants; matching occurrences are removed (they still consume their `count` slot). |
| `rDates`     | `Date[]`                                                                        | -       | Extra instants added to the series, each with the event's own duration.                      |

`EventCalendarWeekday` is `"MO" \| "TU" \| "WE" \| "TH" \| "FR" \| "SA" \| "SU"`. For rule parts outside this subset, plug a full RRULE engine through the `getOccurrences` option; unsupported parts throw `EventCalendarRecurrenceError`.

***

### EventCalendarOccurrence

One expanded instance of an event, as passed to click callbacks and returned by `api.getOccurrences`.

| Property          | Type                   | Description                                            |
| :---------------- | :--------------------- | :----------------------------------------------------- |
| `key`             | `string`               | Stable per instance: `` `${event.id}::${startISO}` ``. |
| `eventId`         | `string`               | The source event id.                                   |
| `event`           | `CalendarEvent<TData>` | The source event.                                      |
| `start` / `end`   | `Date`                 | This instance's instants (end exclusive).              |
| `allDay`          | `boolean`              | Resolved all-day flag.                                 |
| `isRecurring`     | `boolean`              | Whether it came from a recurrence expansion.           |
| `recurrenceIndex` | `number`               | Series ordinal, when recurring.                        |

***

### EventCalendarSegment

A per-day slice of an occurrence, produced by the event index and consumed by `EventCalendarEvent` and the layout hooks. Positional fields are filled per surface: `startMin` / `endMin` for timed blocks, `lane` / `column` / `columnCount` / `columnSpan` for packing, and `rowIndex` / `colStart` / `colSpan` for month/all-day bars. `isStart` / `isEnd` and `continuesBefore` / `continuesAfter` mark cross-day edges.

***

### EventCalendarProposedUpdate

The payload of `onEventUpdate` and `canDropEvent`: a proposed timing (and optionally resource) change.

| Property     | Type                                                              | Description                                                  |
| :----------- | :---------------------------------------------------------------- | :----------------------------------------------------------- |
| `event`      | `CalendarEvent<TData>`                                            | The event being changed.                                     |
| `occurrence` | `EventCalendarOccurrence<TData> \| null`                          | The dragged occurrence; `null` when `source` is `"api"`.     |
| `start`      | `Date`                                                            | Proposed start.                                              |
| `end`        | `Date`                                                            | Proposed exclusive end.                                      |
| `allDay`     | `boolean`                                                         | Proposed all-day flag.                                       |
| `resourceId` | `string`                                                          | Proposed resource when the gesture crossed resource columns. |
| `source`     | `"drag" \| "resize-start" \| "resize-end" \| "keyboard" \| "api"` | What produced the proposal.                                  |

The `onEventUpdate` return type is `EventCalendarUpdateResult`: `false` rejects and reverts, `void` or `true` accepts, and `{ start?, end?, allDay? }` accepts with an adjustment.

***

### EventCalendarSlotInfo

The payload of `onSlotClick`. A click is a point, not a range.

| Property     | Type           | Description                                                             |
| :----------- | :------------- | :---------------------------------------------------------------------- |
| `date`       | `Date`         | Clicked instant (snapped in time grids) or day (day-granular surfaces). |
| `end`        | `Date`         | Present for timed slots: `date` plus `slotDuration`.                    |
| `allDay`     | `boolean`      | Whether the click landed on a day-granular surface.                     |
| `view`       | `CalendarView` | The view the click happened in.                                         |
| `resourceId` | `string`       | Present when the click happened inside a resource column.               |

***

### EventCalendarSlotDraft

The drag-create rectangle, passed to `onSelectSlot` and `canSelectSlot`. The in-progress draft lives in state as `slotDraft` and is cleared on commit or cancel; the committed slot selection lives in `selection.slot`.

| Property     | Type           | Description                                                  |
| :----------- | :------------- | :----------------------------------------------------------- |
| `start`      | `Date`         | Draft start.                                                 |
| `end`        | `Date`         | Draft exclusive end.                                         |
| `allDay`     | `boolean`      | Whether the draft was drawn on a day-granular surface.       |
| `view`       | `CalendarView` | The view the draft was drawn in.                             |
| `resourceId` | `string`       | Present when the slot was selected inside a resource column. |

***

### EventCalendarState

The store snapshot, as received by `useEventCalendarSelector` selectors and `instance.getState()`.

| Property       | Type                                    | Description                                                                          |
| :------------- | :-------------------------------------- | :----------------------------------------------------------------------------------- |
| `view`         | `CalendarView`                          | Active view (`"month" \| "week" \| "day" \| "days" \| "agenda" \| "resource"`).      |
| `date`         | `Date`                                  | Anchor date.                                                                         |
| `dayCount`     | `number`                                | Day count for the `days` view.                                                       |
| `visibleRange` | `EventCalendarDateRange`                | Full rendered grid range including outside days; fetch remote data for this.         |
| `activeRange`  | `EventCalendarDateRange`                | The logical period (the month or week itself).                                       |
| `events`       | `CalendarEvent<TData>[]`                | Current events.                                                                      |
| `selection`    | `EventCalendarSelection`                | Selected occurrence keys plus the committed slot.                                    |
| `interactions` | `EventCalendarInteractions`             | Effective interaction toggles.                                                       |
| `loading`      | `boolean`                               | The `loading` prop.                                                                  |
| `drag`         | `EventCalendarDragState<TData> \| null` | Live move/resize gesture (kind, occurrence, proposed instants, validity), or `null`. |
| `slotDraft`    | `EventCalendarSlotDraft \| null`        | Live drag-create rectangle, or `null`.                                               |
| `viewSettings` | `EventCalendarViewSettings`             | User display toggles.                                                                |

`EventCalendarDateRange` is `{ start: Date; end: Date }` with an inclusive start and an exclusive end. The exported `EventCalendarDataAdapter` type (`getEvents(range, signal?)`) describes the shape of an external data source; wiring it to a backend is application territory.

## Hooks

Most hooks require an `<EventCalendar>` ancestor. The exceptions: `useEventCalendarState` creates the instance itself, `useNow` is standalone, `useEventCalendarSettingsVersion` takes the instance as an argument, and hooks that accept an explicit `calendar` option work outside the tree.

| Hook                              | Signature                                                                                     | Description                                                                                                                                                                    |
| :-------------------------------- | :-------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useEventCalendarState`           | `(options?: UseEventCalendarStateOptions<TData>) => EventCalendarInstance<TData>`             | Headless root hook: the full engine without markup. Pass the instance to `<EventCalendar calendar={instance}>` or drive fully custom UI from `getState` / `subscribe` / `api`. |
| `useEventCalendar`                | `() => EventCalendarInstance<TData>`                                                          | The stable calendar instance from context; throws outside `<EventCalendar>`.                                                                                                   |
| `useEventCalendarSelector`        | `(selector: (state: EventCalendarState<TData>) => T, options?: { calendar?, isEqual? }) => T` | Fine-grained subscription with equality memoization (`Object.is` default).                                                                                                     |
| `useEventCalendarView`            | `() => { view, dayCount, availableViews, setView }`                                           | Active view state plus the resolved `views` option.                                                                                                                            |
| `useEventCalendarNavigation`      | `() => { date, title, visibleRange, activeRange, next, prev, today, goTo, isToday }`          | Navigation state and actions; `title` is the formatted period title.                                                                                                           |
| `useEventCalendarSelection`       | `() => { selection, select, selectEvent, clearSelection }`                                    | Selection state and actions.                                                                                                                                                   |
| `useEventCalendarInteractions`    | `() => { interactions, setInteractions }`                                                     | Interaction toggles.                                                                                                                                                           |
| `useEventCalendarOccurrences`     | `(range?: EventCalendarDateRange) => EventCalendarOccurrence<TData>[]`                        | Expanded, sorted occurrences; defaults to the visible range.                                                                                                                   |
| `useEventCalendarDay`             | `(day: Date) => { segments: { allDay, timed }, isToday, isOutside }`                          | Per-cell subscription; only cells whose segments changed re-render.                                                                                                            |
| `useEventCalendarWeek`            | `(day: Date) => { bars, laneCount, rowStart }`                                                | Per-week-row subscription for the month view's laned multi-day bars.                                                                                                           |
| `useEventCalendarViewSettings`    | `() => { viewSettings, setViewSettings, effective }`                                          | User display toggles plus the effective values after view-config fallback.                                                                                                     |
| `useEventCalendarSettings`        | `() => EventCalendarSettings<TData>`                                                          | Resolved settings including merged i18n; re-renders only when settings change.                                                                                                 |
| `useEventCalendarSettingsVersion` | `(instance: EventCalendarInstance<TData>) => number`                                          | Subscribes to settings changes only (version counter, not state).                                                                                                              |
| `useEventCalendarViewConfig`      | `() => EventCalendarViewConfig<TData>`                                                        | Root-level display props and render overrides, for view components.                                                                                                            |
| `useEventCalendarViewContext`     | `() => { view: CalendarView }`                                                                | The rendering view of the nearest view component; throws outside a view.                                                                                                       |
| `useEventCalendarGestures`        | `() => { beginMove, beginResize, beginCreate, canDrag, canResize }`                           | Per-chip / per-surface pointer gesture wiring for custom views and cells.                                                                                                      |
| `useEventCalendarEventChip`       | `() => { occurrence, segment, isDragging, isSelected }`                                       | The chip's subject; usable inside `renderEvent` content and chip children.                                                                                                     |
| `useNow`                          | `(intervalMs?: number) => Date`                                                               | Current time, refreshed on an interval (default 30000 ms) and on tab focus.                                                                                                    |

An `EventCalendarInstance` is `{ getState, subscribe, api, settings, internals }`; `internals` is cross-file plumbing for sibling view modules and not public API.

## Helpers

Pure, React-free helpers exported from `event-calendar-lib.tsx` (plus the gesture flags from `event-calendar-dnd.tsx`). `event-calendar-lib.tsx` also exports the advanced types `EventCalendarIndex`, `EventCalendarDayBucket`, and `EventCalendarWeekRow` used in these signatures, and `event-calendar.tsx` exports the `EventCalendarContext`, `EventCalendarViewConfigContext`, and `EventCalendarViewContext` context objects for advanced composition.

| Function             | Signature                                                                                | Description                                                                                      |
| :------------------- | :--------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
| `flattenResources`   | `(resources: EventCalendarResource[], depth?: number) => Array<{ resource, depth }>`     | Depth-first flatten of the resource tree, parents included.                                      |
| `buildEventIndex`    | `(events, visibleRange, opts) => EventCalendarIndex<TData>`                              | Expand, segment, and pack all events for a range into `{ occurrences, byDay, weekRows }`.        |
| `segmentOccurrence`  | `(occurrence, range, timeZone) => EventCalendarSegment<TData>[]`                         | The canonical multi-day segmentation (exclusive end, zero-duration safe).                        |
| `packTimedSegments`  | `(segments) => void`                                                                     | Google-style overlap packing for one day's timed segments (mutates `column` fields in place).    |
| `packWeekRowLanes`   | `(segments, rowIndex, rowStart, timeZone) => EventCalendarSegment<TData>[]`              | Greedy lane packing of bar segments within one week row; returns new merged bar segments.        |
| `defaultEventOrder`  | `(a, b: EventCalendarOccurrence) => number`                                              | Default sort: earlier start, then longer duration, then key.                                     |
| `getViewDateRange`   | `(view, date, opts) => { visibleRange, activeRange }`                                    | The rendered and logical ranges for a view and anchor date.                                      |
| `stepDate`           | `(view, date, direction, opts) => Date`                                                  | The anchor date stepped one period forward or backward.                                          |
| `toZoned`            | `(date: Date, timeZone: string) => TZDate`                                               | The instant re-expressed in the display time zone.                                               |
| `zonedStartOfDay`    | `(date: Date, timeZone: string) => TZDate`                                               | Zoned midnight of the day containing the instant.                                                |
| `getDayKey`          | `(date: Date, timeZone: string) => string`                                               | Stable per-day key (`yyyy-MM-dd`) in the display time zone.                                      |
| `getDayTotalMinutes` | `(dayStart: Date, timeZone: string) => number`                                           | Day length in minutes; 1380/1500 on DST transition days.                                         |
| `getRangeKey`        | `(range: EventCalendarDateRange) => string`                                              | Cheap string cache key for a range.                                                              |
| `snapMinutes`        | `(minutes: number, snap: number) => number`                                              | Round minutes to the nearest snap step.                                                          |
| `rangesIntersect`    | `(a, b: EventCalendarDateRange) => boolean`                                              | Half-open range intersection.                                                                    |
| `eventsOverlap`      | `(a, b: { start: Date; end: Date }) => boolean`                                          | Half-open overlap test.                                                                          |
| `isBarOccurrence`    | `(occurrence: EventCalendarOccurrence) => boolean`                                       | True when the occurrence renders as a bar (all-day or multi-day).                                |
| `spansMultipleDays`  | `(occ: { start: Date; end: Date }) => boolean`                                           | Longer than 24 hours (an event ending exactly at midnight is single-day).                        |
| `resolveOffDay`      | `(day, timeZone, config: boolean \| EventCalendarOffDaysConfig \| undefined) => boolean` | Whether a day is an off day in the display zone.                                                 |
| `minuteBlockStyle`   | `(startMin, endMin, boundsStartMin) => CSSProperties`                                    | Absolute top/height for a minute-positioned overlay block (from `event-calendar-time-grid.tsx`). |
| `wasRecentDrag`      | `() => boolean`                                                                          | True shortly after a gesture ended; lets click handlers ignore the click that ends a drag.       |
| `wasRecentChipPress` | `() => boolean`                                                                          | True shortly after a press started on an event chip; guards slot-create clicks.                  |
| `markChipPress`      | `() => void`                                                                             | Flag a chip press (called by `EventCalendarEvent`); needed when building custom chips.           |

Useful exported constants: `BASE_VIEWS` and `ALL_VIEWS` (the view lists), `DEFAULT_VIEW_CONFIG`, `DEFAULT_VIEW_COMPONENTS` (the view switchboard map), `EVENT_CALENDAR_ACTIVATION` (gesture defaults), `EVENT_CALENDAR_COLORS` (ten Tailwind palette presets for `event.color`), `EVENT_CALENDAR_GHOST` (the standardized drag-ghost classes), `EVENT_CALENDAR_FADE_TRUNCATE` (the fade-out truncation classes, reusable in `renderEvent` content), `MIN_PACK_SLOT` (packing-effective minimum of 30 minutes), and `MAX_OCCURRENCES` (recurrence expansion cap of 1000 per event).

***

### Recurrence helpers

Exported from `event-calendar-recurrence.tsx`. The supported `RRULE` subset is `FREQ` (daily, weekly, monthly, yearly), `INTERVAL`, `COUNT`, `UNTIL`, `BYDAY` (with ordinals for monthly/yearly), `BYMONTHDAY`, `BYMONTH`, and `WKST`; anything else throws `EventCalendarRecurrenceError`, whose message points at the `getOccurrences` escape hatch.

| Function            | Signature                                                               | Description                                                                                                       |
| :------------------ | :---------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
| `expandRecurrence`  | `(event, range, ctx: { timeZone }) => EventCalendarOccurrence<TData>[]` | Expand one event into its occurrences intersecting the range; wall-time iteration in the display zone (DST-safe). |
| `parseRRuleString`  | `(input: string, timeZone?: string) => EventCalendarRecurrenceRule`     | Parse a raw `RRULE` line (with or without the prefix); Z-less `UNTIL` values are wall time in the given zone.     |
| `formatRRuleString` | `(rule: EventCalendarRecurrenceRule) => string`                         | Serialize the structured subset back to an `RRULE` line (without prefix).                                         |

## Config

### State options

Option props accepted by `EventCalendar` and `useEventCalendarState`. Controlled/uncontrolled pairs follow the standard convention: pass the controlled prop plus its `on*Change` callback, or the `default*` prop for internal state.

| Prop                                   | Type                                                                             | Default                         | Description                                                                                                                                                                   |
| :------------------------------------- | :------------------------------------------------------------------------------- | :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `events` / `defaultEvents`             | `CalendarEvent<TData>[]`                                                         | `[]`                            | The events (controlled / uncontrolled).                                                                                                                                       |
| `view` / `defaultView`                 | `CalendarView`                                                                   | `"month"`                       | Active view.                                                                                                                                                                  |
| `date` / `defaultDate`                 | `Date`                                                                           | `new Date()`                    | Anchor date.                                                                                                                                                                  |
| `dayCount` / `defaultDayCount`         | `number`                                                                         | `3`                             | Day count for the `days` view (min 1).                                                                                                                                        |
| `selection` / `defaultSelection`       | `EventCalendarSelection`                                                         | `{ eventKeys: [], slot: null }` | Selection state.                                                                                                                                                              |
| `interactions` / `defaultInteractions` | `Partial<EventCalendarInteractions>`                                             | all `true`                      | Interaction toggles, merged over the defaults.                                                                                                                                |
| `viewSettings` / `defaultViewSettings` | `EventCalendarViewSettings`                                                      | `{}`                            | User display toggles.                                                                                                                                                         |
| `loading`                              | `boolean`                                                                        | `false`                         | Dims the content area and disables pointer events.                                                                                                                            |
| `views`                                | `CalendarView[]`                                                                 | base views                      | Enabled views; defaults to `["month", "week", "day", "days", "agenda"]`, plus `"resource"` when `resources` is non-empty.                                                     |
| `timeZone`                             | `string`                                                                         | system time zone                | IANA display time zone; all day math and rendering happen in it.                                                                                                              |
| `locale`                               | `Locale`                                                                         | -                               | date-fns locale for every formatted string.                                                                                                                                   |
| `weekStartsOn`                         | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`                                                | `locale`                        | First day of the week (0 = Sunday). Defaults to the `locale`'s own first day when one is set, so a German or French calendar starts on Monday; an explicit value always wins. |
| `dayStartHour`                         | `number`                                                                         | `0`                             | First rendered hour in time grids.                                                                                                                                            |
| `dayEndHour`                           | `number`                                                                         | `24`                            | Last rendered hour in time grids.                                                                                                                                             |
| `slotDuration`                         | `number`                                                                         | `30`                            | Duration in minutes of a click-created slot (`onSlotClick` end).                                                                                                              |
| `snapDuration`                         | `number`                                                                         | `15`                            | Snap granularity in minutes for drag, resize, and drag-create.                                                                                                                |
| `agendaDayCount`                       | `number`                                                                         | `30`                            | Days covered by the agenda view window.                                                                                                                                       |
| `fixedWeeks`                           | `boolean`                                                                        | `true`                          | Month view always renders 6 weeks.                                                                                                                                            |
| `showOutsideDays`                      | `boolean`                                                                        | `true`                          | Show leading/trailing outside days in the month view.                                                                                                                         |
| `i18n`                                 | `Partial<EventCalendarI18nConfig>`                                               | -                               | Per-key overrides of labels, view names, formats, and formatter functions.                                                                                                    |
| `resources`                            | `EventCalendarResource[]`                                                        | `[]`                            | Bookable resources for the resource view.                                                                                                                                     |
| `getEventPriority`                     | `(event: CalendarEvent<TData>) => number`                                        | `event.priority ?? 0`           | Packing prominence resolver.                                                                                                                                                  |
| `eventOrder`                           | `(a, b: EventCalendarOccurrence<TData>) => number`                               | `defaultEventOrder`             | Occurrence sort comparator (default: earlier start, then longer duration, then key).                                                                                          |
| `getOccurrences`                       | `(event, range, ctx: { timeZone }) => Array<{ start: Date; end: Date }> \| null` | -                               | Custom recurrence expansion per event (plug a full RRULE engine); return `null` for the built-in one.                                                                         |
| `weekendDays`                          | `number[]`                                                                       | `[0, 6]`                        | Weekday numbers treated as the weekend by the "weekends" view toggle.                                                                                                         |
| `activation`                           | `Partial<EventCalendarActivationConfig>`                                         | see below                       | Pointer-gesture tuning.                                                                                                                                                       |

`EventCalendarActivationConfig` defaults: `moveDistancePx: 5`, `createDistancePx: 4`, `touchDelayMs: 250`, `touchTolerancePx: 5`, `autoScrollEdgePx: 48`, `autoScrollMaxStepPx: 15` (exported as `EVENT_CALENDAR_ACTIVATION`).

***

### Callbacks

Callback props accepted by `EventCalendar` and `useEventCalendarState`, alongside the options above.

| Prop                   | Signature                                                                                                             | Description                                                                                                                                                |
| :--------------------- | :-------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onEventClick`         | `(occurrence, e: React.MouseEvent) => void`                                                                           | Chip click; call `e.preventDefault()` to opt out of the built-in selection.                                                                                |
| `onEventDoubleClick`   | `(occurrence, e: React.MouseEvent) => void`                                                                           | Chip double click.                                                                                                                                         |
| `onEventUpdate`        | `(update: EventCalendarProposedUpdate<TData>) => EventCalendarUpdateResult`                                           | The one validation funnel for drags, resizes, and API timing changes; `false` rejects, an object adjusts.                                                  |
| `canDropEvent`         | `(update: EventCalendarProposedUpdate<TData>) => boolean`                                                             | Live validation during a gesture; drives the `data-drop-invalid` styling and the not-allowed cursor.                                                       |
| `onDragBlocked`        | `(occurrence, info: { gesture: "move" \| "resize"; reason: "readOnly" \| "disabled" \| "interactions-off" }) => void` | A gesture was attempted on a locked event; fires once per gesture so you can surface a message.                                                            |
| `onSlotClick`          | `(slot: EventCalendarSlotInfo, e: React.MouseEvent) => void`                                                          | Click on an empty slot or day cell (also fired by the day add button).                                                                                     |
| `onSelectSlot`         | `(slot: EventCalendarSlotDraft) => void`                                                                              | A drag-create selection was committed.                                                                                                                     |
| `canSelectSlot`        | `(slot: EventCalendarSlotDraft) => boolean`                                                                           | Live validation of the drag-create rectangle.                                                                                                              |
| `onRangeChange`        | `(info: EventCalendarRangeInfo) => void`                                                                              | Visible range changed (view, date, or time zone); fires once for the initial range. `info` carries `range`, `activeRange`, `view`, `date`, and `timeZone`. |
| `onViewChange`         | `(view: CalendarView) => void`                                                                                        | View changed.                                                                                                                                              |
| `onDateChange`         | `(date: Date) => void`                                                                                                | Anchor date changed.                                                                                                                                       |
| `onDayCountChange`     | `(count: number) => void`                                                                                             | N-day count changed.                                                                                                                                       |
| `onSelectionChange`    | `(selection: EventCalendarSelection) => void`                                                                         | Selection changed.                                                                                                                                         |
| `onInteractionsChange` | `(interactions: EventCalendarInteractions) => void`                                                                   | Interaction toggles changed.                                                                                                                               |
| `onViewSettingsChange` | `(viewSettings: EventCalendarViewSettings) => void`                                                                   | User display toggles changed.                                                                                                                              |
| `onEventsChange`       | `(events: CalendarEvent<TData>[]) => void`                                                                            | Events array changed (drag commit, resize, API mutation).                                                                                                  |
| `onMoreClick`          | `(day: Date, occurrences: EventCalendarOccurrence<TData>[], e: React.MouseEvent) => void \| false`                    | "+N more" clicked; return `false` to suppress the built-in popover and open your own UI.                                                                   |

***

### View configuration

Display props and render overrides, accepted directly on `EventCalendar` (they live in the view layer, never in the headless options). Defaults come from `DEFAULT_VIEW_CONFIG`.

| Prop                   | Type                                                | Default                                                       | Description                                                                                                                                                      |
| :--------------------- | :-------------------------------------------------- | :------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scrollToHour`         | `number`                                            | `7`                                                           | Hour the time grids scroll to on mount.                                                                                                                          |
| `nowIndicator`         | `boolean`                                           | `true`                                                        | Show the current-time line in time grids.                                                                                                                        |
| `interval`             | `number`                                            | `60`                                                          | Grid interval in minutes for time-based views; gutter slots and gridlines follow it. Also accepted per view component.                                           |
| `maxEventsPerCell`     | `number \| "auto"`                                  | `"auto"`                                                      | Max bars plus chips per month cell before "+N more".                                                                                                             |
| `showWeekNumbers`      | `boolean`                                           | `false`                                                       | Week-number gutter in the month view.                                                                                                                            |
| `enableShortcuts`      | `boolean`                                           | `true`                                                        | View-switcher keyboard shortcuts and their `kbd` hints.                                                                                                          |
| `shortcutsScope`       | `"focus-within" \| "global"`                        | `"focus-within"`                                              | Where the shortcuts listen.                                                                                                                                      |
| `scrollMode`           | `"contained" \| "page"`                             | `"contained"`                                                 | Contained: the calendar fills its container and views scroll internally. Page: content flows with the document and day headers stick below `--ec-sticky-offset`. |
| `stickyNav`            | `boolean`                                           | `false`                                                       | Stick the default nav to the top while the page scrolls.                                                                                                         |
| `dayClassName`         | `(day: Date) => string \| undefined`                | -                                                             | Custom per-day indication on month cells, day columns, and all-day cells.                                                                                        |
| `todayClassName`       | `string`                                            | -                                                             | Extra classes for the current day, appended after the built-in highlight.                                                                                        |
| `showDayAddButton`     | `boolean`                                           | `false`                                                       | Hover "+" affordance on month cells; fires the same `onSlotClick` as clicking the day.                                                                           |
| `scrollbars`           | `"custom" \| "native"`                              | `"custom"`                                                    | Scroll implementation for every internally scrolling surface (shadcn ScrollArea vs browser scrollbars).                                                          |
| `navButtonVariant`     | `"ghost" \| "outline" \| "secondary" \| "default"`  | `"ghost"`                                                     | Variant applied to all nav buttons.                                                                                                                              |
| `navButtonSize`        | `"sm" \| "default"`                                 | `"sm"`                                                        | Size applied to all nav buttons (icon buttons use the icon twin).                                                                                                |
| `offDays`              | `boolean \| EventCalendarOffDaysConfig`             | -                                                             | Off-day (non-working day) marking; `true` = weekends with a muted background.                                                                                    |
| `classNames`           | `EventCalendarClassNames`                           | -                                                             | Per-element class hooks; see below.                                                                                                                              |
| `components`           | `Partial<Record<CalendarView, ComponentType>>`      | -                                                             | Swap individual view implementations.                                                                                                                            |
| `dayCountPresets`      | `number[]`                                          | `[5]`                                                         | N-day presets offered by the view switcher when the `days` view is enabled.                                                                                      |
| `navTooltips`          | `false \| { side?, delay?, closeDelay?, timeout? }` | `{ side: "bottom", delay: 600, closeDelay: 0, timeout: 300 }` | Nav tooltips: `false` disables them all; the object tunes placement and timings.                                                                                 |
| `eventTooltip`         | `boolean \| { side?, delay? }`                      | `false`                                                       | Styled tooltip on event hover / focus; `true` shows the event label, an object tunes side and delay. Content via `renderEventTooltip`.                           |
| `compactEventMinutes`  | `number`                                            | `45`                                                          | Timed events shorter than this render the compact single-row chip layout.                                                                                        |
| `morePopoverAlign`     | `"start" \| "center" \| "end"`                      | `"start"`                                                     | "+N more" popover alignment against its trigger.                                                                                                                 |
| `nowIndicatorInterval` | `number`                                            | `30000`                                                       | Now-indicator refresh cadence in milliseconds.                                                                                                                   |
| `agendaSummaryMaxDots` | `number`                                            | `6`                                                           | Max color dots in a collapsed agenda day summary.                                                                                                                |

Render overrides, all optional and all part of the same view config:

| Prop                        | Signature                                                                                    | Description                                                                                                   |
| :-------------------------- | :------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ |
| `renderEvent`               | `(props: EventCalendarRenderEventProps<TData>) => ReactNode`                                 | Replace the chip content in grid views; receives `occurrence`, `segment`, `view`, `isDragging`, `isSelected`. |
| `renderAgendaEvent`         | `(props: EventCalendarRenderEventProps<TData>) => ReactNode`                                 | Replace the agenda row content.                                                                               |
| `renderEventTooltip`        | `(props: { occurrence, segment, view, label }) => ReactNode`                                 | Content for the styled hover tooltip (`eventTooltip`); a falsy return falls back to the default label.        |
| `renderDragPreview`         | `(props: { drag: EventCalendarDragState<TData> }) => ReactNode`                              | Custom drag preview content.                                                                                  |
| `renderMonthCell`           | `(props: { day, segments, isToday, isOutside, overflowCount, defaultContent }) => ReactNode` | Replace a month cell's body; `defaultContent` lets you wrap instead of rebuild.                               |
| `renderDayColumnBackground` | `(props: { day, boundsStartMin, boundsEndMin, totalMinutes }) => ReactNode`                  | Business-logic layer rendered pointer-events-none behind event segments in each day column.                   |
| `renderDayHeader`           | `(props: { day, view, isToday }) => ReactNode`                                               | Replace day header cells (month header row and time-grid headers).                                            |
| `renderTimeGutterSlot`      | `(props: { time, hour, minute }) => ReactNode`                                               | Replace hour gutter labels.                                                                                   |
| `renderAllDaySection`       | `(props: { days, segments }) => ReactNode`                                                   | Replace the entire all-day row of time grids.                                                                 |
| `renderMoreIndicator`       | `(props: { day, count, segments }) => ReactNode`                                             | Replace the "+N more" trigger content.                                                                        |
| `renderMoreContent`         | `(props: { day, segments, close }) => ReactNode`                                             | Replace the entire body of the built-in "+N more" popover while keeping its trigger and positioning.          |
| `renderAgendaEventDetails`  | `(occurrence: EventCalendarOccurrence<TData>) => ReactNode`                                  | Agenda-only expandable details; returning a node gives the row an expand/collapse toggle.                     |
| `renderNowIndicator`        | `(props: { time: Date }) => ReactNode`                                                       | Replace the current-time line.                                                                                |
| `renderNoEvents`            | `() => ReactNode`                                                                            | Replace the agenda empty state.                                                                               |
| `renderResourceHeader`      | `(props: { resource: EventCalendarResource }) => ReactNode`                                  | Resource column header content; default is `resource.title`.                                                  |
| `renderAgendaDayHeader`     | `(props: { day, collapsed, count, toggle, defaultContent }) => ReactNode`                    | Replace the agenda date gutter (day badge, weekday, collapse toggle).                                         |
| `renderAgendaDaySummary`    | `(props: { day, occurrences, count, expand, defaultContent }) => ReactNode`                  | Replace the collapsed agenda day summary row content.                                                         |

The `classNames` object (`EventCalendarClassNames`) offers one string hook per element, cn-merged after the built-in classes so Tailwind variants and `!` overrides win. Available keys: `nav`, `toolbar`, `content`, `monthView`, `monthCell`, `timeGrid`, `timeGutter`, `dayColumn`, `allDaySection`, `agendaView`, `event`, `eventTooltip`, `moreIndicator`, `morePopover`, `morePopoverHeader`; nav family `navButton`, `title`, `navTooltip`, `viewSwitcherContent`, `viewSwitcherLabel`, `viewShortcut`, `datePickerContent`; month view `monthHeader`, `monthDayHeader`, `monthBody`, `monthRow`, `weekNumber`, `monthBarOverlay`, `monthBar`, `monthCellContent`, `monthCellFooter`, `monthDayNumber`, `dayAddButton`; time grid and resource `timeGridHeader`, `timeGutterLabel`, `allDayLabel`, `allDayCell`, `timedChip`, `resourceHeader`; interaction surfaces `dragGhost`, `dragCarry`, `dragCarryInvalid`, `dropHint`, `dropIndicator`, `slotDraft`, `resizeHandle`, `resizeGrip`; agenda `noEvents`, `agendaDay`, `agendaDayGutter`, `agendaDate`, `agendaDayToggle`, `agendaDayContent`, `agendaItem`, `agendaItemSurface`, `agendaItemToggle`, `agendaDaySummary`, `agendaSummaryDot`. Metric CSS variables can ride on any parent key, for example `classNames.timeGrid: "[--ec-gutter-width:4rem]"` or `classNames.morePopover: "[--ec-more-max-height:20rem]"`.

***

### EventCalendarInteractions

Interaction toggles, controllable via the `interactions` prop or `api.setInteractions`. All three default to `true`.

| Property     | Type      | Default | Description                   |
| :----------- | :-------- | :------ | :---------------------------- |
| `drag`       | `boolean` | `true`  | Move events by dragging.      |
| `resize`     | `boolean` | `true`  | Resize events at their edges. |
| `selectSlot` | `boolean` | `true`  | Drag-create slot selection.   |

***

### EventCalendarViewSettings

User-adjustable display toggles (the "view settings" state), controllable via `viewSettings` / `onViewSettingsChange` or `api.setViewSettings`. Every field is optional; `undefined` defers to the matching view-config prop (see `useEventCalendarViewSettings().effective`).

| Property       | Type      | Default | Description                                                                              |
| :------------- | :-------- | :------ | :--------------------------------------------------------------------------------------- |
| `weekends`     | `boolean` | -       | Show Saturday/Sunday columns in month, week, and N-day grids (effective default `true`). |
| `weekNumbers`  | `boolean` | -       | Week-number gutter in the month view (defers to `showWeekNumbers`).                      |
| `nowIndicator` | `boolean` | -       | Current-time line (defers to the `nowIndicator` view config).                            |
| `offDays`      | `boolean` | -       | Off-day background marking (defers to the `offDays` view config).                        |

***

### EventCalendarOffDaysConfig

Configuration for non-working-day marking, passed as the `offDays` view config. `true` uses the defaults (weekends with a muted background); marked cells carry `data-off` for CSS-selector customization.

| Property      | Type                     | Default         | Description                                                          |
| :------------ | :----------------------- | :-------------- | :------------------------------------------------------------------- |
| `weekendDays` | `number[]`               | `[0, 6]`        | Weekday numbers treated as off (0 = Sunday).                         |
| `dates`       | `Date[]`                 | -               | Additional explicit off dates (compared by day in the display zone). |
| `isOffDay`    | `(day: Date) => boolean` | -               | Full custom predicate; runs in addition to `weekendDays` / `dates`.  |
| `className`   | `string`                 | `"bg-muted/40"` | Marker classes.                                                      |

***

### Internationalization

The `i18n` option accepts a `Partial<EventCalendarI18nConfig>` with four sections, shallow-merged per nested object so a partial override replaces individual keys, never whole sections:

* `labels`: UI strings and label functions (`today`, `previous`, `next`, `addEvent`, `allDay`, `more(count)`, `noEvents`, `loading`, `event`, `events(count)`, `selectView`, `week(weekNumber)`, `resources`, `goToDate`, `dropNotAllowed`, `continues`, `timeFrom(time)`, `timeUntil(time)`, `viewShortcuts`, `toggleDayEvents(count, expanded)`, `eventDetails(title)`, `moreCompact(count)`, `timeRange(from, to)`).
* `viewNames`: display names per view (`month`, `week`, `day`, `days(count)`, `agenda`, `resource`).
* `formats`: date-fns format strings applied with the calendar `locale` (`monthTitle`, `weekTitle`, `dayTitle`, `agendaTitle`, `monthDayHeader`, `monthDayHeaderNarrow`, `timeGridDayHeader`, `agendaDayHeader`, `agendaDayNumber`, `agendaWeekday`, `moreDayHeader`, `monthCellAriaLabel`, `dayAria`, `resourceTitle`, `timeGutter`, `timeGutterMinute`, `eventTime`, `monthCellDay`). Leaving `weekTitle` / `agendaTitle` undefined keeps the smart cross-month range title.
* `functions`: formatter functions (`formatTitle`, `formatEventTime`, `formatDayRange`, `formatEventLabel`, `formatEventAriaLabel`). The defaults are re-bound to the merged labels and formats, so overriding `formats.monthTitle` flows into the default `formatTitle` without replacing it.

`mergeEventCalendarI18n(overrides?)` performs this merge and `DEFAULT_EVENT_CALENDAR_I18N` holds the defaults; both are exported from `event-calendar-i18n.tsx` for standalone use.

## All 5 variations

### Event calendar with resource view for room bookings

<ComponentPreview name="demo-c-event-calendar-02" />

### Event calendar with create and edit dialog

<ComponentPreview name="demo-c-event-calendar-03" />

### Event calendar with custom event chips

<ComponentPreview name="demo-c-event-calendar-04" />

### Event calendar with drag-to-book appointments

<ComponentPreview name="demo-c-event-calendar-05" />


# Filters
URL: https://www.spaceui.one/components/filters

***

title: Filters
description: Provides a filter bar with badges and active tags, allowing users to narrow down search results by multiple criteria simultaneously.
component: true
base: base
preview:
name: demo-c-filters-01
align: start
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="components-spaceui-filters" />

## Usage

```tsx
import * as React from 'react'
import { createFilter, Filters, type Filter, type FilterFieldConfig } from '@/components/spaceui/filters'

export default function SpaceUI() {
  const [filters, setFilters] = React.useState<Filter[]>([createFilter('priority', 'is_any_of', ['low', 'medium'])])

  const fields: FilterFieldConfig[] = [
    {
      key: 'priority',
      label: 'Priority',
      type: 'multiselect',
      options: [
        { value: 'low', label: 'Low' },
        { value: 'medium', label: 'Medium' },
        { value: 'high', label: 'High' },
      ],
    },
  ]

  return <Filters filters={filters} fields={fields} onChange={setFilters} />
}
```

## Examples

### Validation

<ComponentPreview name="demo-c-filters-02" align="start" />

### Trigger Button

<ComponentPreview name="demo-c-filters-03" align="start" />

### Small Size

<ComponentPreview name="demo-c-filters-04" align="start" />

### Large Size

<ComponentPreview name="demo-c-filters-05" align="start" />

### Custom Controls

<ComponentPreview name="demo-c-filters-06" align="start" />

### Data Grid

<ComponentPreview name="demo-c-filters-07" className="**:[.preview]:h-auto" align="start" />

### Nuqs

<ComponentPreview name="demo-c-filters-08" className="**:[.preview]:h-auto" align="start" />

### With i18n Support

<ComponentPreview name="demo-c-filters-09" align="start" />

### Virtualized Large Lists

<ComponentPreview name="demo-c-filters-10" align="start" />

### Prefetched Async Options

<ComponentPreview name="demo-c-filters-11" align="start" />

### Async Server-side Search

<ComponentPreview name="demo-c-filters-12" align="start" />

## API Reference

### Filters

The main component for displaying and managing a collection of active filters.

| Prop                 | Type                             | Default     | Description                                                             |
| :------------------- | :------------------------------- | :---------- | :---------------------------------------------------------------------- |
| `filters`            | `Filter<T>[]`                    | -           | `Required`. The array of active filters.                                |
| `fields`             | `FilterFieldsConfig<T>`          | -           | `Required`. The configuration for available filter fields.              |
| `onChange`           | `(filters: Filter<T>[]) => void` | -           | `Required`. Callback fired when filters are added, updated, or removed. |
| `size`               | `"sm" \| "default" \| "lg"`      | `"default"` | The size of the filter items and controls.                              |
| `trigger`            | `ReactNode`                      | -           | Custom element to trigger the "Add Filter" menu.                        |
| `showSearchInput`    | `boolean`                        | `true`      | Whether to show the search input in the "Add Filter" menu.              |
| `allowMultiple`      | `boolean`                        | `true`      | Whether to allow multiple filters for the same field.                   |
| `enableShortcut`     | `boolean`                        | `false`     | Whether to enable the keyboard shortcut to open the filter menu.        |
| `shortcutKey`        | `string`                         | `"f"`       | The key used for the shortcut (e.g., "f").                              |
| `shortcutLabel`      | `string`                         | `"F"`       | The label to display in the shortcut indicator.                         |
| `i18n`               | `Partial<FilterI18nConfig>`      | -           | Custom labels and operators for internationalization.                   |
| `className`          | `string`                         | -           | Additional CSS classes for the container.                               |
| `menuPopupClassName` | `string`                         | -           | Additional CSS classes for the filter dropdown menu.                    |

***

### FilterFieldConfig

Configuration for an individual filterable field.

| Property              | Type                                                                 | Description                                                                                                                                                                                                                                                                |
| :-------------------- | :------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`                 | `string`                                                             | `Required`. Unique identifier for the field.                                                                                                                                                                                                                               |
| `label`               | `string`                                                             | `Required`. Human-readable label for the field.                                                                                                                                                                                                                            |
| `type`                | `"text" \| "select" \| "multiselect" \| "custom" \| "separator"`     | The type of filter input to use.                                                                                                                                                                                                                                           |
| `icon`                | `ReactNode`                                                          | Optional icon to display next to the field label.                                                                                                                                                                                                                          |
| `options`             | `FilterOption<T>[]`                                                  | List of options for `select` and `multiselect` fields.                                                                                                                                                                                                                     |
| `loadOptions`         | `(query: string) => FilterOption<T>[] \| Promise<FilterOption<T>[]>` | Async options loader for large or remote lists. Called with the current search query - return a prefetched list (ignore the query) or server-side search results. Debounced, with loading/error states and a value-to-label cache. `options` still seeds the initial view. |
| `renderOptionList`    | `(props: FilterOptionListRenderProps<T>) => ReactNode`               | Bring-your-own rendering for the options list, e.g. virtualization with a windowing library of your choice. Receives `{ options, highlightedIndex, renderOption }`; render the scrollable list and call `renderOption` for each row. Omit for the default plain list.      |
| `operators`           | `FilterOperator[]`                                                   | Custom operators for this specific field.                                                                                                                                                                                                                                  |
| `defaultOperator`     | `string`                                                             | The operator to select by default when adding this field.                                                                                                                                                                                                                  |
| `placeholder`         | `string`                                                             | Placeholder text for text inputs.                                                                                                                                                                                                                                          |
| `searchable`          | `boolean`                                                            | Whether the options list should be searchable.                                                                                                                                                                                                                             |
| `maxSelections`       | `number`                                                             | Maximum number of items allowed in `multiselect`.                                                                                                                                                                                                                          |
| `prefix`              | `ReactNode \| string`                                                | Prefix element for the input field.                                                                                                                                                                                                                                        |
| `suffix`              | `ReactNode \| string`                                                | Suffix element for the input field.                                                                                                                                                                                                                                        |
| `pattern`             | `string`                                                             | Regex pattern for text input validation.                                                                                                                                                                                                                                   |
| `validation`          | `(value) => boolean \| object`                                       | Custom validation function.                                                                                                                                                                                                                                                |
| `customRenderer`      | `(props) => ReactNode`                                               | Custom renderer for the filter value selector.                                                                                                                                                                                                                             |
| `customValueRenderer` | `(values, options) => ReactNode`                                     | Custom renderer for the active filter value display.                                                                                                                                                                                                                       |
| `fields`              | `FilterFieldConfig<T>[]`                                             | Nested fields if this is a group configuration.                                                                                                                                                                                                                            |
| `group`               | `string`                                                             | Group label if this is a group configuration.                                                                                                                                                                                                                              |
| `className`           | `string`                                                             | Additional CSS classes for the field components.                                                                                                                                                                                                                           |

***

### FilterOption

Structure for options in `select` and `multiselect` fields.

| Property    | Type        | Description                                      |
| :---------- | :---------- | :----------------------------------------------- |
| `value`     | `T`         | `Required`. The internal value of the option.    |
| `label`     | `string`    | `Required`. Human-readable label for the option. |
| `icon`      | `ReactNode` | Optional icon to display next to the option.     |
| `className` | `string`    | Additional CSS classes for the option item.      |

***

### Filter

The structure of an active filter object.

| Property   | Type     | Description                                      |
| :--------- | :------- | :----------------------------------------------- |
| `id`       | `string` | Unique identifier for the filter instance.       |
| `field`    | `string` | The `key` of the associated field configuration. |
| `operator` | `string` | The selected operator (e.g., "is", "contains").  |
| `values`   | `T[]`    | The current value(s) of the filter.              |

***

### FilterI18nConfig

Configuration for internationalization and custom labels.

| Property       | Type     | Description                                |
| :------------- | :------- | :----------------------------------------- |
| `addFilter`    | `string` | Label for the "Add Filter" button.         |
| `searchFields` | `string` | Placeholder for the field search input.    |
| `operators`    | `object` | Map of operator keys to localized strings. |
| `validation`   | `object` | Map of validation error messages.          |
| `placeholders` | `object` | Map of dynamic placeholder templates.      |

***

### Helpers

| Function            | Signature                                             | Description                                   |
| :------------------ | :---------------------------------------------------- | :-------------------------------------------- |
| `createFilter`      | `(field, operator?, values?) => Filter`               | Creates a new filter object with a unique ID. |
| `createFilterGroup` | `(id, label, fields, initialFilters?) => FilterGroup` | Creates a filter group configuration.         |


# Flip Text
URL: https://www.spaceui.one/components/flip-text

***

title: Flip Text
description: Per-character 3D flip animation with a sine-eased stagger wave across the text.
preview:
name: demo-c-flip-text-01
-------------------------

## Installation

<ComponentInstallation name="components-spaceui-flip-text" />


# Fluid Countdown
URL: https://www.spaceui.one/components/fluid-countdown

***

title: Fluid Countdown
description: A countdown timer with fluid rolling digits, play/pause and reset controls, and auto-loop built with NumberFlow and Motion.
preview:
name: demo-c-fluid-countdown-01
contained: false
----------------

Full-screen countdown with fluid rolling numerals, interactive controls, and accessible motion.

## Installation

<ComponentInstallation name="components-spaceui-fluid-countdown" />

## Usage

```tsx
import { FluidCountdown } from '@/components/spaceui/fluid-countdown'

export default function Timer() {
  return <FluidCountdown duration={60} autoStart loop label="Launch in" accentColor="#6366f1" />
}
```


# Fluid Crossfade
URL: https://www.spaceui.one/components/fluid-crossfade

***

title: Fluid Crossfade
description: Dual-pass WebGL fluid simulation with chromatic wave refraction and Bayer 4x4 matrix ordered dither crossfading.
isPro: true
preview:
name: demo-c-fluid-crossfade-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-fluid-crossfade" />

<ComponentInstallation name="components-shader-fluid-crossfade" />

## Usage

```tsx
import { FluidCrossfade } from '@/components/spaceui/fluid-crossfade'
import { FluidCrossfade } from '@/components/shader/fluid-crossfade'

export default function Example() {
  return (
    <FluidCrossfade
      imageA="https://cdn.spaceui.one/atom/samples/image-1.png"
      imageB="https://cdn.spaceui.one/atom/samples/image-2.png"
      aspectRatio={16 / 9}
      ditherGrid={3.0}
    />
  )
}
```

## API Reference

| Prop                 | Type     | Default  | Description                                 |
| -------------------- | -------- | -------- | ------------------------------------------- |
| `imageA`             | `string` | —        | Initial default texture URL                 |
| `imageB`             | `string` | —        | Hover/transition texture URL                |
| `ditherGrid`         | `number` | `3.0`    | Scale of the Bayer 4x4 dithering pattern    |
| `pixelGridSize`      | `number` | `240`    | Resolution of pixel quantization            |
| `refractionStrength` | `number` | `0.85`   | Power of fluid wave refraction on the image |
| `aspectRatio`        | `number` | `16 / 9` | Aspect ratio of the canvas                  |


# Fluid Distortion Image
URL: https://www.spaceui.one/components/fluid-distortion-image

***

title: Fluid Distortion Image
description: An interactive WebGL image component with cover UV mapping and dynamic cursor fluid-distortion ripples using data textures.
preview:
name: demo-c-fluid-distortion-image-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-fluid-distortion-image" />

<ComponentInstallation name="components-shader-fluid-distortion-image" />

## Usage

```tsx
import { FluidDistortionImage } from '@/components/spaceui/fluid-distortion-image'
import { FluidDistortionImage } from '@/components/shader/fluid-distortion-image'

export default function Example() {
  return (
    <FluidDistortionImage
      src="/images/art.jpg"
      alt="Interactive fluid artwork"
      aspectRatio={16 / 10}
      distortionIntensity={0.04}
    />
  )
}
```

## API Reference

| Prop                  | Type     | Default                     | Description                                  |
| --------------------- | -------- | --------------------------- | -------------------------------------------- |
| `src`                 | `string` | —                           | Image source URL                             |
| `alt`                 | `string` | `'Distorted surface image'` | Accessible image label                       |
| `aspectRatio`         | `number` | `16 / 10`                   | Fixed aspect ratio with object-cover mapping |
| `distortionIntensity` | `number` | `0.03`                      | Strength of cursor ripple displacement       |
| `relaxationSpeed`     | `number` | `0.94`                      | Decay rate of fluid velocity (0 to 1)        |
| `radius`              | `number` | `0.18`                      | Radius of cursor impact area                 |


# Fluid Dither Crossfade
URL: https://www.spaceui.one/components/fluid-dither-crossfade

***

title: Fluid Dither Crossfade
description: A dual-pass WebGL shader component featuring real-time Navier-Stokes fluid pressure simulation and Bayer 4x4 matrix ordered dithering crossfade.
preview:
name: demo-c-fluid-dither-crossfade-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-fluid-dither-crossfade" />

<ComponentInstallation name="components-shader-fluid-dither-crossfade" />

## Usage

```tsx
import { FluidDitherCrossfade } from '@/components/spaceui/fluid-dither-crossfade'
import { FluidDitherCrossfade } from '@/components/shader/fluid-dither-crossfade'

export default function Example() {
  return (
    <FluidDitherCrossfade
      imageA="https://cdn.spaceui.one/atom/samples/image-0-f.png"
      imageB="https://cdn.spaceui.one/atom/samples/image-0-b.png"
      pixelRes={150}
      pixelEdgeRes={80}
      ditherGrid={20}
    />
  )
}
```

## API Reference

| Prop                 | Type      | Default                                                | Description                                      |
| -------------------- | --------- | ------------------------------------------------------ | ------------------------------------------------ |
| `imageA`             | `string`  | `'https://cdn.spaceui.one/atom/samples/image-0-f.png'` | Initial base texture URL                         |
| `imageB`             | `string`  | `'https://cdn.spaceui.one/atom/samples/image-0-b.png'` | Revealed target texture URL                      |
| `bgColor`            | `string`  | `'#0e0e0e'`                                            | Canvas background color                          |
| `pixelRes`           | `number`  | `150`                                                  | Pixelation resolution for revealed texture       |
| `pixelEdgeRes`       | `number`  | `80`                                                   | Chunky pixel resolution for fluid ink boundary   |
| `ditherGrid`         | `number`  | `20`                                                   | Bayer 4x4 matrix grid sampling size              |
| `ditherEnabled`      | `boolean` | `true`                                                 | Whether ordered dithering is active              |
| `brushSize`          | `number`  | `0.64`                                                 | Radius of cursor fluid wave & ink stroke         |
| `distortionStrength` | `number`  | `9.18`                                                 | Intensity of wave chromatic refraction           |
| `inkDissipation`     | `number`  | `0.926`                                                | Speed at which revealed ink mask fades back      |
| `edgeThreshold`      | `number`  | `0.08`                                                 | Ink density threshold required to reveal image B |


# Frost Blurred
URL: https://www.spaceui.one/components/frost-blurred

***

title: Frost Blurred
description: Stacked, masked backdrop-filter layers that frost content along an edge.
preview:
name: demo-c-frost-blurred-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-frost-blurred" />

## Usage

```tsx
import { FrostBlurred } from '@/components/spaceui/frost-blurred'

export default function Hero() {
  return (
    <FrostBlurred height="62%" side="bottom">
      <h1 className="text-8xl font-medium">UImaxxing</h1>
    </FrostBlurred>
  )
}
```

Without children, render it as an overlay on a relative parent:

```tsx
<div className="relative">
  <img src="/cover.jpg" alt="" />
  <FrostBlurred className="absolute inset-x-0 bottom-0" height="40%" />
</div>
```

## Props

| Prop       | Type                                     | Default    | Description                                       |
| ---------- | ---------------------------------------- | ---------- | ------------------------------------------------- |
| `layers`   | `number`                                 | `7`        | Stacked progressive blur layers.                  |
| `strength` | `number`                                 | `1`        | Multiplier on each layer's blur radius.           |
| `height`   | `string \| number`                       | `'62%'`    | Overlay height (or width if left/right).          |
| `side`     | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Edge the frost grows from.                        |
| `tint`     | `number`                                 | `0`        | Optional theme background mix (0 for pure glass). |
| `opacity`  | `number`                                 | `0.9`      | Layer opacity.                                    |
| `children` | `React.ReactNode`                        | —          | Content to frost. Omit to use as a pure overlay.  |


# GitHub Activity
URL: https://www.spaceui.one/components/github-activity

***

title: GitHub Activity
description: An interactive GitHub ecosystem showcase featuring pure 52-week contribution heatmap matrix content with live fetch for users and repositories.
preview:
name: demo-c-github-activity-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-github-activity" />

## Anatomy

```tsx
import { GitHubActivity } from '@/components/spaceui/github-activity'

export default function Example() {
  return <GitHubActivity user="https://github.com/usespaceui/ui" shape="rounded" />
}
```

## Features

### Repository Activity with Stats on Top

Layout demonstrating repository commit activity with KPI metric cards positioned above the graph.

<ComponentPreview name="demo-c-github-activity-02" contained={false} />

### User Activity with Stats at Bottom

Layout demonstrating user contribution activity with KPI metric cards positioned below the graph.

<ComponentPreview name="demo-c-github-activity-03" contained={false} />

## Props

### GitHubActivity

| Prop            | Type                                | Default           | Description                                                                                                                                          |
| --------------- | ----------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user`          | `string`                            | -                 | Target GitHub identifier: user handle (`'shadcn'`), profile URL, repository slug (`'facebook/react'`), or repo URL. Auto-detects user vs repository. |
| `repo`          | `string`                            | -                 | Explicit alias for `user` when targeting a repository (`'owner/repo'` or GitHub URL)                                                                 |
| `target`        | `string`                            | -                 | Unified alias for `user`                                                                                                                             |
| `username`      | `string`                            | -                 | Alias for `user` for backwards compatibility                                                                                                         |
| `shape`         | `'square' \| 'rounded' \| 'circle'` | `'rounded'`       | Corner geometry style for inner elements (no squircle)                                                                                               |
| `contributions` | `ContributionData`                  | -                 | 52-week contribution heatmap calendar data (skips live fetch if provided)                                                                            |
| `showHeader`    | `boolean`                           | `true`            | Toggles the top summary header                                                                                                                       |
| `showLegend`    | `boolean`                           | `true`            | Toggles the bottom color level legend                                                                                                                |
| `title`         | `string`                            | `'Contributions'` | Custom header title (displayed if no user/repo is given)                                                                                             |
| `subtitle`      | `string`                            | `'Past 52 weeks'` | Custom header subtitle (defaults to `'Repository commit activity'` for repos)                                                                        |


# Glass Button
URL: https://www.spaceui.one/components/glass-button

***

title: Glass Button
description: A glassmorphic extension of Button Squircle — backdrop blur, layered highlights and a hover shine sweep.
---------------------------------------------------------------------------------------------------------------------

## Icon

Icon-only glass buttons, sized for a toolbar or a social row.

<ComponentPreview name="demo-c-glass-button-icon-01" />

## Text

A pill CTA with an icon and a label.

<ComponentPreview name="demo-c-glass-button-text-01" />

## Blur Reveal

An icon button that widens and blur-reveals a text label on hover.

<ComponentPreview name="demo-c-glass-button-reveal-01" />

<ComponentInstallation name="components-spaceui-glass-button" />


# Gooey Experiments
URL: https://www.spaceui.one/components/gooey-experiments

***

title: Gooey Experiments
description: A gallery of drag-to-merge and hover-morph gooey micro-interactions built with SVG filters.
--------------------------------------------------------------------------------------------------------

## Gooey Tooltip

A tooltip bubble that follows the cursor and gooey-connects to its trigger button on hover.

<ComponentPreview name="demo-c-gooey-tooltip-01" />

<ComponentInstallation name="components-spaceui-gooey-tooltip" />

## Gooey Info Popover

A round trigger that morphs into an info panel on hover — pass any content as children.

<ComponentPreview name="demo-c-gooey-info-popover-01" />

<ComponentInstallation name="components-spaceui-gooey-info-popover" />

## Gooey Slots Tooltip

A round trigger that expands upward into a rich content card on hover.

<ComponentPreview name="demo-c-gooey-slots-tooltip-01" />

<ComponentInstallation name="components-spaceui-gooey-slots-tooltip" />

## Gooey Blobs

Two draggable blobs — drag them close together to see them merge into one liquid shape.

<ComponentPreview name="demo-c-gooey-blobs-01" />

<ComponentInstallation name="components-spaceui-gooey-blobs" />


# Gooey Text Reveal
URL: https://www.spaceui.one/components/gooey-text-reveal

***

title: Gooey Text Reveal
description: Line-by-line blur reveal with a gooey SVG edge filter, driven by GSAP SplitText — plays immediately, on scroll, or scrubbed to scroll position.
preview:
name: demo-c-gooey-text-reveal-01
contained: false
align: start
previewClassName: items-start
-----------------------------

## Installation

<ComponentInstallation name="components-spaceui-gooey-text-reveal" />


# Gradient File Upload
URL: https://www.spaceui.one/components/gradient-file-upload

***

title: Gradient File Upload
description: A refined upload surface with an animated glowing beam border, dynamic radial feedback, file extension badges, and multi-state progress indicators.
preview:
name: demo-c-gradient-file-upload-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-gradient-file-upload" />

## Usage

```tsx
import { GradientFileUpload } from '@/components/spaceui/gradient-file-upload'
```

```tsx
<GradientFileUpload
  variant="original"
  maxSizeMb={50}
  uploadDurationMs={2500}
  onFileAccepted={(file) => console.log('Selected:', file.name)}
/>
```

## API Reference

### GradientFileUpload Props

| Prop               | Type                           | Default      | Description                                                         |
| ------------------ | ------------------------------ | ------------ | ------------------------------------------------------------------- |
| `variant`          | `'original' \| 'glow'`         | `'original'` | Visual border animation engine (`original` conic shader or `glow`)  |
| `accept`           | `string`                       | `"*"`        | Accepted file types (e.g. `image/*,application/pdf`)                |
| `maxSizeMb`        | `number`                       | `50`         | Maximum file size in megabytes before rejecting                     |
| `uploadDurationMs` | `number`                       | `2400`       | Simulated upload duration in milliseconds                           |
| `onFileAccepted`   | `(file: File) => void`         | -            | Callback fired immediately when a valid file is dropped or selected |
| `onUpload`         | `(file: File) => Promise<...>` | -            | Custom async upload handler returning `{ status, message }`         |
| `className`        | `string`                       | -            | Additional class name applied to outer container                    |


# Gradient Background
URL: https://www.spaceui.one/components/gradient

***

title: Gradient Background
description: Creates a smoothly animating multi-color gradient background that shifts colors gently behind your page content.
preview: demo-c-backgrounds-gradient-01
---------------------------------------

## Installation

<ComponentInstallation name="components-backgrounds-gradient" />

## Usage

```tsx
<GradientBackground />
```

## API Reference

### GradientBackground

<TypeTable
  type={{
  transition: {
    description: 'The transition of the gradient',
    type: 'Transition',
    required: false,
    default: "{ duration: 15, ease: 'easeInOut', repeat: Infinity }",
  },
  '...props': {
    description: 'The props of the GradientBackground.',
    type: 'React.ComponentProps<"div">',
    required: false,
  },
}}
/>


# Handle Reel
URL: https://www.spaceui.one/components/handle-reel

***

title: Handle Reel
description: Kinetic tumbler reel that spins a vertical reel of names past a prefix, highlighting the centered handle as it decelerates and settles with momentum.
preview:
name: demo-c-handle-reel-01
contained: false
----------------

A slot-machine handle reel inspired by tactile momentum wheels. It spins past a fixed prefix (such as `ryna.me/`), highlights the landed name, and eases gracefully. Built with Motion.

## Installation

<ComponentInstallation name="components-spaceui-handle-reel" />

## Variants

### With custom reset button

<ComponentPreview name="demo-c-handle-reel-02" contained={false} />

## Usage

```tsx
import { HandleReel } from '@/components/spaceui/handle-reel'

export default function HeroSection() {
  return <HandleReel prefix="ryna.me/" finalName="ryna" loop highlightColor="#6366f1" />
}
```

## Props

| Prop             | Type        | Default                     | Description                                               |
| ---------------- | ----------- | --------------------------- | --------------------------------------------------------- |
| `prefix`         | `ReactNode` | `"ryna.me/"`                | Static prefix displayed before the rolling handles.       |
| `suffix`         | `ReactNode` | `undefined`                 | Optional suffix displayed after the rolling handles.      |
| `names`          | `string[]`  | Default names               | Array of candidate names or handles to cycle through.     |
| `finalName`      | `string`    | `"ryna"`                    | The final handle the reel lands on.                       |
| `rows`           | `number`    | `7`                         | Number of visible rows in the viewport.                   |
| `cycles`         | `number`    | `3`                         | Number of scroll cycles before settling.                  |
| `spinDuration`   | `number`    | `4`                         | Duration of the spin animation in seconds.                |
| `highlightColor` | `string`    | `"var(--primary, #6366f1)"` | Accent color pulsed when landed.                          |
| `loop`           | `boolean`   | `false`                     | Replay the reel automatically.                            |
| `loopDelay`      | `number`    | `2200`                      | Pause duration before replaying when `loop` is true.      |
| `trigger`        | `number`    | `0`                         | Increment to restart the roll programmatically.           |
| `onLand`         | `function`  | `undefined`                 | Callback fired when the reel settles on the final handle. |


# Heat Shade
URL: https://www.spaceui.one/components/heat-shade

***

title: Heat Shade
description: WebGPU heat field or climbing licks. Logo cyan on a navy ember.
preview: demo-c-heat-shade-01
defaultMode: split
------------------

## Installation

<ComponentInstallation name="components-shader-heat-shade" />

Depends on `vgpu`. WebGPU required.

## Files

| File                            | Role                           |
| ------------------------------- | ------------------------------ |
| `heat-shade/index.tsx`          | vgpu surface, clock, low-power |
| `heat-shade/heat-shade.wgsl.ts` | Field boundary                 |
| `heat-shade/heat-licks.wgsl.ts` | Climbing tongues               |

## Usage

```tsx
import { HeatShade } from '@/components/shader/heat-shade'

export default function SpaceUI() {
  return <HeatShade className="h-96 w-full" variant="licks" from="bottom" base="#2a7bba" hot="#43c8ff" speed={1} />
}
```

## Variants

### Field

Drifting boundary. Same colors, different silhouette.

<ComponentPreview name="demo-c-heat-shade-02" />

## API Reference

### HeatShade

| Prop        | Type                 | Default    | Description     |
| ----------- | -------------------- | ---------- | --------------- |
| `variant`   | `'field' \| 'licks'` | `'licks'`  | Silhouette      |
| `from`      | `'top' \| 'bottom'`  | `'bottom'` | Origin edge     |
| `base`      | `string`             | `#2a7bba`  | Navy (logo)     |
| `hot`       | `string`             | `#43c8ff`  | Cyan rim (logo) |
| `speed`     | `number`             | `1`        | Drift speed     |
| `className` | `string`             | —          | Canvas class    |


# Icon Stack
URL: https://www.spaceui.one/components/icon-stack

***

title: Icon Stack
description: Displays an overlapping cluster of icons or avatars that expands smoothly when hovered to reveal every individual item.
component: true
base: base
preview: demo-c-icon-stack-01
-----------------------------

## Installation

<ComponentInstallation name="components-spaceui-icon-stack" />

## Usage

```tsx
import { InboxIcon } from 'lucide-react'

import { IconStack } from '@/components/spaceui/icon-stack'
```

```tsx
<IconStack aria-hidden="true">
  <InboxIcon className="size-4" />
</IconStack>
```

`IconStack` is a shadcn-compatible Space UI primitive for building layered
isometric icons and compact isometric illustrations. Use it for empty states,
onboarding steps, feature cards, dashboard status panels, and small UI moments
that need more depth than a flat icon.

The main preview above shows the basic shadcn icon stack pattern: a layered SVG
stack with one centered icon. Style the inner icon or custom content directly
with its own `className`; the stack only provides the isometric artwork and
overlay position. Keep meaningful labels in surrounding copy and mark purely
decorative stacks with `aria-hidden="true"`.

## Examples

### Sizes

<ComponentPreview name="demo-c-icon-stack-02" />

### Colors

<ComponentPreview name="demo-c-icon-stack-03" />

### Icon Badge

<ComponentPreview name="demo-c-icon-stack-04" />

### Empty State Illustration

<ComponentPreview name="demo-c-icon-stack-05" className="**:[.preview]:h-auto" />

### Item Media

<ComponentPreview name="demo-c-icon-stack-06" />

## API Reference

### IconStack

| Prop        | Type              | Default | Description                                           |
| :---------- | :---------------- | :------ | :---------------------------------------------------- |
| `className` | `string`          | -       | Controls the outer wrapper size, color, and layout.   |
| `children`  | `React.ReactNode` | -       | Renders optional decorative content inside the stack. |

All native `div` props are supported.


# Image Dark
URL: https://www.spaceui.one/components/image-dark

***

title: Image Dark
description: An adaptive image component that dynamically switches between light and dark mode sources using standard HTML img elements with zero layout shift and no hydration mismatch.
preview: demo-c-image-dark-01
-----------------------------

## Installation

<ComponentInstallation name="components-spaceui-image-dark" />

## Usage

```tsx
import { ImageDark } from '@/components/spaceui/image-dark'
```

```tsx
<ImageDark src="/logo.svg" darkSrc="/logo-dark.svg" alt="Brand Logo" width={48} height={48} />
```

## API Reference

### ImageDark Props

`ImageDark` accepts all standard HTML `<img>` element attributes (`width`, `height`, `loading`, `decoding`, `alt`, `className`, etc.) along with the following:

| Prop        | Type     | Default      | Description                                                                               |
| ----------- | -------- | ------------ | ----------------------------------------------------------------------------------------- |
| `src`       | `string` | **Required** | The primary/light mode image source URL or path.                                          |
| `darkSrc`   | `string` | `undefined`  | The dark mode image source URL or path. Swapped automatically in dark theme.              |
| `alt`       | `string` | `""`         | Alternative text description for accessibility.                                           |
| `className` | `string` | `undefined`  | Additional classes merged onto both image elements (`dark:hidden` / `hidden dark:block`). |

***

### Card Integration

Use standard image sizing and container styling inside cards, hero banners, or device mockups.

<ComponentPreview name="demo-c-image-dark-02" />


# Components
URL: https://www.spaceui.one/components

***

title: Components
description: Composed Space UI components styled with Tailwind CSS.
-------------------------------------------------------------------


# Interactive Checklist
URL: https://www.spaceui.one/components/interactive-checklist

***

title: Interactive Checklist
description: Tactile checklist with spring checkmarks, animated strike-through lines, and completion progress.
preview: demo-c-interactive-checklist-01
----------------------------------------

## Installation

<ComponentInstallation name="components-spaceui-interactive-checklist" />

## Usage

```tsx
import { InteractiveChecklist } from '@/components/spaceui/interactive-checklist'

export default function Example() {
  return <InteractiveChecklist />
}
```

## Props

| Prop            | Type              | Default          | Description                       |
| --------------- | ----------------- | ---------------- | --------------------------------- |
| `initialItems`  | `ChecklistItem[]` | `DEFAULT_TASKS`  | Initial checklist tasks           |
| `title`         | `string`          | `'Sprint Tasks'` | Checklist title                   |
| `corner`        | `number`          | `24`             | Corner radius in px               |
| `onCompleteAll` | `() => void`      | `—`              | Triggered when all items are done |


# Interest Picker
URL: https://www.spaceui.one/components/interest-picker

***

title: Interest Picker
description: A draggable row-packed interest picker with an emoji burst on select and a shake-to-explode clear action.
preview:
name: demo-c-interest-picker-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-interest-picker" />


# Kanban
URL: https://www.spaceui.one/components/kanban

***

title: Kanban
description: Displays tasks across draggable columns, allowing users to organize projects, track progress stages, and reorder cards intuitively.
component: true
base: base
preview:
name: demo-c-kanban-01
align: start
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="components-spaceui-kanban" />

## Usage

```tsx
import {
  Kanban,
  KanbanBoard,
  KanbanColumn,
  KanbanColumnContent,
  KanbanColumnHandle,
  KanbanItem,
  KanbanItemHandle,
  KanbanOverlay,
} from '@/components/spaceui/kanban'
```

```tsx
<Kanban value={columns} onValueChange={setColumns} getItemValue={(item) => item.id}>
  <KanbanBoard>
    {Object.entries(columns).map(([id, items]) => (
      <KanbanColumn key={id} value={id}>
        <KanbanColumnHandle>
          <h3>{id}</h3>
        </KanbanColumnHandle>
        <KanbanColumnContent value={id}>
          {items.map((item) => (
            <KanbanItem key={item.id} value={item.id}>
              <KanbanItemHandle>{item.content}</KanbanItemHandle>
            </KanbanItem>
          ))}
        </KanbanColumnContent>
      </KanbanColumn>
    ))}
  </KanbanBoard>
  <KanbanOverlay>
    <div className="bg-muted size-full rounded-md" />
  </KanbanOverlay>
</Kanban>
```

## Examples

### Overlay

<ComponentPreview name="demo-c-kanban-02" className="**:[.preview]:h-auto" align="start" />

### Persist to a backend

<ComponentPreview name="demo-c-kanban-06" className="**:[.preview]:h-auto" align="start" />

## Persisting moves

Keep `value` and `onValueChange` so the board reshuffles live while dragging, and
use `onValueCommit` to save. It fires once per completed drag (never during the
hover preview) with the final board and a `previousValue` snapshot, so you can
update optimistically and roll back on error. Its `meta.kind` tells you whether a
card moved (`"item"`) or a column was reordered (`"column"`).

```tsx
const moveCard = api.board.moveCard.useMutation()
const reorderColumns = api.board.reorderColumns.useMutation()

<Kanban
  value={columns}
  onValueChange={setColumns}
  getItemValue={(task) => task.id}
  onValueCommit={(next, meta) => {
    if (meta.kind === "column") {
      reorderColumns.mutate({ order: Object.keys(next) })
      return
    }
    moveCard.mutate(
      {
        id: String(meta.event.active.id),
        to: meta.overContainer,
        index: meta.overIndex,
      },
      {
        onError: () => {
          setColumns(meta.previousValue) // roll back
          toast.error("Could not move the card. Your board was restored.")
        },
      },
    )
  }}
>
  {/* ... */}
</Kanban>
```

If a user might start another drag before the mutation settles, prefer a refetch
in `onError` instead of restoring the snapshot, so a newer arrangement is not
clobbered.

If you do not need the live cross-column preview, `onMove` is a simpler
alternative: it fires once on drop for item moves and lets you apply the move
yourself. Column reorders still arrive through `onValueChange`.

## API Reference

### Kanban

The root component that provides the kanban context and manages the items state.

| Prop              | Type                                                              | Default | Description                                                                                                                                                                        |
| :---------------- | :---------------------------------------------------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`           | `Record<string, T[]>`                                             | -       | `Required`. The current state of columns and their items.                                                                                                                          |
| `onValueChange`   | `(value: Record<string, T[]>) => void`                            | -       | `Required`. Fired when items move within or between columns. In the default mode it also fires during the drag to render the live preview, so avoid persisting from here directly. |
| `getItemValue`    | `(item: T) => string`                                             | -       | `Required`. Function to get a unique identifier for an item.                                                                                                                       |
| `onValueCommit`   | `(value: Record<string, T[]>, meta: KanbanCommitMeta<T>) => void` | -       | Fired once per completed drag with the final board and a `previousValue` snapshot. Use it to persist moves to a backend. See [Persisting moves](#persisting-moves).                |
| `onMove`          | `(event: KanbanMoveEvent) => void`                                | -       | Opt-in single commit point for item moves. When set, the live preview is disabled and you apply the move yourself.                                                                 |
| `restoreOnCancel` | `boolean`                                                         | `false` | When `true`, cancelling a drag (for example pressing Escape) restores the board to its pre-drag arrangement.                                                                       |
| `onDragStart`     | `(event: DragStartEvent) => void`                                 | -       | Raw dnd-kit passthrough, fired when a drag starts.                                                                                                                                 |
| `onDragEnd`       | `(event: DragEndEvent) => void`                                   | -       | Raw dnd-kit passthrough, fired after internal cleanup and before the final `onValueChange`/`onMove` call. In the default mode, `onValueChange` has already fired during dragOver.  |
| `onDragCancel`    | `(event: DragCancelEvent) => void`                                | -       | Raw dnd-kit passthrough, fired when a drag is cancelled.                                                                                                                           |
| `accessibility`   | `DndContextProps["accessibility"]`                                | -       | dnd-kit accessibility options (announcements and screen reader instructions).                                                                                                      |
| `modifiers`       | `Modifiers`                                                       | -       | dnd-kit modifiers applied to the drag.                                                                                                                                             |
| `className`       | `string`                                                          | -       | Additional CSS classes for the container.                                                                                                                                          |

`KanbanCommitMeta<T>` is `{ kind: "item" | "column"; event: DragEndEvent; activeContainer: string; activeIndex: number; overContainer: string; overIndex: number; previousValue: Record<string, T[]> }`.

***

### KanbanBoard

The horizontal container for kanban columns.

| Prop        | Type     | Default | Description                           |
| :---------- | :------- | :------ | :------------------------------------ |
| `className` | `string` | -       | Additional CSS classes for the board. |

***

### KanbanColumn

An individual column within the kanban board.

| Prop        | Type     | Default | Description                                       |
| :---------- | :------- | :------ | :------------------------------------------------ |
| `value`     | `string` | -       | `Required`. The unique identifier for the column. |
| `className` | `string` | -       | Additional CSS classes for the column.            |

***

### KanbanColumnHandle

The drag handle for a column (if columns are sortable).

| Prop        | Type     | Default | Description                            |
| :---------- | :------- | :------ | :------------------------------------- |
| `className` | `string` | -       | Additional CSS classes for the handle. |

***

### KanbanColumnContent

The scrollable area within a column that holds the items.

| Prop        | Type     | Default | Description                                                       |
| :---------- | :------- | :------ | :---------------------------------------------------------------- |
| `value`     | `string` | -       | `Required`. The identifier of the column this content belongs to. |
| `className` | `string` | -       | Additional CSS classes for the content area.                      |

***

### KanbanItem

An individual draggable item within a column.

| Prop        | Type      | Default | Description                                     |
| :---------- | :-------- | :------ | :---------------------------------------------- |
| `value`     | `string`  | -       | `Required`. The unique identifier for the item. |
| `disabled`  | `boolean` | `false` | Whether the item is draggable.                  |
| `className` | `string`  | -       | Additional CSS classes for the item.            |

***

### KanbanItemHandle

The drag handle for an individual item.

| Prop        | Type     | Default | Description                            |
| :---------- | :------- | :------ | :------------------------------------- |
| `className` | `string` | -       | Additional CSS classes for the handle. |

***

### KanbanOverlay

The ghost element displayed during a drag operation.

| Prop        | Type     | Default | Description                             |
| :---------- | :------- | :------ | :-------------------------------------- |
| `className` | `string` | -       | Additional CSS classes for the overlay. |

## All 6 variations

### Kanban board with frame columns

<ComponentPreview name="demo-c-kanban-03" />

### Minimal kanban with stacked frame

<ComponentPreview name="demo-c-kanban-04" />

### Feature roadmap kanban with progress

<ComponentPreview name="demo-c-kanban-05" />


# Like Button
URL: https://www.spaceui.one/components/like-button

***

title: Like Button
description: A like button with burst particles, a ripple ring, a spring-animated heart, and a smooth NumberFlow count transition.
preview:
name: demo-c-like-button-01
---------------------------

## Installation

<ComponentInstallation name="components-spaceui-like-button" />


# Liquid Mask Crossfade
URL: https://www.spaceui.one/components/liquid-mask-crossfade

***

title: Liquid Mask Crossfade
description: A WebGL shader component featuring interactive liquid cursor mask crossfade with dynamic trail, refraction, and parallax effects.
preview:
name: demo-c-liquid-mask-crossfade-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-shader-liquid-mask-crossfade" />

## Usage

```tsx
import { LiquidMaskCrossfade } from '@/components/shader/liquid-mask-crossfade'

export default function Example() {
  return (
    <LiquidMaskCrossfade
      imageA="https://cdn.spaceui.one/atom/samples/image-0-f.png"
      imageB="https://cdn.spaceui.one/atom/samples/image-0-b.png"
      radius={0.15}
      distortion={0.18}
      refraction={0.14}
    />
  )
}
```

## API Reference

| Prop               | Type     | Default     | Description                                   |
| ------------------ | -------- | ----------- | --------------------------------------------- |
| `imageA`           | `string` | `-`         | Outer base texture URL                        |
| `imageB`           | `string` | `-`         | Inner revealed texture URL                    |
| `radius`           | `number` | `0.15`      | Base radius of the liquid cursor droplet      |
| `distortion`       | `number` | `0.18`      | Liquid noise distortion intensity             |
| `noiseScale`       | `number` | `5.7`       | Scale of the FBM procedural noise             |
| `speed`            | `number` | `0.1`       | Animation speed of procedural liquid noise    |
| `edgeSoftness`     | `number` | `0.06`      | Softness and blur width of the mask boundary  |
| `refraction`       | `number` | `0.14`      | Strength of the chromatic refraction effect   |
| `parallax`         | `number` | `0.05`      | Depth parallax movement of the inner image    |
| `mouseSmoothness`  | `number` | `0.06`      | Cursor lerp smoothing factor                  |
| `trailLength`      | `number` | `1.08`      | Length spacing of the cursor droplet trail    |
| `trailPersistence` | `number` | `0.65`      | Persistence and drag memory of the trail      |
| `trailTaper`       | `number` | `0.86`      | Taper ratio from cursor head to trail tail    |
| `idleDelay`        | `number` | `2.0`       | Seconds of inactivity before fade out begins  |
| `fadeDuration`     | `number` | `0.35`      | Fade-in duration when pointer enters or moves |
| `fadeOutDuration`  | `number` | `0.7`       | Fade-out duration when cursor goes idle       |
| `aspectRatio`      | `number` | `undefined` | Optional aspect ratio override                |
| `className`        | `string` | `undefined` | Additional Tailwind CSS classes               |


# Liquid Mesh Blur
URL: https://www.spaceui.one/components/liquid-mesh-blur

***

title: Liquid Mesh Blur
description: Organic liquid mesh gradient shader background blending orbiting particle clusters through a high-radius Gaussian blur diffusion filter.
preview: demo-c-liquid-mesh-blur-01
defaultMode: split
isPro: true
-----------

## Installation

<ComponentInstallation name="components-shader-liquid-mesh-blur" />

## Usage

```tsx
import { LiquidMeshBlur } from '@/components/shader/liquid-mesh-blur'

export default function SpaceUI() {
  return (
    <div className="relative h-96 w-full overflow-hidden rounded-2xl">
      <LiquidMeshBlur blur={60} speed={1} particleCount={70} interactive={true} />
    </div>
  )
}
```

## Examples

### Top Ambient Glow

<ComponentPreview name="demo-c-liquid-mesh-blur-02" />

## API Reference

| Prop                 | Type                  | Default                                                              | Description                                          |
| -------------------- | --------------------- | -------------------------------------------------------------------- | ---------------------------------------------------- |
| `colors`             | `string[]`            | `['#7C5CFC', '#0EA5E9', '#FF6F59', '#B8EE3A', '#E040FB', '#06B6D4']` | Array of hex color strings for fluid clusters        |
| `color1` .. `color6` | `string`              | —                                                                    | Direct overrides for individual cluster colors       |
| `blur`               | `number`              | `60`                                                                 | Gaussian blur diffusion radius in pixels             |
| `speed`              | `number`              | `1`                                                                  | Orbit & drift velocity multiplier                    |
| `particleCount`      | `number`              | `70`                                                                 | Total number of animated fluid particles             |
| `minSize`            | `number`              | `130`                                                                | Minimum particle radius in pixels                    |
| `maxSize`            | `number`              | `230`                                                                | Maximum particle radius in pixels                    |
| `contrast`           | `number`              | `1.1`                                                                | Color contrast multiplier applied with blur filter   |
| `interactive`        | `boolean`             | `true`                                                               | Enables pointer tracking attraction & repulsion      |
| `className`          | `string`              | —                                                                    | Optional container CSS class name                    |
| `style`              | `React.CSSProperties` | —                                                                    | Inline styles for wrapper container                  |
| `children`           | `React.ReactNode`     | —                                                                    | Content overlaid cleanly on top of the liquid canvas |


# Liquid Metal Border
URL: https://www.spaceui.one/components/liquid-metal-border

***

title: Liquid Metal Border
description: Liquid metal shader as a border wrap. Put any registry component inside.
preview:
name: demo-c-liquid-metal-border-01
className: mb-4
---------------

## Installation

<ComponentInstallation name="components-spaceui-liquid-metal-border" />

## Usage

```tsx
import { LiquidBorder } from '@/components/spaceui/liquid-metal-border'
import { Avatar } from '@/components/ui/avatar'
import { AvatarFallback } from '@/components/spaceui/avatar-extended'

;<LiquidBorder className="inline-flex size-14 rounded-full p-0.75">
  <Avatar className="size-full">
    <AvatarFallback name="space" variant="pebble" />
  </Avatar>
</LiquidBorder>
```

`rounded-*` and `p-0.75` on `LiquidBorder` are the metal ring.

## Variants

### Button

<ComponentPreview name="demo-c-liquid-metal-border-02" className="mb-4" />

### Card

<ComponentPreview name="demo-c-liquid-metal-border-03" className="mb-4" />

### Presets

<ComponentPreview name="demo-c-liquid-metal-border-04" className="mb-4" />

## Props

| Prop                | Type                                                                 | Default    | Description                                    |
| ------------------- | -------------------------------------------------------------------- | ---------- | ---------------------------------------------- |
| `children`          | `node`                                                               | —          | Any registry component                         |
| `preset`            | `'chrome' \| 'gold' \| 'ocean' \| 'sunset' \| 'emerald' \| 'violet'` | `'chrome'` | Built-in metal tint and fallback palette       |
| `colorBack`         | `string`                                                             | —          | Custom base metal color (overrides preset)     |
| `colorTint`         | `string`                                                             | —          | Custom highlight tint color (overrides preset) |
| `fallbackClassName` | `string`                                                             | —          | CSS linear gradient classes for fallback layer |
| `innerClassName`    | `string`                                                             | —          | Class names for the relative content wrapper   |
| `speed`             | `number`                                                             | `0.6`      | Animation speed                                |
| `repetition`        | `number`                                                             | `4`        | Pattern repeats                                |
| `softness`          | `number`                                                             | `0.5`      | Highlight softness                             |
| `shiftRed`          | `number`                                                             | `0.3`      | Red shift                                      |
| `shiftBlue`         | `number`                                                             | `0.3`      | Blue shift                                     |
| `distortion`        | `number`                                                             | `0`        | Distortion                                     |
| `contour`           | `number`                                                             | `0`        | Contour                                        |
| `angle`             | `number`                                                             | `45`       | Pattern angle                                  |
| `scale`             | `number`                                                             | `8`        | Pattern scale                                  |
| `offsetX`           | `number`                                                             | `0.1`      | X offset                                       |
| `offsetY`           | `number`                                                             | `-0.1`     | Y offset                                       |


# Liquid Sortable List
URL: https://www.spaceui.one/components/liquid-sortable-list

***

title: Liquid Sortable List
description: Smooth drag-and-drop sortable team list with generative avatars and spring reordering.
preview: demo-c-liquid-sortable-list-01
---------------------------------------

## Installation

<ComponentInstallation name="components-spaceui-liquid-sortable-list" />

## Usage

```tsx
import { LiquidSortableList } from '@/components/spaceui/liquid-sortable-list'

export default function Example() {
  return <LiquidSortableList />
}
```

## Props

| Prop            | Type                                | Default              | Description                  |
| --------------- | ----------------------------------- | -------------------- | ---------------------------- |
| `items`         | `SortableMember[]`                  | `DEFAULT_MEMBERS`    | Items with avatars and roles |
| `onOrderChange` | `(items: SortableMember[]) => void` | `—`                  | Callback when order changes  |
| `title`         | `string`                            | `'Reorder Priority'` | Header title                 |
| `corner`        | `number`                            | `20`                 | Card corner radius           |


# Liquid Switch
URL: https://www.spaceui.one/components/liquid-switch

***

title: Liquid Switch
description: Elastic toggle switch with velocity-based organic stretch and spring return physics.
preview: demo-c-liquid-switch-01
--------------------------------

## Installation

<ComponentInstallation name="components-spaceui-liquid-switch" />

## Usage

```tsx
import { LiquidSwitch } from '@/components/spaceui/liquid-switch'

export default function Example() {
  return <LiquidSwitch />
}
```

## Props

| Prop              | Type                         | Default | Description                       |
| ----------------- | ---------------------------- | ------- | --------------------------------- |
| `checked`         | `boolean`                    | `—`     | Controlled checked state          |
| `defaultChecked`  | `boolean`                    | `false` | Default checked state             |
| `onCheckedChange` | `(checked: boolean) => void` | `—`     | Toggle change callback            |
| `stretch`         | `number`                     | `36`    | Dynamic elongation factor (0-100) |
| `label`           | `string`                     | `—`     | Optional companion label          |
| `disabled`        | `boolean`                    | `false` | Disabled interaction              |


# Loading Orb
URL: https://www.spaceui.one/components/loading

***

title: Loading Orb
description: Matrix pixel grid loader with Tailwind color support, spring motion presets, and assistant status cards.
preview: demo-c-orb-loading-01
------------------------------

## Installation

<ComponentInstallation name="components-orb-loading" />

## Usage

```tsx
import { LoadingOrb, BuildingLoader } from '@/components/orb/loading'

export default function App() {
  return (
    <div className="flex flex-col items-center gap-6">
      {/* Standard loader cycling states with Tailwind color */}
      <LoadingOrb className="text-primary" size={56} />

      {/* Specific pattern locked */}
      <LoadingOrb pattern="diamond" className="text-emerald-500" size={48} />

      {/* Companion assistant status card */}
      <BuildingLoader state="Building" detail="Composing response from context" className="text-foreground" />
    </div>
  )
}
```

## Features

### All States Overview

All 6 geometric matrix patterns (`diamond`, `corners`, `bands`, `scatter`, `diagonal`, `glyph`) displayed simultaneously on a single line:

<ComponentPreview name="demo-c-orb-loading-02" />

### Tailwind Colors

Style with standard Tailwind text or background utilities (`text-primary`, `text-emerald-500`, `text-indigo-500`, etc.). Tonal depth is automatically calculated across opacities:

<ComponentPreview name="demo-c-orb-loading-03" />

### Assistant Status Banner

Agentic workflow status card with reactive states and real-time shimmer progress:

<ComponentPreview name="demo-c-orb-loading-04" />

## API Reference

### LoadingOrb

| Prop           | Type                                                                                | Default        | Description                                                                   |
| -------------- | ----------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------- |
| `size`         | `number`                                                                            | `56`           | Pixel size of the 4x4 matrix container                                        |
| `speed`        | `number`                                                                            | `750`          | Interval in milliseconds between pattern steps                                |
| `pattern`      | `'diamond' \| 'corners' \| 'bands' \| 'scatter' \| 'diagonal' \| 'glyph' \| number` | `undefined`    | Specific pattern to display, or omitted to auto-cycle                         |
| `motionPreset` | `'morph' \| 'fade' \| 'scale' \| 'blur' \| 'flip'`                                  | `'morph'`      | Spring animation curve applied on cell transitions                            |
| `className`    | `string`                                                                            | —              | Tailwind classes (e.g. `text-foreground`, `text-primary`, `text-emerald-500`) |
| `dotClassName` | `string`                                                                            | `'bg-current'` | Custom Tailwind utility applied to every cell                                 |
| `radius`       | `number`                                                                            | `3`            | Border radius in pixels for each matrix dot                                   |
| `gap`          | `number`                                                                            | `3`            | Spacing between dots in pixels                                                |
| `showGhost`    | `boolean`                                                                           | `false`        | When true, renders inactive dots with subtle ghost opacity                    |

### BuildingLoader

| Prop          | Type                                                                                | Default                             | Description                                                    |
| ------------- | ----------------------------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------- |
| `state`       | `string`                                                                            | `'Building'`                        | Primary state label (e.g. "Building", "Thinking", "Searching") |
| `detail`      | `string`                                                                            | `'Composing response from context'` | Secondary explanatory caption                                  |
| `showShimmer` | `boolean`                                                                           | `true`                              | Whether to display the bottom shimmer progress bar             |
| `size`        | `number`                                                                            | `38`                                | Size of the embedded `LoadingOrb`                              |
| `pattern`     | `'diamond' \| 'corners' \| 'bands' \| 'scatter' \| 'diagonal' \| 'glyph' \| number` | `undefined`                         | Specific pattern for the embedded orb                          |
| `className`   | `string`                                                                            | —                                   | Classes for the container card                                 |


# Member Selector
URL: https://www.spaceui.one/components/member-selector

***

title: Member Selector
description: An interactive participant and member avatar selector with dynamic row layout, animated selection badges, quick-add button, and searchable popover.
preview:
name: demo-c-member-selector-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-member-selector" />

## Usage

```tsx
import { MemberSelector } from '@/components/spaceui/member-selector'
```

```tsx
const [selected, setSelected] = useState(['1', '2'])

<MemberSelector
  members={members}
  selected={selected}
  onChange={setSelected}
  maxVisible={5}
  label="Participants"
/>
```

## API Reference

### MemberSelector Props

| Prop         | Type                           | Default      | Description                                                   |
| ------------ | ------------------------------ | ------------ | ------------------------------------------------------------- |
| `members`    | `Member[]`                     | **required** | List of available members (`id`, `name`, `email?`, `avatar?`) |
| `selected`   | `string[]`                     | **required** | Array of currently selected member IDs                        |
| `onChange`   | `(selected: string[]) => void` | **required** | Callback when selection changes                               |
| `max`        | `number`                       | -            | Optional maximum number of selectable members                 |
| `maxVisible` | `number`                       | `5`          | Maximum number of avatars displayed in horizontal row         |
| `label`      | `string`                       | -            | Optional header label (e.g. "Participants")                   |
| `className`  | `string`                       | -            | Additional class names applied to the container               |


# Mesh Gradient
URL: https://www.spaceui.one/components/mesh-gradient

***

title: Mesh Gradient
description: Dynamic WebGL mesh gradient shader background featuring fluid swirls, configurable color stops, distortion turbulence, and film grain overlay.
preview: demo-c-mesh-gradient-01
defaultMode: split
------------------

## Installation

<ComponentInstallation name="components-shader-mesh-gradient" />

Depends on `@paper-design/shaders-react`. WebGL required.

## Usage

```tsx
import { MeshGradient } from '@/components/shader/mesh-gradient'

export default function SpaceUI() {
  return (
    <div className="relative h-96 w-full overflow-hidden rounded-2xl">
      <MeshGradient
        colors={['#085b96', '#51a0f6', '#cfe5f2']}
        speed={1}
        distortion={1}
        swirl={0.57}
        rotation={120}
        grain={true}
      />
    </div>
  )
}
```

## API Reference

| Prop              | Type                           | Default                             | Description                               |
| ----------------- | ------------------------------ | ----------------------------------- | ----------------------------------------- |
| `colors`          | `string[]`                     | `['#085b96', '#51a0f6', '#cfe5f2']` | Array of color stops for the gradient     |
| `speed`           | `number`                       | `1`                                 | Time progression multiplier for animation |
| `distortion`      | `number`                       | `1`                                 | Turbulence wave amplitude                 |
| `swirl`           | `number`                       | `0.57`                              | Rotational vortex intensity               |
| `swirlIterations` | `number`                       | `7.4`                               | Depth of swirl fractal iterations         |
| `softness`        | `number`                       | `1`                                 | Blur and color blend smoothness           |
| `proportion`      | `number`                       | `0`                                 | Center color distribution bias            |
| `shape`           | `'edge' \| 'wave' \| 'circle'` | `'edge'`                            | Primary gradient geometry type            |
| `shapeScale`      | `number`                       | `0.59`                              | Geometric scale factor                    |
| `scale`           | `number`                       | `1.45`                              | Global mesh magnification                 |
| `rotation`        | `number`                       | `120`                               | Initial angular orientation in degrees    |
| `grain`           | `boolean`                      | `true`                              | Organic film grain overlay texture        |
| `className`       | `string`                       | —                                   | Wrapper CSS class name                    |
| `style`           | `React.CSSProperties`          | —                                   | Inline style object                       |


# Morph Icon
URL: https://www.spaceui.one/components/morph-icon

***

title: Morph Icon
description: Transforms one vector icon smoothly into another with fluid shape morphing animations when state changes.
preview: demo-c-morph-icon-01
-----------------------------

## Installation

<ComponentInstallation name="components-spaceui-morph-icon" />

## Usage

```tsx
import { MorphIcon } from '@/components/spaceui/morph-icon'
import { IconSun, IconMoon } from '@tabler/icons-react'
```

```tsx
<Button onClick={toggleTheme} size="icon" variant="ghost">
  <MorphIcon activeKey={isDark ? 'dark' : 'light'} variant="blur-scale">
    {isDark ? <IconMoon className="size-5" /> : <IconSun className="size-5" />}
  </MorphIcon>
</Button>
```

## API Reference

### MorphIcon Props

| Prop        | Type                                                   | Default        | Description                                                             |
| ----------- | ------------------------------------------------------ | -------------- | ----------------------------------------------------------------------- |
| `activeKey` | `React.Key`                                            | **Required**   | Unique key identifying current active icon/state to trigger transitions |
| `children`  | `React.ReactNode`                                      | **Required**   | The icon element to render                                              |
| `variant`   | `"blur-scale" \| "rotate-scale" \| "flip" \| "spring"` | `"blur-scale"` | Motion transition preset style                                          |
| `duration`  | `number`                                               | `0.22`         | Transition duration in seconds                                          |
| `className` | `string`                                               | `undefined`    | Additional classes applied to the motion wrapper                        |

***

### Theme Switcher Transition

Smooth morphing between sun, moon, and system desktop icons.

<ComponentPreview name="demo-c-morph-icon-02" />

### Action & Status Toggles

Common UI action buttons (like/heart, volume/mute, play/pause, upvote) with instant morphing transitions.

<ComponentPreview name="demo-c-morph-icon-03" />

### Animation Presets

Side-by-side comparison of all 4 motion presets: `blur-scale`, `rotate-scale`, `flip`, and `spring`.

<ComponentPreview name="demo-c-morph-icon-04" />

### Multi-State Status Indicator

Morphing through multi-stage state transitions (pending, loading, success, error).

<ComponentPreview name="demo-c-morph-icon-05" />

### Accordion & Visibility Toggles

Password reveal and accordion expand/collapse transitions using `MorphIcon`.

<ComponentPreview name="demo-c-morph-icon-06" />

## Examples

<ShowcaseGrid>
  <ShowcaseCard name="demo-c-morph-icon-02" description="Theme switcher transition" />

  <ShowcaseCard name="demo-c-morph-icon-03" description="Action and status toggles" />

  <ShowcaseCard name="demo-c-morph-icon-04" description="Animation presets showcase" />

  <ShowcaseCard name="demo-c-morph-icon-05" description="Multi-state status indicator" />

  <ShowcaseCard name="demo-c-morph-icon-06" description="Accordion and visibility toggles" />
</ShowcaseGrid>


# Morphing Area
URL: https://www.spaceui.one/components/morphing-area

***

title: Morphing Area
description: Adaptive aspect ratio surface with constant-area morphing for any child element, card, or media.
preview: demo-c-morphing-area-01
--------------------------------

## Installation

<ComponentInstallation name="components-spaceui-morphing-area" />

## Usage

```tsx
import { MorphingArea } from '@/components/spaceui/morphing-area'

export default function Example() {
  return (
    <MorphingArea ratio="4:3" rounded={8} squircle={false}>
      <img src="/your-image.jpg" alt="" className="size-full object-cover" />
    </MorphingArea>
  )
}
```

You can pass any content as `children`, including custom UI cards, gradients, or media:

```tsx
<MorphingArea ratio="1:1" rounded={12} squircle>
  <div className="size-full bg-gradient-to-br from-indigo-500 to-purple-600 p-6 flex flex-col justify-between text-white">
    <h3>Dynamic Card</h3>
    <p>Morphs smoothly across aspect ratios.</p>
  </div>
</MorphingArea>
```

## Props

| Prop        | Type                                                                | Default | Description                                                       |
| ----------- | ------------------------------------------------------------------- | ------- | ----------------------------------------------------------------- |
| `children`  | `React.ReactNode`                                                   | `—`     | Child elements (images, cards, media) to morph.                   |
| `ratio`     | `'4:3' \| '1:1' \| '3:4' \| '16:9' \| 'land' \| 'square' \| 'tall'` | `'1:1'` | Target aspect ratio for constant-area surface morphing.           |
| `width`     | `string \| number`                                                  | `—`     | Optional explicit width override.                                 |
| `height`    | `string \| number`                                                  | `—`     | Optional explicit height override.                                |
| `rounded`   | `number`                                                            | `8`     | Corner radius in pixels (min 0).                                  |
| `squircle`  | `boolean`                                                           | `false` | Enables continuous squircle curvature via `@usespaceui/squircle`. |
| `morph`     | `number`                                                            | `50`    | Morph transition spring duration modifier (0–100).                |
| `className` | `string`                                                            | `—`     | Additional class names.                                           |


# Morphing Command Bar
URL: https://www.spaceui.one/components/morphing-command-bar

***

title: Morphing Command Bar
description: Elastic command bar that expands seamlessly from passive state to active input with action trigger.
preview: demo-c-morphing-command-bar-01
---------------------------------------

## Installation

<ComponentInstallation name="components-spaceui-morphing-command-bar" />

## Usage

```tsx
import { MorphingCommandBar } from '@/components/spaceui/morphing-command-bar'

export default function Example() {
  return <MorphingCommandBar />
}
```

## Props

| Prop          | Type                      | Default                                   | Description            |
| ------------- | ------------------------- | ----------------------------------------- | ---------------------- |
| `placeholder` | `string`                  | `'Search components, actions or docs...'` | Input placeholder text |
| `onSubmit`    | `(query: string) => void` | `—`                                       | Submit callback        |
| `corner`      | `number`                  | `28`                                      | Corner radius in px    |


# Morphing Search Pill
URL: https://www.spaceui.one/components/morphing-search-pill

***

title: Morphing Search Pill
description: Adaptive search pill that expands smoothly from a compact button into a full input field.
preview: demo-c-morphing-search-pill-01
---------------------------------------

## Installation

<ComponentInstallation name="components-spaceui-morphing-search-pill" />

## Usage

```tsx
import { MorphingSearchPill } from '@/components/spaceui/morphing-search-pill'

export default function Example() {
  return <MorphingSearchPill />
}
```

## Props

| Prop             | Type                      | Default             | Description                |
| ---------------- | ------------------------- | ------------------- | -------------------------- |
| `placeholder`    | `string`                  | `'Quick search...'` | Search field placeholder   |
| `onSearch`       | `(query: string) => void` | `—`                 | Search query callback      |
| `collapsedWidth` | `number`                  | `64`                | Width when collapsed in px |
| `expandedWidth`  | `number`                  | `280`               | Width when expanded in px  |
| `corner`         | `number`                  | `20`                | Pill corner radius         |


# Morphing Text
URL: https://www.spaceui.one/components/morphing-text

***

title: Morphing Text
description: Seamless character-level FLIP morphing animation between words or phrases with pause-on-hover capability.
preview:
name: demo-c-morphing-text-01
contained: false
----------------

A fluid character-morphing typography component that rearranges matching letters into their next positions using shared layout IDs and blur transitions.

## Installation

<ComponentInstallation name="components-spaceui-morphing-text" />

## Examples

### Full Phrases & Sentences

Morph seamlessly across full multi-word sentences and headlines with fluid character travel.

<ComponentPreview name="demo-c-morphing-text-02" contained={false} />

## Usage

```tsx
import { MorphingText } from '@/components/spaceui/morphing-text'

const words = ['Morphing', 'Motion', 'Animation', 'Dimension', 'Precision']

export default function RotatingHeadline() {
  return (
    <MorphingText
      texts={words}
      interval={2400}
      pauseOnHover
      blurAmount="10px"
      className="text-4xl font-bold tracking-tight"
    />
  )
}
```

## Props

### MorphingText

| Prop            | Type                          | Default      | Description                                                                                               |
| --------------- | ----------------------------- | ------------ | --------------------------------------------------------------------------------------------------------- |
| `texts`         | `string[]`                    | **required** | The list of words or phrases to cycle through sequentially.                                               |
| `interval`      | `number`                      | `2400`       | Time in milliseconds before advancing to the next phrase.                                                 |
| `pauseOnHover`  | `boolean`                     | `true`       | When true, pauses timer when cursor is hovered over the text.                                             |
| `blurAmount`    | `string`                      | `'10px'`     | Blur radius applied to entering and exiting characters.                                                   |
| `springBounce`  | `number`                      | `0.14`       | Spring bounce factor (0 to 1) for layout transitions.                                                     |
| `className`     | `string`                      | `undefined`  | Custom styling for the wrapper container.                                                                 |
| `textClassName` | `string`                      | `undefined`  | Custom styling for the text component.                                                                    |
| `renderChar`    | `(char: string) => ReactNode` | `undefined`  | Overrides how each character token renders — e.g. through Textmoji so emoji stay styled across the morph. |

### TextMorph (Single Morph)

You can also use `<TextMorph />` directly for fine-grained control when morphing between custom state values:

```tsx
import { TextMorph } from '@/components/spaceui/morphing-text'

export function DynamicStatus({ status }: { status: string }) {
  return <TextMorph className="text-xl font-medium">{status}</TextMorph>
}
```


# Notification List
URL: https://www.spaceui.one/components/notification-list

***

title: Notification List
description: Displays an interactive feed of incoming notifications with unread indicators, timestamps, and swipe-to-dismiss actions.
author:
name: arhamkhnz
url: [https://github.com/arhamkhnz](https://github.com/arhamkhnz)
preview: demo-c-notification-list-01
------------------------------------

## Installation

<ComponentInstallation name="components-spaceui-notification-list" />

## Usage

```tsx
<NotificationList />
```

## Credits

* Credits to [Alexander Avdeev](https://x.com/privetavdey) for [this X post](https://x.com/privetavdey/status/1932774726889586780) as inspiration


# Paper Shader
URL: https://www.spaceui.one/components/paper-shader

***

title: Paper Shader
description: Paper Shaders WebGL2 canvas. Pass a fragment shader and uniforms; the mount compiles, resizes, and ticks time.
preview: demo-c-paper-shader-01
defaultMode: split
------------------

The canvas is `registry/components/shader/paper-shader/index.tsx` (default export `PaperShader`). The demo fragment lives in `demo/components/shader/paper-shader/c-paper-shader-1/shader-source.tsx`.

## Installation

<ComponentInstallation name="components-shader-paper-shader" />

## Usage

```tsx
import PaperShader from '@/components/shader/paper-shader'

export default function SpaceUI() {
  return (
    <PaperShader
      fragmentShader={shader}
      uniforms={{
        u_colorBack: [0.1, 0.1, 0.1, 1],
        u_colorTint: [1, 1, 1, 1],
        u_contour: 0.5,
        u_distortion: 0.1,
        u_softness: 0.05,
        u_speed: 1,
      }}
      speed={1}
      webGlContextAttributes={{ alpha: true, antialias: true }}
    />
  )
}
```

## Files

| File                                 | Role                                     |
| ------------------------------------ | ---------------------------------------- |
| `paper-shader/index.tsx`             | WebGL2 mount, compile, uniforms, dispose |
| `c-paper-shader-1/index.tsx`         | Demo wrapper                             |
| `c-paper-shader-1/shader-source.tsx` | Example GLSL 300 es fragment             |

## API Reference

| Prop                     | Type                      | Default      | Description                                       |
| ------------------------ | ------------------------- | ------------ | ------------------------------------------------- |
| `fragmentShader`         | `string`                  | **required** | GLSL 300 es fragment source                       |
| `uniforms`               | `Record<string, unknown>` | `{}`         | Values uploaded each frame (`u_time` is injected) |
| `speed`                  | `number`                  | `0`          | Time multiplier                                   |
| `webGlContextAttributes` | `WebGLContextAttributes`  | —            | Context flags                                     |
| `minPixelRatio`          | `number`                  | —            | DPR floor                                         |
| `maxPixelCount`          | `number`                  | —            | Pixel cap for large canvases                      |
| `style`                  | `CSSProperties`           | —            | Outer div style                                   |

The parent must be positioned; the canvas is `absolute inset-0`.


# Phone Input
URL: https://www.spaceui.one/components/phone-input

***

title: Phone Input
description: Allows users to enter international phone numbers with automatic country flag detection, dial codes, and formatted digits.
component: true
base: base
links:
api: [https://gitlab.com/catamphetamine/react-phone-number-input](https://gitlab.com/catamphetamine/react-phone-number-input)
preview:
name: demo-c-phone-input-01
className: '\[&*.preview>\*]:w-full \[&*.preview>\*]:max-w-xs'
--------------------------------------------------------------

We used the [react-phone-number-input](https://gitlab.com/catamphetamine/react-phone-number-input) library to create this component.

## Installation

<ComponentInstallation name="components-spaceui-phone-input" />

## Usage

```tsx
import { PhoneInput } from '@/components/spaceui/phone-input'
```

```tsx
<PhoneInput placeholder="Enter phone number" defaultCountry="US" value={value} onChange={setValue} />
```

## Examples

### Size

<ComponentPreview name="demo-c-phone-input-02" className="[&_.preview>*]:w-full [&_.preview>*]:max-w-xs" />

## API Reference

### PhoneInput

The main component for entering phone numbers with country selection.

| Prop             | Type                        | Default     | Description                                                |
| :--------------- | :-------------------------- | :---------- | :--------------------------------------------------------- |
| `value`          | `string`                    | -           | The current phone number value in E.164 format.            |
| `onChange`       | `(value: string) => void`   | -           | Callback fired when the value changes.                     |
| `variant`        | `"sm" \| "default" \| "lg"` | `"default"` | The vertical size of the input and country selector.       |
| `popupClassName` | `string`                    | -           | Additional CSS classes for the country selection dropdown. |
| `defaultCountry` | `Country`                   | -           | The default country selected if no value is provided.      |
| `placeholder`    | `string`                    | -           | Placeholder text for the phone number input.               |
| `className`      | `string`                    | -           | Additional CSS classes for the root container.             |
| `disabled`       | `boolean`                   | `false`     | Whether the input and country selector are disabled.       |

***

### Utilities

The component re-exports essential phone number utilities:

```tsx
import {
  PhoneInput,
  isValidPhoneNumber,
  formatPhoneNumber,
  formatPhoneNumberIntl,
  isPossiblePhoneNumber,
  getCountryCallingCode,
} from '@/components/spaceui/phone-input'
```

* **`isValidPhoneNumber(value)`**: Checks if the phone number is valid according to international metadata.
* **`formatPhoneNumber(value)`**: Formats the phone number in national format.
* **`formatPhoneNumberIntl(value)`**: Formats the phone number in international format (e.g. `+1 213 373 4253`).
* **`isPossiblePhoneNumber(value)`**: Quick length check to see if the number could be possible.
* **`getCountryCallingCode(country)`**: Returns the calling code for a given ISO country code (e.g. `'FR'` -> `'33'`).

***

### External Props

This component also accepts all props from the [react-phone-number-input](https://gitlab.com/catamphetamine/react-phone-number-input#props) library.

## Examples

### Large phone input

<ComponentPreview name="demo-c-phone-input-03" />

### Disabled phone input

<ComponentPreview name="demo-c-phone-input-04" />

### Phone input with preset value

<ComponentPreview name="demo-c-phone-input-05" />

### Phone input with error state

<ComponentPreview name="demo-c-phone-input-06" />

### Phone input with specific default country

<ComponentPreview name="demo-c-phone-input-07" />

### Read-only phone input

<ComponentPreview name="demo-c-phone-input-08" />

### Real-time validation

<ComponentPreview name="demo-c-phone-input-09" />

### With Field, Label and Description

<ComponentPreview name="demo-c-phone-input-10" />


# Pin List
URL: https://www.spaceui.one/components/pin-list

***

title: Pin List
description: Provides a quick-access bar where users can pin, organize, and reorder favorite items, documents, or shortcuts.
author:
name: arhamkhnz
url: [https://github.com/arhamkhnz](https://github.com/arhamkhnz)
preview: demo-c-pin-list-01
---------------------------

## Installation

<ComponentInstallation name="components-spaceui-pin-list" />

## Usage

```tsx
<PinList items={ITEMS} />
```

## API Reference

### PinList

<TypeTable
  type={{
  items: {
    description: 'Array of items to show in the list. Each item should have id, name, info, icon, and pinned.',
    type: 'PinListItem[]',
    required: true,
  },
  labels: {
    description:
      'Custom labels for the pinned and unpinned sections. Example: { pinned: "Favorites", unpinned: "All" }.',
    type: '{ pinned?: string; unpinned?: string; }',
    required: false,
    default: '{ pinned: "Pinned Items", unpinned: "All Items" }',
  },
  transition: {
    description:
      'Spring animation config for item transitions. Controls the movement physics. Example: { stiffness: 320, damping: 20, mass: 0.8, type: "spring" }',
    type: '{ stiffness?: number; damping?: number; mass?: number; type?: string; }',
    required: false,
    default: '{ stiffness: 320, damping: 20, mass: 0.8, type: "spring" }',
  },
  labelMotionProps: {
    description:
      'Motion props for the section labels. Allows customizing the label enter/exit animation. Example: { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: { duration: 0.22, ease: "easeInOut" } }',
    type: '{ initial?: object; animate?: object; exit?: object; transition?: object; }',
    required: false,
    default:
      '{ initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: { duration: 0.22, ease: "easeInOut" } }',
  },
  className: {
    description: 'Class name for the outermost container.',
    type: 'string',
    required: false,
  },
  labelClassName: {
    description: 'Class name for the section labels.',
    type: 'string',
    required: false,
  },
  pinnedSectionClassName: {
    description: 'Class name for the pinned items group.',
    type: 'string',
    required: false,
  },
  unpinnedSectionClassName: {
    description: 'Class name for the unpinned items group.',
    type: 'string',
    required: false,
  },
  zIndexResetDelay: {
    description:
      'Delay (in ms) before resetting z-index after toggle, should match your animation duration if changed.',
    type: 'number',
    required: false,
    default: '500',
  },
}}
/>

## Credits

* Credits to [Nitish Khagwal](https://x.com/nitishkmrk) for [this X post](https://x.com/nitishkmrk/status/1933050634594660800) as inspiration


# Pixel Fill Button
URL: https://www.spaceui.one/components/pixel-fill-button

***

title: Pixel Fill Button
description: An interactive button whose background fills with square matrix pixels radiating from the cursor entry point on hover.
preview:
name: demo-c-pixel-fill-button-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-pixel-fill-button" />

## Usage

```tsx
import { PixelFillButton } from '@/components/spaceui/pixel-fill-button'

export default function Example() {
  return (
    <div className="flex gap-4">
      {/* Classic */}
      <PixelFillButton pixelColor="#ffe9a8">Classic Button</PixelFillButton>

      {/* Silk Border */}
      <PixelFillButton borderEffect="silk" silkPreset="twilight" pixelColor="#ec4899">
        Silk Edition
      </PixelFillButton>

      {/* Metal Border */}
      <PixelFillButton borderEffect="metal" metalPreset="chrome" pixelColor="#ffffff">
        Metal Edition
      </PixelFillButton>
    </div>
  )
}
```

## API Reference

| Prop               | Type                                       | Default      | Description                                                   |
| ------------------ | ------------------------------------------ | ------------ | ------------------------------------------------------------- |
| `children`         | `ReactNode`                                | —            | Button label / icons                                          |
| `borderEffect`     | `'default' \| 'silk' \| 'metal' \| 'none'` | `'default'`  | Active border styling wrapper (Silk shader or Liquid Metal)   |
| `silkPreset`       | `SilkPreset`                               | `'twilight'` | Preset palette for the Silk Border ('aurora', 'sunset', etc.) |
| `metalPreset`      | `LiquidPreset`                             | `'chrome'`   | Preset finish for the Metal Border ('gold', 'violet', etc.)   |
| `pixelColor`       | `string`                                   | `'#ffe9a8'`  | Color of the expanding matrix pixels                          |
| `textColorOnHover` | `string`                                   | `'#000000'`  | Color applied to the text when pixel-filled                   |
| `pixelSize`        | `number`                                   | `4`          | Size in pixels of each square grain                           |
| `blurAmount`       | `string`                                   | `'8px'`      | Text transition blur amount                                   |
| `squircle`         | `boolean`                                  | `true`       | Smooth squircle curvature styling                             |
| `href`             | `string`                                   | —            | Optional URL (renders an `<a>` tag when provided)             |
| `borderClassName`  | `string`                                   | —            | Custom class names for the outer border container             |
| `className`        | `string`                                   | —            | Custom class names for the button element                     |


# Pixel Reveal Image
URL: https://www.spaceui.one/components/pixel-reveal-image

***

title: Pixel Reveal Image
description: A WebGL image component with dynamic pixel matrix wave and customizable neon accent border on scroll.
preview:
name: demo-c-pixel-reveal-image-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-shader-pixel-reveal-image" />

## Usage

```tsx
import { PixelRevealImage } from '@/components/shader/pixel-reveal-image'

export default function Example() {
  return <PixelRevealImage src="/images/showcase.jpg" alt="Creative portrait" accentColor="#ffe9a8" gridDensity={40} />
}
```

## API Reference

| Prop             | Type                                 | Default                 | Description                                                |
| ---------------- | ------------------------------------ | ----------------------- | ---------------------------------------------------------- |
| `src`            | `string`                             | —                       | Path or URL to the source image                            |
| `alt`            | `string`                             | `'Pixel reveal visual'` | Accessible image label                                     |
| `accentColor`    | `string`                             | `'#ffe9a8'`             | Accent color for transition edge pixels (Aurum by default) |
| `gridDensity`    | `number`                             | `40`                    | Number of pixel blocks across the matrix grid              |
| `bandWidth`      | `number`                             | `3.5`                   | Thickness of the glowing pixel transition wave             |
| `noiseIntensity` | `number`                             | `0.16`                  | Procedural jitter noise dispersion                         |
| `direction`      | `'top-to-bottom' \| 'bottom-to-top'` | `'bottom-to-top'`       | Wavefront sweep direction                                  |
| `progress`       | `number`                             | —                       | Optional controlled progress value (0 to 1)                |
| `aspectRatio`    | `number`                             | `3 / 4`                 | Aspect ratio of the canvas container                       |


# Pixel Reveal Text
URL: https://www.spaceui.one/components/pixel-reveal-text

***

title: Pixel Reveal Text
description: A typography shader component that materializes text out of pixel matrix noise with neon contour highlights on scroll.
preview:
name: demo-c-pixel-reveal-text-01
contained: false
----------------

## Animoji Phrases

The same loop effect cycling through a rotating set of phrases, in top of the Animoji component.

<ComponentPreview name="demo-c-pixel-reveal-text-02" contained={false} />

## Installation

<ComponentInstallation name="components-spaceui-pixel-reveal-text" />

## Usage

```tsx
import { PixelRevealText } from '@/components/spaceui/pixel-reveal-text'

export default function Example() {
  return <PixelRevealText text="Every detail, perfected." fontSize={44} pixelSize={4} edgeColor="#ffe9a8" />
}
```

## API Reference

| Prop            | Type               | Default     | Description                                                |
| --------------- | ------------------ | ----------- | ---------------------------------------------------------- |
| `text`          | `string`           | —           | Text content to reveal                                     |
| `fontSize`      | `number`           | `44`        | Font size in pixels                                        |
| `fontFamily`    | `string`           | `'inherit'` | CSS font family                                            |
| `fontWeight`    | `string \| number` | `600`       | Font weight                                                |
| `color`         | `string`           | —           | Base text color (inherits from theme if omitted)           |
| `edgeColor`     | `string`           | `'#ffe9a8'` | Accent color of the advancing wavefront (Aurum by default) |
| `pixelSize`     | `number`           | `4`         | Resolution of pixel blocks                                 |
| `noiseStrength` | `number`           | `0.35`      | Degree of matrix randomness during reveal                  |
| `progress`      | `number`           | —           | Optional controlled reveal progress (0 to 1)               |


# Rainbow Glow Border
URL: https://www.spaceui.one/components/rainbow-glow-border

***

title: Rainbow Glow Border
description: Smooth animated rainbow glow border wrap with drifting color orbs. Put any registry component inside.
isPro: true
preview:
name: demo-c-rainbow-glow-border-01
className: mb-4
---------------

## Installation

<ComponentInstallation name="components-spaceui-rainbow-glow-border" />

## Usage

```tsx
import { RainbowGlowBorder } from '@/components/spaceui/rainbow-glow-border'
import { Avatar } from '@/components/ui/avatar'
import { AvatarFallback } from '@/components/spaceui/avatar-extended'

;<RainbowGlowBorder className="inline-flex size-14 rounded-full p-0.75">
  <Avatar className="size-full">
    <AvatarFallback name="rainbow" variant="lumina" />
  </Avatar>
</RainbowGlowBorder>
```

`rounded-*` and `p-0.75` on `RainbowGlowBorder` control the glow ring shape and thickness.

## Variants

### Button

<ComponentPreview name="demo-c-rainbow-glow-border-02" className="mb-4" />

### Card

<ComponentPreview name="demo-c-rainbow-glow-border-03" className="mb-4" />

### Presets

<ComponentPreview name="demo-c-rainbow-glow-border-04" className="mb-4" />

## Props

| Prop             | Type                                                                 | Default     | Description                                                    |
| ---------------- | -------------------------------------------------------------------- | ----------- | -------------------------------------------------------------- |
| `children`       | `React.ReactNode`                                                    | —           | Any registry component                                         |
| `preset`         | `'rainbow' \| 'aurora' \| 'sunset' \| 'neon' \| 'cyber' \| 'chrome'` | `'rainbow'` | Built-in animated palette presets                              |
| `orbs`           | `OrbConfig[]`                                                        | —           | Custom array of orb colors and trajectories (overrides preset) |
| `innerClassName` | `string`                                                             | —           | Class names for the relative content wrapper                   |
| `blur`           | `number`                                                             | `6`         | Gaussian blur radius applied to drifting orbs in pixels        |
| `duration`       | `number`                                                             | `3`         | Loop duration in seconds for each cycle                        |


# Rainbow Glow Button
URL: https://www.spaceui.one/components/rainbow-glow-button

***

title: Rainbow Glow Button
description: An interactive dark pill button featuring 6 orbiting colorful blurred orbs and a blur reveal transition on hover.
preview:
name: demo-c-rainbow-glow-button-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-rainbow-glow-button" />

## Usage

```tsx
import { RainbowGlowButton } from '@/components/spaceui/rainbow-glow-button'
```

```tsx
export default function Example() {
  return (
    <RainbowGlowButton as="a" href="https://spaceui.one/pricing" target="_blank">
      Get pro
    </RainbowGlowButton>
  )
}
```

## API Reference

### RainbowGlowButton Props

| Prop        | Type              | Default        | Description                                                 |
| ----------- | ----------------- | -------------- | ----------------------------------------------------------- |
| `as`        | `'button' \| 'a'` | `'button'`     | Render as a button or an anchor link.                       |
| `href`      | `string`          | —              | Target link URL when `as="a"`.                              |
| `orbs`      | `OrbConfig[]`     | `DEFAULT_ORBS` | Custom array of orb colors and coordinate motion keyframes. |
| `className` | `string`          | —              | Additional CSS class names.                                 |
| `children`  | `React.ReactNode` | —              | Content displayed within the button label.                  |


# Rating
URL: https://www.spaceui.one/components/rating

***

title: Rating
description: Allows users to submit ratings or view average customer scores using interactive star icons with half-star precision.
component: true
base: base
preview: demo-c-rating-01
-------------------------

## Installation

<ComponentInstallation name="components-spaceui-rating" />

## Usage

```tsx
import { Rating } from '@/components/spaceui/rating'
```

```tsx
<Rating rating={4.5} showValue editable />
```

## Examples

### Decimal

<ComponentPreview name="demo-c-rating-02" />

### Show Value

<ComponentPreview name="demo-c-rating-03" />

### Editable

<ComponentPreview name="demo-c-rating-04" />

### Size

<ComponentPreview name="demo-c-rating-05" />

## API Reference

### Rating

The main component for displaying and editing star ratings.

| Prop             | Type                        | Default | Description                                                                        |
| :--------------- | :-------------------------- | :------ | :--------------------------------------------------------------------------------- |
| `rating`         | `number`                    | -       | **Required**. The current rating value. Supports decimal values for partial stars. |
| `maxRating`      | `number`                    | `5`     | Total number of stars to display.                                                  |
| `size`           | `"sm" \| "default" \| "lg"` | `"md"`  | The size of the stars and spacing.                                                 |
| `showValue`      | `boolean`                   | `false` | Whether to show the numeric rating value next to the stars.                        |
| `editable`       | `boolean`                   | `false` | Whether the rating can be changed by clicking on stars.                            |
| `onRatingChange` | `(rating: number) => void`  | -       | Callback fired when a star is clicked (if `editable` is true).                     |
| `starClassName`  | `string`                    | -       | Additional CSS classes for the numeric value container.                            |
| `className`      | `string`                    | -       | Additional CSS classes for the root container.                                     |

## All 9 variations

### Rating with review summary

<ComponentPreview name="demo-c-rating-06" />

### Interactive half-star rating

<ComponentPreview name="demo-c-rating-07" />

### Emoji reaction rating

<ComponentPreview name="demo-c-rating-08" />

### Rating with review text input

<ComponentPreview name="demo-c-rating-09" />


# Resizable
URL: https://www.spaceui.one/components/resizable

***

title: 'Resizable'
description: Allows users to adjust side-by-side workspace panels by dragging divider handles to fit their screen needs.
preview: demo-c-resizable-01
----------------------------

## Installation

<ComponentInstallation name="components-spaceui-resizable" />

# Examples

## Horizontal resizable layout

<ComponentPreview name="demo-c-resizable-01" />

## Vertical resizable layout.

<ComponentPreview name="demo-c-resizable-02" />

## Nested mixed-direction resizable layout.

<ComponentPreview name="demo-c-resizable-03" />

## Nested resizable

<ComponentPreview name="demo-c-resizable-04" />

## Handle with animated pill indicator

<ComponentPreview name="demo-c-resizable-05" />

## Handle pill with spring scale on drag

<ComponentPreview name="demo-c-resizable-06" />

## Handle with large capsule expansion on drag

<ComponentPreview name="demo-c-resizable-07" />

## Nested layout with animated pill handles

<ComponentPreview name="demo-c-resizable-08" />

## Three-panel layout with animated pill handles

<ComponentPreview name="demo-c-resizable-09" />

## State-tracked resizable layout.

<ComponentPreview name="demo-c-resizable-10" />


# Scatter Text
URL: https://www.spaceui.one/components/scatter-text

***

title: Scatter Text
description: A text input whose content scatters into drifting canvas grains on submit.
preview:
name: demo-c-scatter-text-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-scatter-text" />

## Usage

```tsx
import { ScatterText } from '@/components/spaceui/scatter-text'

export default function SpaceUI() {
  return <ScatterText placeholder="adriel@spaceui.one" onSubmit={(value) => console.log(value)} />
}
```

## Files

| File                     | Role                                       |
| ------------------------ | ------------------------------------------ |
| `scatter-text/index.tsx` | Canvas rasterizing, scatter loop, the form |

## API Reference

| Prop             | Type                                         | Default | Description                               |
| ---------------- | -------------------------------------------- | ------- | ----------------------------------------- |
| `placeholder`    | `string`                                     | —       | Empty-state hint                          |
| `value`          | `string`                                     | —       | Controlled value                          |
| `defaultValue`   | `string`                                     | `''`    | Initial value when uncontrolled           |
| `onChange`       | `(e: ChangeEvent<HTMLInputElement>) => void` | —       | Fires on every keystroke                  |
| `onSubmit`       | `(value: string) => void`                    | —       | Fires once the scatter animation finishes |
| `className`      | `string`                                     | —       | Outer form wrapper                        |
| `inputClassName` | `string`                                     | —       | The `<input>` element                     |

Submit either by pressing Enter or clicking the trailing button. Grain color is sampled from the input's own computed text color, so it follows light/dark theme automatically.


# Scroll Manifesto
URL: https://www.spaceui.one/components/scroll-manifesto

***

title: Scroll Manifesto
description: A pinned statement that comes into focus word by word as you scroll. Each word rises, sharpens from a blur and lights up in reading order.
isPro: true
preview:
name: demo-c-scroll-manifesto-01
contained: false
align: start
previewClassName: items-start
-----------------------------

## Installation

<ComponentInstallation name="components-spaceui-scroll-manifesto" />

## Usage

```tsx
import { ScrollManifesto } from '@/components/spaceui/scroll-manifesto'

export default function Mission() {
  return (
    <ScrollManifesto
      text="Ship the product only you can build. We made the rest move, sound and feel right."
      highlight={['only you']}
    />
  )
}
```

The statement stays pinned while the reader scrolls through `scrollLength` viewport heights, then lets the page continue. It pins inside the nearest scrolling ancestor (a preview pane, a modal) or the window, and shows the text fully revealed when the reader prefers reduced motion.


# Scroll Text Reveal
URL: https://www.spaceui.one/components/scroll-text-reveal

***

title: Scroll Text Reveal
description: Progressive character-by-character and word-by-word text reveal driven by scroll progress.
preview:
name: demo-c-scroll-text-reveal-01
contained: false
align: start
previewClassName: items-start
-----------------------------

## Installation

<ComponentInstallation name="components-spaceui-scroll-text-reveal" />


# Scrollspy
URL: https://www.spaceui.one/components/scrollspy

***

title: Scrollspy
description: Tracks the user’s scroll position on the page and automatically highlights the corresponding link in the table of contents.
component: true
base: base
preview:
name: demo-c-scrollspy-01
align: start
className: '\[&\_.preview>\[data-orientation=vertical]]:sm:max-w-\[80%] \*\*:\[.preview]:min-h-\[580px]'
--------------------------------------------------------------------------------------------------------

## Installation

<ComponentInstallation name="components-spaceui-scrollspy" />

## Usage

```tsx
import { Scrollspy } from '@/components/spaceui/scrollspy'
```

```tsx
<Scrollspy targetRef={containerRef}>
  <a href="#section-1" data-scrollspy-anchor="section-1">Section 1</a>
  <a href="#section-2" data-scrollspy-anchor="section-2">Section 2</a>
</Scrollspy>

<div ref={containerRef}>
  <div id="section-1">Content 1</div>
  <div id="section-2">Content 2</div>
</div>
```

## Examples

### Horizontal

<ComponentPreview name="demo-c-scrollspy-02" className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[530px]" align="start" />

## API Reference

### Scrollspy

The main component that wraps the navigation links and manages the scroll spying logic.

| Prop            | Type                                 | Default       | Description                                                        |
| :-------------- | :----------------------------------- | :------------ | :----------------------------------------------------------------- |
| `targetRef`     | `RefObject<HTMLElement \| Document>` | `window`      | The scrollable container to monitor.                               |
| `onUpdate`      | `(id: string) => void`               | -             | Callback fired when the active section changes.                    |
| `offset`        | `number`                             | `0`           | Global pixel offset from the top when calculating active sections. |
| `smooth`        | `boolean`                            | `true`        | Whether to use smooth scrolling when clicking on anchors.          |
| `history`       | `boolean`                            | `true`        | Whether to update the URL hash when the active section changes.    |
| `dataAttribute` | `string`                             | `"scrollspy"` | The prefix for data attributes (e.g., `data-scrollspy-anchor`).    |
| `className`     | `string`                             | -             | Additional CSS classes for the wrapper.                            |

***

### Data Attributes

Navigation links within `Scrollspy` should use these attributes to connect to sections:

| Attribute               | Description                                                     |
| :---------------------- | :-------------------------------------------------------------- |
| `data-scrollspy-anchor` | **Required**. The ID of the target section (without the `#`).   |
| `data-scrollspy-offset` | Optional. Overrides the global `offset` for this specific link. |

The component adds `data-active="true"` to the link element when its corresponding section is active.


# Section Scrollspy
URL: https://www.spaceui.one/components/section-scrollspy

***

title: Section Scrollspy
description: Floating section scrollbar that tracks the active heading as you scroll.
preview:
name: demo-c-section-scrollspy-01
contained: false
----------------

Mark each block with `data-page-section` and an `h2`. The bar reads the heading (and an optional badge) then follows scroll.

## Installation

<ComponentInstallation name="components-spaceui-section-scrollspy" />

## Usage

```tsx
import * as React from 'react'
import { SectionScrollspy } from '@/components/spaceui/section-scrollspy'

export default function SpaceUI() {
  const scrollRef = React.useRef<HTMLDivElement>(null)

  return (
    <div ref={scrollRef} className="relative h-[420px] overflow-y-auto">
      <section data-page-section>
        <h2>Installation</h2>
      </section>
      <SectionScrollspy containerRef={scrollRef} />
    </div>
  )
}
```

Pass `portal` to pin it to the viewport. Omit `containerRef` to track `window` scroll.

## API Reference

| Prop           | Type                     | Default               | Description                    |
| -------------- | ------------------------ | --------------------- | ------------------------------ |
| `containerRef` | `RefObject<HTMLElement>` | —                     | Scroll root. Window if omitted |
| `selector`     | `string`                 | `[data-page-section]` | Section query                  |
| `portal`       | `boolean`                | `false`               | Render into `document.body`    |
| `className`    | `string`                 | —                     | Root class                     |


# Silk Border
URL: https://www.spaceui.one/components/silk-border

***

title: Silk Border
description: Fluid WebGPU silk mesh gradient wrapper. Wrap avatars, badges, buttons, and cards with theme presets and CSS fallback.
preview:
name: demo-c-silk-border-01
className: mb-4
---------------

## Installation

<ComponentInstallation name="components-spaceui-silk-border" />

## Usage

```tsx
import { SilkBorder } from '@/components/spaceui/silk-border'
import { Avatar } from '@/components/ui/avatar'
import { AvatarFallback } from '@/components/spaceui/avatar-extended'

;<SilkBorder preset="ember" className="inline-flex size-14 rounded-full p-0.75">
  <Avatar className="size-full">
    <AvatarFallback name="space" variant="pebble" />
  </Avatar>
</SilkBorder>
```

`rounded-*` and `p-0.75` on `SilkBorder` form the silk outline ring with an automatic CSS gradient fallback if WebGPU is unsupported.

## Variants

### Button & Badge

<ComponentPreview name="demo-c-silk-border-02" className="mb-4" />

### Card

<ComponentPreview name="demo-c-silk-border-03" className="mb-4" />

### Presets

<ComponentPreview name="demo-c-silk-border-04" className="mb-4" />

## Props

| Prop                | Type                                                                                           | Default   | Description                                    |
| ------------------- | ---------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------- |
| `children`          | `React.ReactNode`                                                                              | —         | Any component wrapped inside the border        |
| `preset`            | `'aurora' \| 'ember' \| 'twilight' \| 'ocean' \| 'sunset' \| 'emerald' \| 'amber' \| 'violet'` | `'ember'` | Built-in silk color and fallback palette       |
| `color1`            | `string`                                                                                       | —         | Custom primary hex color                       |
| `color2`            | `string`                                                                                       | —         | Custom secondary hex color                     |
| `color3`            | `string`                                                                                       | —         | Custom tertiary hex color                      |
| `speed`             | `number`                                                                                       | `0.65`    | Animation speed multiplier                     |
| `animate`           | `boolean`                                                                                      | `true`    | Whether the silk mesh flows smoothly           |
| `grain`             | `boolean`                                                                                      | `false`   | Film grain texture overlay                     |
| `fallbackClassName` | `string`                                                                                       | —         | CSS linear gradient classes for fallback layer |
| `innerClassName`    | `string`                                                                                       | —         | Class names for the relative content wrapper   |


# Silk Flare
URL: https://www.spaceui.one/components/silk-flare

***

title: Silk Flare
description: WebGPU single-pass composite shader fusing silky mesh warp gradients and rising thermodynamic heat flares.
preview: demo-c-silk-flare-01
defaultMode: split
------------------

## Installation

<ComponentInstallation name="components-shader-silk-flare" />

Depends on `vgpu`. WebGPU required.

## Usage

```tsx
import { SilkFlare } from '@/components/shader/silk-flare'

export default function SpaceUI() {
  return (
    <SilkFlare
      className="h-96 w-full"
      color1="#7c3aed"
      color2="#6366f1"
      color3="#a855f7"
      hotColor="#38bdf8"
      heatOpacity={0.5}
      from="bottom"
      speed={0.8}
      animate
      grain
    />
  )
}
```

## API Reference

| Prop          | Type                | Default            | Description                                        |
| ------------- | ------------------- | ------------------ | -------------------------------------------------- |
| `color1`      | `string`            | required           | First silk mesh base color                         |
| `color2`      | `string`            | required           | Mid warp mesh color                                |
| `color3`      | `string`            | required           | Dark silk blend color                              |
| `hotColor`    | `string`            | `color3`           | Peak flame/flare heat color                        |
| `heatOpacity` | `number`            | `0.5`              | Intensity/opacity of the thermodynamic flare layer |
| `from`        | `'bottom' \| 'top'` | `'bottom'`         | Direction of rising heat licks                     |
| `speed`       | `number`            | `0.8`              | Animation velocity                                 |
| `animate`     | `boolean`           | `true`             | Play / pause animation                             |
| `grain`       | `boolean`           | `true`             | Film grain overlay                                 |
| `dpr`         | `number`            | `devicePixelRatio` | Target device pixel ratio cap                      |
| `className`   | `string`            | —                  | Canvas class name                                  |


# Silk Gradient
URL: https://www.spaceui.one/components/silk-gradient

***

title: Silk Gradient
description: WebGPU silk mesh. Three colors, warp, grain. Animation on by default.
preview: demo-c-silk-gradient-01
defaultMode: split
------------------

## Installation

<ComponentInstallation name="components-shader-silk-gradient" />

Depends on `vgpu`. WebGPU required.

## Usage

```tsx
import { SilkGradient } from '@/components/shader/silk-gradient'

export default function SpaceUI() {
  return <SilkGradient className="h-96 w-full" color1="#4c9bff" color2="#1f4fd8" color3="#0a1a4a" animate grain />
}
```

## API Reference

| Prop        | Type      | Default  | Description     |
| ----------- | --------- | -------- | --------------- |
| `color1`    | `string`  | required | Light silk      |
| `color2`    | `string`  | required | Mid warp        |
| `color3`    | `string`  | required | Dark blend      |
| `speed`     | `number`  | `1`      | Animation speed |
| `animate`   | `boolean` | `true`   | Play / pause    |
| `grain`     | `boolean` | `true`   | Film grain      |
| `className` | `string`  | —        | Canvas class    |


# Slide To Confirm
URL: https://www.spaceui.one/components/slide-to-confirm

***

title: Slide To Confirm
description: Tactile slide-to-confirm action slider with inertia spring physics.
preview: demo-c-slide-to-confirm-01
-----------------------------------

## Installation

<ComponentInstallation name="components-spaceui-slide-to-confirm" />

## Usage

```tsx
import { SlideToConfirm } from '@/components/spaceui/slide-to-confirm'

export default function Example() {
  return <SlideToConfirm />
}
```

## Props

| Prop             | Type         | Default              | Description                  |
| ---------------- | ------------ | -------------------- | ---------------------------- |
| `label`          | `string`     | `'Slide to confirm'` | Track placeholder label      |
| `confirmedLabel` | `string`     | `'Confirmed'`        | Confirmed state label        |
| `onConfirm`      | `() => void` | `—`                  | Callback on successful slide |
| `resetDelay`     | `number`     | `2400`               | Auto reset duration in ms    |
| `width`          | `number`     | `320`                | Track width in px            |
| `speed`          | `number`     | `50`                 | Spring return speed (0-100)  |
| `corner`         | `number`     | `28`                 | Corner border radius         |
| `disabled`       | `boolean`    | `false`              | Disabled state               |


# Slosh Slider
URL: https://www.spaceui.one/components/slosh-slider

***

title: Slosh Slider
description: Liquid fill slider. Corner, viscosity, momentum, tilt.
preview: demo-c-slosh-slider-01
-------------------------------

## Installation

<ComponentInstallation name="components-spaceui-slosh-slider" />

## Usage

```tsx
import { SloshSlider } from '@/components/spaceui/slosh-slider'

export default function Example() {
  const [value, setValue] = React.useState(42)
  return <SloshSlider value={value} onValueChange={setValue} corner={13} viscosity={15} momentum={55} tilt={45} />
}
```

## Props

| Prop            | Type                      | Default | Description                           |
| --------------- | ------------------------- | ------- | ------------------------------------- |
| `value`         | `number`                  | —       | Controlled value                      |
| `min`           | `number`                  | `0`     | Minimum                               |
| `max`           | `number`                  | `100`   | Maximum                               |
| `step`          | `number`                  | `1`     | Snap                                  |
| `height`        | `number \| string`        | `40`    | Slider track height in px or CSS unit |
| `ring`          | `boolean`                 | `true`  | Inner offset frame ring around track  |
| `onValueChange` | `(value: number) => void` | —       | Change handler                        |
| `corner`        | `number`                  | `13`    | Fill radius, 0–20                     |
| `viscosity`     | `number`                  | `15`    | 0 rigid, 100 loose                    |
| `momentum`      | `number`                  | `55`    | Coast after release                   |
| `tilt`          | `number`                  | `45`    | Lean on the leading edge              |


# Smooth Slider
URL: https://www.spaceui.one/components/smooth-slider

***

title: Smooth Slider
description: A continuous slider with a filled track, tick dots, and a draggable thumb.
preview: demo-c-smooth-slider-01
--------------------------------

## Installation

<ComponentInstallation name="components-spaceui-smooth-slider" />

## Usage

```tsx
import { SmoothSlider } from '@/components/spaceui/smooth-slider'

export default function Example() {
  const [value, setValue] = React.useState(50)
  return <SmoothSlider value={value} onValueChange={setValue} min={0} max={100} step={5} label="Volume" />
}
```

## Props

| Prop             | Type                      | Default    | Description                                                                                     |
| ---------------- | ------------------------- | ---------- | ----------------------------------------------------------------------------------------------- |
| `value`          | `number`                  | —          | Controlled value                                                                                |
| `defaultValue`   | `number`                  | `50`       | Initial value when uncontrolled                                                                 |
| `min`            | `number`                  | `0`        | Floor on the reachable value — positions stay anchored to `[0, max]`, `min` never rescales them |
| `max`            | `number`                  | `100`      | Maximum                                                                                         |
| `step`           | `number`                  | `1`        | Snap                                                                                            |
| `height`         | `number`                  | `32`       | Thumb/fill diameter, in px — dots and the track's own height scale with it                      |
| `showTicks`      | `boolean`                 | `true`     | Dots marking each reachable step along the track                                                |
| `onValueChange`  | `(value: number) => void` | —          | Change handler                                                                                  |
| `label`          | `string`                  | `'Slider'` | Accessible name — the control carries no visible one                                            |
| `disabled`       | `boolean`                 | `false`    | Disables the control                                                                            |
| `className`      | `string`                  | —          | Class on the outer track                                                                        |
| `fillClassName`  | `string`                  | —          | Overrides the fill bar's background — the default is a gradient                                 |
| `thumbClassName` | `string`                  | —          | Overrides the thumb's background                                                                |


# Smooth Orb
URL: https://www.spaceui.one/components/smooth

***

title: Smooth Orb
description: Audio-reactive fluid WebGL orb. Swap ambient, microphone, or file input, change the texture, and toggle grain.
preview: demo-c-orb-smooth-01
-----------------------------

## Installation

<ComponentInstallation name="components-orb-smooth" />

## Usage

```tsx
import { OrbSmooth } from '@/components/orb/smooth'

export function HeroOrb() {
  return <OrbSmooth size={420} audioMode="ambient" grainAnimated />
}
```

## Files

| File                       | Role                                       |
| -------------------------- | ------------------------------------------ |
| `smooth/index.tsx`         | `OrbSmooth` WebGPU fluid sim + display     |
| `smooth/sim.wgsl.ts`       | Splat, advect, pressure, blur passes       |
| `smooth/display.wgsl.ts`   | Sphere shading, grain, texture mapping     |
| `smooth/audio-analyzer.ts` | Mic / `<audio>` analyser → shader uniforms |
| `smooth/types.ts`          | `OrbSmoothProps`, `AudioMode`              |

## API Reference

### OrbSmooth

| Prop                 | Type                           | Default     | Description                                |
| -------------------- | ------------------------------ | ----------- | ------------------------------------------ |
| `textureUrl`         | `string`                       | —           | Equirect / image mapped onto the orb       |
| `audioMode`          | `'ambient' \| 'mic' \| 'file'` | `'ambient'` | How audio drives the fluid                 |
| `audioElement`       | `RefObject<HTMLAudioElement>`  | —           | Required when `audioMode` is `'file'`      |
| `useMicrophone`      | `boolean`                      | `false`     | Legacy mic flag, overridden by `audioMode` |
| `animated`           | `boolean`                      | `true`      | Runs the simulation loop                   |
| `sphereScale`        | `number`                       | `0.9`       | Sphere size in the display pass            |
| `spherePower`        | `number`                       | `1.1`       | Limb falloff                               |
| `grainOpacity`       | `number`                       | `0`         | Film grain mix                             |
| `grainAnimated`      | `boolean`                      | `true`      | Wave-drift grain (off = static)            |
| `watercolorStrength` | `number`                       | `0.5`       | Watercolor UV warp (min = 0, max = 1)      |
| `timeScale`          | `number`                       | `1.4`       | Simulation speed                           |
| `className`          | `string`                       | —           | Canvas wrapper class                       |

## Audio modes

Use the demo buttons: **Ambient** idles the fluid, **Mic** requests `getUserMedia`, **Audio file** binds an `<audio>` element. Grain and texture are independent of audio.


# Sortable
URL: https://www.spaceui.one/components/sortable

***

title: Sortable
description: Allows users to reorder items in a list or grid by dragging and dropping them with smooth layout animations.
component: true
base: base
preview:
name: demo-c-sortable-01
align: start
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="components-spaceui-sortable" />

## Usage

```tsx
import { Sortable, SortableItem, SortableItemHandle } from '@/components/spaceui/sortable'
```

```tsx
<Sortable value={items} onValueChange={setItems} getItemValue={(item) => item.id}>
  {items.map((item) => (
    <SortableItem key={item.id} value={item.id}>
      <SortableItemHandle>
        <GripVertical />
      </SortableItemHandle>
      {item.content}
    </SortableItem>
  ))}
</Sortable>
```

## Examples

### Grid

<ComponentPreview name="demo-c-sortable-02" className="**:[.preview]:h-auto" align="start" />

### Nested

<ComponentPreview name="demo-c-sortable-03" className="**:[.preview]:h-auto" align="start" />

### Persist to a backend

<ComponentPreview name="demo-c-sortable-08" className="**:[.preview]:h-auto" align="start" />

## Persisting order

Sortable commits once, on drop, so `onValueChange` alone is already enough to
persist the whole array. When you want index-based mutations and a one-line
rollback, use `onValueCommit`: it fires with the reordered array and a
`previousValue` snapshot.

```tsx
const reorder = api.list.reorder.useMutation()

<Sortable
  value={items}
  onValueChange={setItems}
  getItemValue={(item) => item.id}
  onValueCommit={(next, meta) => {
    reorder.mutate(
      { id: next[meta.overIndex].id, toIndex: meta.overIndex },
      {
        onError: () => {
          setItems(meta.previousValue) // roll back
          toast.error("Could not save the new order. Restored.")
        },
      },
    )
  }}
>
  {/* ... */}
</Sortable>
```

## API Reference

### Sortable

The root component that manages the sortable state and drag-and-drop context.

| Prop            | Type                                                                               | Default      | Description                                                                                                                                                                           |
| :-------------- | :--------------------------------------------------------------------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `value`         | `T[]`                                                                              | -            | **Required**. The array of items to sort.                                                                                                                                             |
| `onValueChange` | `(value: T[]) => void`                                                             | -            | **Required**. Fired once, on drop, with the reordered array. This alone is enough to persist the whole array.                                                                         |
| `getItemValue`  | `(item: T) => string`                                                              | -            | **Required**. Function to extract a unique ID from an item.                                                                                                                           |
| `onValueCommit` | `(value: T[], meta: SortableCommitMeta<T>) => void`                                | -            | Fired on drop with the reordered array and a `previousValue` snapshot. Convenient for index-based backend mutations and one-line rollback. See [Persisting order](#persisting-order). |
| `onMove`        | `(event: { event: DragEndEvent; activeIndex: number; overIndex: number }) => void` | -            | Opt-in. When set, replaces the default `onValueChange` reorder so you apply the move yourself.                                                                                        |
| `strategy`      | `"horizontal" \| "vertical" \| "grid"`                                             | `"vertical"` | The sorting strategy and layout of the list.                                                                                                                                          |
| `onDragStart`   | `(event: DragStartEvent) => void`                                                  | -            | Raw dnd-kit passthrough, fired when a drag starts.                                                                                                                                    |
| `onDragEnd`     | `(event: DragEndEvent) => void`                                                    | -            | Raw dnd-kit passthrough, fired before the reorder is applied (so `onValueChange` is the persistence seam, not this).                                                                  |
| `onDragCancel`  | `(event: DragCancelEvent) => void`                                                 | -            | Raw dnd-kit passthrough, fired when a drag is cancelled.                                                                                                                              |
| `accessibility` | `DndContextProps["accessibility"]`                                                 | -            | dnd-kit accessibility options (announcements and screen reader instructions).                                                                                                         |
| `modifiers`     | `Modifiers`                                                                        | -            | dnd-kit modifiers applied to the drag.                                                                                                                                                |
| `className`     | `string`                                                                           | -            | Additional CSS classes for the container.                                                                                                                                             |

`SortableCommitMeta<T>` is `{ event: DragEndEvent; activeIndex: number; overIndex: number; previousValue: T[] }`.

***

### SortableItem

An individual draggable item within the sortable list.

| Prop        | Type      | Default | Description                                       |
| :---------- | :-------- | :------ | :------------------------------------------------ |
| `value`     | `string`  | -       | **Required**. The unique identifier for the item. |
| `disabled`  | `boolean` | `false` | Whether the item is draggable.                    |
| `className` | `string`  | -       | Additional CSS classes for the item.              |

***

### SortableItemHandle

The drag handle for an individual sortable item.

| Prop        | Type     | Default | Description                            |
| :---------- | :------- | :------ | :------------------------------------- |
| `className` | `string` | -       | Additional CSS classes for the handle. |

## All 8 variations

### Sortable playlist with frame

<ComponentPreview name="demo-c-sortable-04" />

### Sortable settings priority with frame

<ComponentPreview name="demo-c-sortable-05" />

### Sortable sidebar navigation with frame

<ComponentPreview name="demo-c-sortable-06" />

### Sortable image gallery grid with frame

<ComponentPreview name="demo-c-sortable-07" />


# Squircle
URL: https://www.spaceui.one/components/squircle

***

title: Squircle
description: Flawless math-driven squircle masking and geometry rendering for modern UIs using CSS Houdini.
preview:
name: demo-c-squircle-01
contained: false
----------------

`@usespaceui/squircle` brings iOS-style squircles (mathematically perfect superellipses) to your Tailwind CSS projects. It mimics the continuous curvature corners found in Figma and Apple devices.
By utilizing the CSS Houdini Paint Worklet API, it provides native-like performance and seamlessly integrates with Tailwind CSS.

## Features

* 💃 **Native Tailwind Integration:** Use utility classes like `squircle-2xl` just like you would `rounded-2xl`. No framework-specific wrappers required.
* ⚡️ **Zero-JS Layout Thrashing:** Driven by the native CSS Paint API (Houdini). Repaints happen instantly on the compositor thread.
* ✨ **Native Borders:** The worklet automatically detects and renders standard Tailwind borders perfectly onto the squircle shape.
* 🛠️ **Customizable Smoothing:** Adjust the smoothing intensity with modifiers (`/0` to `/100`).

***

## Installation

If you initialized Space UI in your project, the squircle plugin is already included! If not, you can install it manually:

<InstallCommandBlock packages="@usespaceui/squircle" />

***

## Setup

Because the plugin relies on a CSS Houdini worklet to draw the shape, you must initialize the script once in your app.

### 1. Provider Initialization (React / Next.js)

Since the worklet interacts with the browser DOM, initialize it inside a Client Component provider.

```tsx title="components/providers/squircle-provider.tsx"
'use client'
import * as React from 'react'
import { initSquircle } from '@usespaceui/squircle'

export function SquircleProvider({ children }: { children: React.ReactNode }) {
  React.useEffect(() => {
    initSquircle()
  }, [])

  return <>{children}</>
}
```

Wrap your root layout with this provider:

```tsx title="app/layout.tsx"
import { SquircleProvider } from '@/components/providers/squircle-provider'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <SquircleProvider>{children}</SquircleProvider>
      </body>
    </html>
  )
}
```

### 2. Tailwind CSS Configuration

**For Tailwind CSS v4:**
Add the squircle plugin to your `app.css` or `globals.css`.

```css
@plugin '@usespaceui/squircle';
```

**For Tailwind CSS v3:**
Add the squircle plugin to your `tailwind.config.ts`.

```ts title="tailwind.config.ts"
import squirclePlugin from '@usespaceui/squircle'

export default {
  plugins: [squirclePlugin],
}
```

***

## Usage

You do NOT need a React component to use Squircles. Just use the `squircle-*` classes on standard HTML elements! The classes automatically map to your Tailwind theme's `borderRadius` values.

### 1. Sizing

```tsx
export default function SpaceUI() {
  return (
    <>
      {/* Matches rounded-md */}
      <div className="squircle rounded-md p-4 bg-primary text-primary-foreground">Squircle!</div>

      {/* Matches rounded-2xl */}
      <div className="squircle rounded-2xl bg-muted" />

      {/* Perfectly circular/pill shape */}
      <div className="squircle rounded-full" />

      {/* Arbitrary values are fully supported */}
      <div className="squircle rounded-[40px]" />
    </>
  )
}
```

### 2. Smoothing Intensity

By default, the plugin applies a **60% smooth transition** between the straight edge and the corner arc, perfectly matching native OS smoothing.

You can adjust this intensity using modifiers (`/0`, `/20`, `/40`, `/60`, `/80`, `/100`).

```tsx
export default function SpaceUI() {
  return (
    <>
      {/* Maximum smoothing */}
      <div className="squircle/100 rounded-2xl bg-primary" />

      {/* Minimal smoothing (closer to a plain rounded rectangle) */}
      <div className="squircle/20 rounded-2xl bg-primary" />

      {/* Arbitrary smoothing */}
      <div className="squircle/[0.25] rounded-2xl bg-primary" />
    </>
  )
}
```

### 3. Native Borders & Backgrounds (The Magic)

Unlike basic CSS masks, the Houdini worklet reads your **native CSS border and background classes** and draws them flawlessly.

```tsx
export default function SpaceUI() {
  return (
    <div>
      {/* 8px red border perfectly drawn onto the squircle shape */}
      <div className="squircle rounded-2xl border-8 border-red-500 bg-black" />
      {/* 1px semi-transparent blue border */}
      <div className="squircle rounded-[30px] border border-blue-500/50 bg-white" />
    </div>
  )
}
```

> **Note on border placement:**
> By default, the plugin draws the border **outside** the element (like an outline or a ring) to preserve the interior space for your content. If you want the border drawn inward (standard CSS border-box behavior), you can override the custom CSS variable:
> `<div className="squircle rounded-2xl border-4 border-red-500">...</div>`


# Status Badge
URL: https://www.spaceui.one/components/status-badge

***

title: Status Badge
description: Displays a real-time status indicator with a pulsing dot and color coding to show whether a service or user is online or busy.
preview: demo-c-status-badge-01
-------------------------------

## Installation

<ComponentInstallation name="components-spaceui-status-badge" />

## Usage

```tsx
import { StatusBadge } from '@/components/spaceui/status-badge'
```

```tsx
<StatusBadge status="available" primaryText="Disponible" size="default">
  <Link href="#contact" className="inline-flex items-center gap-1">
    <span>1 place restante pour ce mois-ci</span>
    <ArrowUpRight className="size-3.5" />
  </Link>
</StatusBadge>
```

## API Reference

### StatusBadge Props

| Prop                     | Type                                                                                         | Default     | Description                                                             |
| ------------------------ | -------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| `status`                 | `"online" \| "available" \| "busy" \| "away" \| "offline" \| "error" \| "warning" \| "info"` | `"online"`  | Semantic status controlling indicator dot color and ping wave color     |
| `primaryText`            | `string`                                                                                     | -           | Primary bold label text shown next to the indicator                     |
| `mode`                   | `"inline" \| "stack"`                                                                        | `"inline"`  | Layout mode (`inline` for badge, `stack` for multi-line card)           |
| `animated`               | `boolean`                                                                                    | `true`      | Enables animated radar ping wave effect                                 |
| `showIndicator`          | `boolean`                                                                                    | `true`      | Whether to display the status indicator dot                             |
| `variant`                | `"default" \| "inverted" \| "outline"`                                                       | `"default"` | Visual style variant for the badge container                            |
| `size`                   | `"default" \| "xs" \| "sm" \| "md" \| "lg"`                                                  | `"default"` | Sizing scale for badge and indicator                                    |
| `indicatorClassName`     | `string`                                                                                     | -           | Custom class name for the indicator dot                                 |
| `primaryTextClassName`   | `string`                                                                                     | -           | Custom class name for the primary text label                            |
| `secondaryTextClassName` | `string`                                                                                     | -           | Custom class name for the secondary text / children                     |
| `indicatorBadge`         | `boolean`                                                                                    | `false`     | In stacked mode, encloses the indicator dot in a square badge container |

## Features

### Sizes

<ComponentPreview name="demo-c-status-badge-02" />

### Variants

<ComponentPreview name="demo-c-status-badge-03" />

### Radar Ping & Animation

<ComponentPreview name="demo-c-status-badge-04" />

### Stacked Mode

<ComponentPreview name="demo-c-status-badge-05" />

## Examples

<ShowcaseGrid>
  <ShowcaseCard name="demo-c-status-badge-06" description="Planning availability with link" />

  <ShowcaseCard name="demo-c-status-badge-07" description="Unavailable with resumption date" />

  <ShowcaseCard name="demo-c-status-badge-08" description="Mission quotas" />

  <ShowcaseCard name="demo-c-status-badge-09" description="Freelance and direct project callout" />
</ShowcaseGrid>


# Team Roster Selector
URL: https://www.spaceui.one/components/team-roster-selector

***

title: Team Roster Selector
description: Interactive team roster selection list with generative avatars, spring hover pill, and multi-select state.
preview: demo-c-team-roster-selector-01
---------------------------------------

## Installation

<ComponentInstallation name="components-spaceui-team-roster-selector" />

## Usage

```tsx
import { TeamRosterSelector } from '@/components/spaceui/team-roster-selector'

export default function Example() {
  return <TeamRosterSelector />
}
```

## Props

| Prop                | Type                      | Default           | Description                            |
| ------------------- | ------------------------- | ----------------- | -------------------------------------- |
| `members`           | `TeamMember[]`            | `DEFAULT_MEMBERS` | List of team members with avatar seeds |
| `selectedIds`       | `string[]`                | `—`               | Controlled selected member IDs         |
| `onSelectionChange` | `(ids: string[]) => void` | `—`               | Selection change callback              |
| `onAction`          | `(ids: string[]) => void` | `—`               | CTA action button callback             |
| `title`             | `string`                  | `'Team Members'`  | Header title text                      |
| `corner`            | `number`                  | `24`              | Corner radius in px                    |


# Textmoji
URL: https://www.spaceui.one/components/textmoji

***

title: Textmoji
description: Renders every Unicode emoji in a string as an image sized to the surrounding text.
preview:
name: demo-c-textmoji-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-textmoji" />

## Usage

```tsx
import { Textmoji } from '@/components/spaceui/textmoji'

export default function Example() {
  return (
    <p>
      <Textmoji source="fluent">Ship your ideas faster 🚀 with better UI ✨</Textmoji>
    </p>
  )
}
```

For animated emoji, use [Textmoji Animated](/components/animoji) instead — same API, different provider list.

## Examples

### Sizes

<ComponentPreview name="demo-c-textmoji-02" contained={false} />

### Sources

<ComponentPreview name="demo-c-textmoji-03" contained={false} />

### Unicode escapes & flags

<ComponentPreview name="demo-c-textmoji-04" contained={false} />

### With Blur Reveal Text

<ComponentPreview name="demo-c-textmoji-05" contained={false} />

## Props

| Prop             | Type                                                       | Default    | Description                                            |
| ---------------- | ---------------------------------------------------------- | ---------- | ------------------------------------------------------ |
| `children`       | `string`                                                   | —          | The text to scan                                       |
| `source`         | `'fluent' \| 'apple' \| 'twemoji' \| 'blobmoji' \| 'noto'` | `'fluent'` | Provider to render — only the ones with a static style |
| `className`      | `string`                                                   | —          | Class on the outer wrapper                             |
| `emojiClassName` | `string`                                                   | —          | Class applied to each rendered emoji image             |


# Theme Toggle
URL: https://www.spaceui.one/components/theme-toggle

***

title: Theme Toggle
description: View Transition API theme switch with circle, blur, rectangle, and polygon reveals.
preview: demo-c-theme-toggle-01
-------------------------------

The demo lets you pick `variant`, `start` origin, and blur, then click the button. Source: `registry/components/spaceui/theme-toggle/index.tsx`. It uses `next-themes` and injects `::view-transition-*` CSS before `document.startViewTransition`.

## Installation

<ComponentInstallation name="components-spaceui-theme-toggle" />

Requires `next-themes` and a theme provider already in the app.

## Usage

```tsx
import { ThemeToggleButton } from '@/components/spaceui/theme-toggle'

export default function SpaceUI() {
  return <ThemeToggleButton variant="circle" start="top-left" blur size="lg" />
}
```

```tsx
const { isDark, toggleTheme } = useThemeToggle({ variant: 'rectangle', start: 'left-right' })
```

## Files

| File                     | Role                                                     |
| ------------------------ | -------------------------------------------------------- |
| `theme-toggle/index.tsx` | `createAnimation`, `useThemeToggle`, `ThemeToggleButton` |

## API Reference

### ThemeToggleButton / useThemeToggle

| Prop            | Type                                                    | Default         | Description                      |
| --------------- | ------------------------------------------------------- | --------------- | -------------------------------- |
| `variant`       | `'circle' \| 'circle-blur' \| 'rectangle' \| 'polygon'` | `'circle'`      | Reveal shape                     |
| `start`         | `'center' \| 'top-left' \| …`                           | `'center'`      | Clip origin (depends on variant) |
| `blur`          | `boolean`                                               | `false`         | Blur during the reveal           |
| `size`          | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                  | `'md'` (`icon`) | Square button size               |
| `buttonVariant` | `'outline' \| 'secondary' \| 'default' \| 'ghost'`      | `'secondary'`   | Primitive button visual style    |
| `className`     | `string`                                                | —               | Button class (button only)       |

`useThemeToggle` also returns `toggleTheme`, `setCrazyLightTheme`, `setCrazyDarkTheme`, `setCrazySystemTheme`, and `isDark`.


# Thinking Orb
URL: https://www.spaceui.one/components/thinking

***

title: Thinking Orb
description: 9 procedural Canvas 3D particle loader orbs representing AI cognitive states — working, searching, solving, listening, connecting, weaving, composing, breathing, and shaping.
preview: demo-c-orb-thinking-01
-------------------------------

## Installation

<ComponentInstallation name="components-orb-thinking" />

## Usage

```tsx
import { ThinkingOrb } from '@/components/orb/thinking'

export default function App() {
  return <ThinkingOrb variant="working" surface="auto" size={240} speed={1} scale={0.72} />
}
```

You can also import dedicated variant components directly:

```tsx
import {
  OrbWorking,
  OrbSearching,
  OrbSolving,
  OrbListening,
  OrbConnecting,
  OrbWeaving,
  OrbComposing,
  OrbBreathing,
  OrbShaping,
} from '@/components/orb/thinking'

export function SolvingState() {
  return <OrbSolving size={180} />
}
```

## API Reference

### ThinkingOrb

| Prop        | Type                                                                                                                           | Default     | Description                                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------- |
| `variant`   | `'working' \| 'searching' \| 'solving' \| 'listening' \| 'connecting' \| 'weaving' \| 'composing' \| 'breathing' \| 'shaping'` | `'working'` | Active AI thinking animation state                                                                              |
| `surface`   | `'auto' \| 'ink' \| 'paper'`                                                                                                   | `'auto'`    | Color tone. `'ink'` renders for dark mode; `'paper'` renders for light mode; `'auto'` tracks the document theme |
| `size`      | `number \| string`                                                                                                             | `240`       | Canvas container size in pixels or CSS units                                                                    |
| `scale`     | `number`                                                                                                                       | `0.72`      | Inner particle sphere scale factor (`0.2` to `0.95`)                                                            |
| `speed`     | `number`                                                                                                                       | `1`         | Animation speed multiplier (`0.25` to `2.0`)                                                                    |
| `playback`  | `'play' \| 'pause'`                                                                                                            | `'play'`    | Playback state                                                                                                  |
| `className` | `string`                                                                                                                       | —           | Additional CSS classes                                                                                          |

## Cognitive States

### Working Orb

Particles tracing tilted orbital rings around a ghosted sphere.

<ComponentPreview name="demo-c-orb-thinking-01" />

### Searching Orb

A dotted globe swept by a rotating scan band.

<ComponentPreview name="demo-c-orb-thinking-02" />

### Solving Orb

A point-cloud sphere permuted by successive quarter-turn slice rotations.

<ComponentPreview name="demo-c-orb-thinking-03" />

### Listening Orb

Latitude rings breathing in and out on two detuned sine waves.

<ComponentPreview name="demo-c-orb-thinking-04" />

### Connecting Orb

A drifting node graph with proximity links and travelling signals.

<ComponentPreview name="demo-c-orb-thinking-05" />

### Weaving Orb

Three helical strands braiding around a ghosted sphere.

<ComponentPreview name="demo-c-orb-thinking-06" />

### Composing Orb

A rippling multi-lane ribbon wrapped over a sphere.

<ComponentPreview name="demo-c-orb-thinking-07" />

### Breathing Orb

A face-on ring pulsing with a slow radial ripple.

<ComponentPreview name="demo-c-orb-thinking-08" />

### Shaping Orb

A dotted outline morphing between circle, triangle and square.

<ComponentPreview name="demo-c-orb-thinking-09" />


# Tick Slider
URL: https://www.spaceui.one/components/tick-slider

***

title: Tick Slider
description: A scrubber drawn as a row of tick marks, backed by a real range input.
preview:
name: demo-c-tick-slider-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-tick-slider" />

## Usage

```tsx
import { TickSlider } from '@/components/spaceui/tick-slider'

export default function Example() {
  const [value, setValue] = React.useState(24)
  return (
    <TickSlider
      value={value}
      onChange={setValue}
      min={16}
      max={48}
      step={1}
      majorEvery={8}
      unit="px"
      fixedPitch
      label="Font size"
    />
  )
}
```

## Props

| Prop             | Type                         | Default | Description                                                              |
| ---------------- | ---------------------------- | ------- | ------------------------------------------------------------------------ |
| `value`          | `number`                     | —       | Controlled value                                                         |
| `onChange`       | `(next: number) => void`     | —       | Change handler                                                           |
| `min`            | `number`                     | `0`     | Minimum                                                                  |
| `max`            | `number`                     | `100`   | Maximum                                                                  |
| `step`           | `number`                     | `1`     | Snap                                                                     |
| `majorEvery`     | `number`                     | `4`     | Every Nth step gets a taller mark                                        |
| `isMajorMark`    | `(value: number) => boolean` | —       | Custom predicate for taller marks, overrides `majorEvery`                |
| `label`          | `string`                     | —       | Accessible name — the control carries no visible label                   |
| `unit`           | `string`                     | `''`    | Suffix on the value readout                                              |
| `showValue`      | `boolean`                    | `true`  | Shows the numeric readout on the right                                   |
| `disabled`       | `boolean`                    | `false` | Disables the control                                                     |
| `fixedPitch`     | `boolean`                    | `false` | Sizes the rail from the mark pitch instead of filling the container      |
| `trackClassName` | `string`                     | —       | Overrides the rail's width/class entirely — takes over from `fixedPitch` |
| `className`      | `string`                     | —       | Class on the outer wrapper                                               |


# Timeline
URL: https://www.spaceui.one/components/timeline

***

title: Timeline
description: Displays a vertical sequence of events, milestone dates, and activity logs connected by a timeline line.
component: true
base: base
preview:
name: demo-c-timeline-01
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Examples

### With Left-Aligned Dates

<ComponentPreview name="demo-c-timeline-02" className="**:[.preview]:h-auto" />

### With Custom Indicators

<ComponentPreview name="demo-c-timeline-03" className="**:[.preview]:h-auto" />

### With Icons

<ComponentPreview name="demo-c-timeline-04" className="**:[.preview]:h-auto" />

### Alternating Layout

<ComponentPreview name="demo-c-timeline-05" className="**:[.preview]:h-auto" />

### Deployment Pipeline with Details

<ComponentPreview name="demo-c-timeline-06" className="**:[.preview]:h-auto" />

### Milestones with Status Colors

<ComponentPreview name="demo-c-timeline-07" className="**:[.preview]:h-auto" />

### Horizontal Orientation

<ComponentPreview name="demo-c-timeline-08" className="**:[.preview]:h-auto" />

### Compact Horizontal Roadmap

<ComponentPreview name="demo-c-timeline-09" className="**:[.preview]:h-auto" />

### Deployment Log Feed

<ComponentPreview name="demo-c-timeline-10" className="**:[.preview]:h-auto" />

### Activity Feed with User Avatars

<ComponentPreview name="demo-c-timeline-11" className="**:[.preview]:h-auto" />

### Interactive Horizontal Timeline

<ComponentPreview name="demo-c-timeline-12" className="**:[.preview]:h-auto" />

## Installation

<ComponentInstallation name="components-spaceui-timeline" />

## Usage

```tsx
import {
  Timeline,
  TimelineContent,
  TimelineDate,
  TimelineHeader,
  TimelineIndicator,
  TimelineItem,
  TimelineSeparator,
  TimelineTitle,
} from '@/components/spaceui/timeline'
```

```tsx
<Timeline>
  <TimelineItem step={1}>
    <TimelineHeader>
      <TimelineDate>March 2024</TimelineDate>
      <TimelineTitle>Project Initialized</TimelineTitle>
    </TimelineHeader>
    <TimelineIndicator />
    <TimelineSeparator />
    <TimelineContent>Successfully set up the project repository and initial architecture.</TimelineContent>
  </TimelineItem>
</Timeline>
```

## API Reference

### Timeline

The root component for the timeline.

| Prop            | Type                         | Default      | Description                                  |
| :-------------- | :--------------------------- | :----------- | :------------------------------------------- |
| `defaultValue`  | `number`                     | `1`          | The initial active step.                     |
| `value`         | `number`                     | -            | The current active step (controlled).        |
| `onValueChange` | `(value: number) => void`    | -            | Callback fired when the active step changes. |
| `orientation`   | `"horizontal" \| "vertical"` | `"vertical"` | The layout orientation of the timeline.      |

### TimelineItem

A single item in the timeline.

| Prop   | Type     | Default | Description                                  |
| :----- | :------- | :------ | :------------------------------------------- |
| `step` | `number` | -       | **Required**. The step number for this item. |

### TimelineDate

The date or time label for a timeline item.

| Prop        | Type     | Default | Description                                |
| :---------- | :------- | :------ | :----------------------------------------- |
| `className` | `string` | -       | Additional CSS classes for the date label. |

### TimelineTitle

The title for a timeline item.

| Prop        | Type     | Default | Description                           |
| :---------- | :------- | :------ | :------------------------------------ |
| `className` | `string` | -       | Additional CSS classes for the title. |

### TimelineIndicator

The visual indicator (usually a dot) for a timeline item.

| Prop        | Type     | Default | Description                               |
| :---------- | :------- | :------ | :---------------------------------------- |
| `className` | `string` | -       | Additional CSS classes for the indicator. |

### TimelineSeparator

The line connecting timeline indicators.

| Prop        | Type     | Default | Description                                    |
| :---------- | :------- | :------ | :--------------------------------------------- |
| `className` | `string` | -       | Additional CSS classes for the separator line. |

### TimelineHeader

A container for the date and title.

| Prop        | Type     | Default | Description                                      |
| :---------- | :------- | :------ | :----------------------------------------------- |
| `className` | `string` | -       | Additional CSS classes for the header container. |

### TimelineContent

The main descriptive content for a timeline item.

| Prop        | Type     | Default | Description                                       |
| :---------- | :------- | :------ | :------------------------------------------------ |
| `className` | `string` | -       | Additional CSS classes for the content container. |

## All 12 variations

### Activity feed timeline with user avatars

<ComponentPreview name="demo-c-timeline-11" />

### Compact horizontal milestone timeline

<ComponentPreview name="demo-c-timeline-12" />


# Tournament Bracket
URL: https://www.spaceui.one/components/tournament-bracket

***

title: Tournament Bracket
description: Animated knockout bracket with round navigation, live and finished matches, and elbow connectors.
preview:
name: demo-c-tournament-bracket-01
contained: false
----------------

Source: `registry/components/spaceui/tournament-bracket/index.tsx`. Round chevrons shift the visible window; match cards and connectors are `motion` layout.

## Installation

<ComponentInstallation name="components-spaceui-tournament-bracket" />

## Usage

```tsx
import { TournamentBracket } from '@/components/spaceui/tournament-bracket'

export default function SpaceUI() {
  return <TournamentBracket />
}
```

## Files

| File                           | Role                                                                      |
| ------------------------------ | ------------------------------------------------------------------------- |
| `tournament-bracket/index.tsx` | `TEAMS`, rounds data, `MatchBox`, `BracketContainer`, `TournamentBracket` |

Default data is a World Cup–style knockout. Swap `rounds` in the file to feed your own matches (`status`: `upcoming` | `live` | `finished`, optional penalties).


# User Presence Avatar
URL: https://www.spaceui.one/components/user-presence-avatar

***

title: User Presence Avatar
description: A compact avatar group for showing online and offline users, with smooth animated transitions when presence changes.
author:
name: arhamkhnz
url: [https://github.com/arhamkhnz](https://github.com/arhamkhnz)
preview: demo-c-user-presence-avatar-01
---------------------------------------

## Installation

<ComponentInstallation name="components-spaceui-user-presence-avatar" />

## Usage

```tsx
<UserPresenceAvatar users={users} />
```

## Credits

* Credits to [Farrel](https://x.com/farrelput) for [this X post](https://x.com/farrelput/status/1915792408580628817) as inspiration


# Voice Chat Widget
URL: https://www.spaceui.one/components/voice-chat-widget

***

title: Voice Chat Widget
description: An expandable voice chat pill with participant avatars, animated speaking indicators, and a smooth pill-to-panel transition.
preview:
name: demo-c-voice-chat-widget-01
contained: false
----------------

## Installation

<ComponentInstallation name="components-spaceui-voice-chat-widget" />


# Words Preloader
URL: https://www.spaceui.one/components/words-preloader

***

title: Words Preloader
description: Greeting cycle preloader that exits with a curved SVG wipe. Replay from the demo.
preview: demo-c-words-preloader-01
----------------------------------

## Installation

<ComponentInstallation name="components-spaceui-words-preloader" />

## Usage

```tsx
import { WordsPreloader } from '@/components/spaceui/words-preloader'

export default function SpaceUI() {
  return (
    <WordsPreloader words={['Hello', 'bonjour', 'Ciao']} duration={2000}>
      <YourPage />
    </WordsPreloader>
  )
}
```

## Files

| File                        | Role                               |
| --------------------------- | ---------------------------------- |
| `words-preloader/index.tsx` | Overlay, word index, SVG path wipe |

## API Reference

| Prop        | Type        | Default       | Description                          |
| ----------- | ----------- | ------------- | ------------------------------------ |
| `words`     | `string[]`  | greetings     | Sequence shown before the wipe       |
| `duration`  | `number`    | `2000`        | Milliseconds before exit             |
| `className` | `string`    | —             | Root class                           |
| `children`  | `ReactNode` | fallback copy | Content revealed after the preloader |


# cache
URL: https://www.spaceui.one/hooks/cache

***

title: cache
description: Memory memoization cache map.
preview: demo-h-cache-01
------------------------

## Installation

<ComponentInstallation name="hooks-utils-cache" />

## Usage

```tsx
import { cache } from '@/utils/cache'

const memoized = cache((x: number) => x * 10)
```

## API Reference

### Parameters / Props

| Parameter | Type       | Default    | Description             |
| :-------- | :--------- | :--------- | :---------------------- |
| `fn`      | `Function` | *required* | Computation to memoize. |

### Return Value

| Return Type | Description        |
| :---------- | :----------------- |
| `Function`  | Memoized function. |


# Class
URL: https://www.spaceui.one/hooks/class

***

title: Class
description: Conditional class wrapper component.
preview: demo-h-class-01
------------------------

## Installation

<ComponentInstallation name="hooks-components-class" />

## Usage

````tsx
import { Class } from '@/components/class'

import { Class } from '@/components/class'```

```tsx
<Class names={{ 'bg-primary text-white': isActive }}>
  <div>Box</div>
</Class>
````

## API Reference

### Parameters / Props

| Prop       | Type                      | Default    | Description          |
| :--------- | :------------------------ | :--------- | :------------------- |
| `names`    | `Record<string, boolean>` | *required* | Class condition map. |
| `children` | `ReactElement`            | *required* | Target element.      |

### Return Value

| Return Type    | Description                          |
| :------------- | :----------------------------------- |
| `ReactElement` | Cloned element with classes applied. |


# cookie
URL: https://www.spaceui.one/hooks/cookie

***

title: cookie
description: Imperative cookie helper with get, set, and delete.
preview: demo-h-cookie-01
-------------------------

## Installation

<ComponentInstallation name="hooks-utils-cookie" />

## Usage

```tsx
import { setCookie, getCookie, deleteCookie } from '@/utils/cookie'

setCookie('theme', 'dark', 7)
const val = getCookie('theme')
deleteCookie('theme')
```

## API Reference

### Parameters / Props

| Method                   | Parameters                      | Description                    |
| :----------------------- | :------------------------------ | :----------------------------- |
| `get(name)`              | `string`                        | Returns cookie string or null. |
| `set(name, value, opts)` | `string, string, CookieOptions` | Sets cookie.                   |
| `remove(name)`           | `string`                        | Deletes cookie.                |

### Return Value

*Utility object with methods.*


# event & bindEvent
URL: https://www.spaceui.one/hooks/event

***

title: event & bindEvent
description: Safe cross-browser event listener binder with automatic unbind return.
preview: demo-h-event-01
------------------------

## Installation

<ComponentInstallation name="hooks-utils-event" />

## Usage

```tsx
import { bindEvent } from '@/utils/event'

const unbind = bindEvent(window, 'resize', () => onResize())
```

## API Reference

### Parameters / Props

| Parameter  | Type            | Default    | Description     |
| :--------- | :-------------- | :--------- | :-------------- |
| `target`   | `EventTarget`   | *required* | DOM target.     |
| `type`     | `string`        | *required* | Event name.     |
| `listener` | `EventListener` | *required* | Event callback. |

### Return Value

| Return Type  | Description       |
| :----------- | :---------------- |
| `() => void` | Cleanup function. |


# For
URL: https://www.spaceui.one/hooks/for

***

title: For
description: Declarative JSX list rendering component with automatic empty state fallback.
preview: demo-h-for-01
----------------------

### Example 2: Interactive Product Catalog with Search

<ComponentPreview name="demo-h-for-02" />

## Installation

<ComponentInstallation name="hooks-components-for" />

## Usage

````tsx
import { For } from '@/components/for'

import { For } from '@/components/for'```

```tsx
<For each={['A', 'B', 'C']} fallback={<p>Empty</p>}>
  {(item, i) => <div key={i}>{item}</div>}
</For>
````

## API Reference

### Parameters / Props

| Prop       | Type                                    | Default    | Description           |
| :--------- | :-------------------------------------- | :--------- | :-------------------- |
| `each`     | `T[] \| null \| undefined`              | *required* | Array to map.         |
| `fallback` | `ReactNode`                             | `null`     | Empty state fallback. |
| `children` | `(item: T, index: number) => ReactNode` | *required* | Item renderer.        |

### Return Value

| Return Type | Description    |
| :---------- | :------------- |
| `ReactNode` | Rendered list. |


# formatBytes & parseBytes
URL: https://www.spaceui.one/hooks/format-bytes

***

title: formatBytes & parseBytes
description: Converts raw byte counts into localized human-readable file sizes and parses strings back into bytes.
preview: demo-h-format-bytes-01
-------------------------------

### Example 2: Cloud Storage Usage Meter

<ComponentPreview name="demo-h-format-bytes-02" />

## Installation

<ComponentInstallation name="hooks-utils-format-bytes" />

## Usage

```tsx
import { formatBytes, parseBytes } from '@/utils/format-bytes'

formatBytes(15728640) // => "15.00 MB"
parseBytes('15MB') // => 15728640
```

## API Reference

### Parameters / Props

| Parameter          | Type     | Default    | Description     |
| :----------------- | :------- | :--------- | :-------------- |
| `bytes`            | `number` | *required* | Numeric bytes.  |
| `options.decimals` | `number` | `2`        | Decimal digits. |

### Return Value

| Return Type | Description                 |
| :---------- | :-------------------------- |
| `string`    | Formatted file size string. |


# formatContent & truncate
URL: https://www.spaceui.one/hooks/format-content

***

title: formatContent & truncate
description: Text truncate and content formatting helpers.
preview: demo-h-format-content-01
---------------------------------

## Installation

<ComponentInstallation name="hooks-utils-format-content" />

## Usage

```tsx
import { slugifyHeadline } from '@/utils/format-content'

slugifyHeadline('Getting Started with React!') // => "getting-started-with-react"
```

## API Reference

### Parameters / Props

| Parameter   | Type     | Default    | Description |
| :---------- | :------- | :--------- | :---------- |
| `text`      | `string` | *required* | Input text. |
| `maxLength` | `number` | *required* | Max length. |

### Return Value

| Return Type | Description       |
| :---------- | :---------------- |
| `string`    | Truncated string. |


# formatDate & timeAgo
URL: https://www.spaceui.one/hooks/format-date

***

title: formatDate & timeAgo
description: Localized date and relative time formatting.
preview: demo-h-format-date-01
------------------------------

## Installation

<ComponentInstallation name="hooks-utils-format-date" />

## Usage

```tsx
import { getHumanDate, formatDateDiff } from '@/utils/format-date'

getHumanDate(new Date(), 'short')
formatDateDiff(new Date(Date.now() - 3600000)) // => "1 hour ago"
```

## API Reference

### Parameters / Props

| Parameter | Type                       | Default        | Description   |
| :-------- | :------------------------- | :------------- | :------------ |
| `date`    | `Date \| number \| string` | *required*     | Target date.  |
| `format`  | `string`                   | `'yyyy-MM-dd'` | Date pattern. |

### Return Value

| Return Type | Description            |
| :---------- | :--------------------- |
| `string`    | Formatted date string. |


# formatText (slugify, capitalize)
URL: https://www.spaceui.one/hooks/format-text

***

title: formatText (slugify, capitalize)
description: String transforms and slug generation.
preview: demo-h-format-text-01
------------------------------

## Installation

<ComponentInstallation name="hooks-utils-format-text" />

## Usage

```tsx
import { truncateText, randomWord, capitalizeText } from '@/utils/format-text'

// Sentence case (capitalizes the first letter of each sentence)
capitalizeText('SPACE UI IS THE BEST UI LIBRAY. TRY IT TODAY!')
// => "Space ui is the best ui libray. Try it today!"

// Words case (capitalizes the first letter of every word)
capitalizeText('SPACE UI IS THE BEST UI LIBRAY', 'words')
// => "Space Ui Is The Best Ui Libray"

// Truncate text
truncateText('Space UI is the best UI library!', { maxLength: 8 }) // => "Space..."
```

## API Reference

### `capitalizeText(text, options?)`

Capitalizes text by sentence, words, or first letter while optionally lowercasing the rest.

| Parameter           | Type                               | Default      | Description                                                                                             |
| :------------------ | :--------------------------------- | :----------- | :------------------------------------------------------------------------------------------------------ |
| `text`              | `string`                           | *required*   | The input string to capitalize.                                                                         |
| `options.mode`      | `'sentence' \| 'words' \| 'first'` | `'sentence'` | Capitalization strategy. Can also be passed directly as a string (e.g. `'words'`).                      |
| `options.lowerRest` | `boolean`                          | `true`       | When `true`, lowercases all non-capitalized characters to ensure only the target letters are uppercase. |

**Shorthand helpers:**

* `capitalizeWords(text, options?)` - Shorthand for `capitalizeText(text, { mode: 'words' })`.
* `capitalizeFirst(text, options?)` - Shorthand for `capitalizeText(text, { mode: 'first' })`.
* `capitalize(text, options?)` - Alias for `capitalizeText`.

### `truncateText(text, options?)`

Truncates a string by character or word count and adds an ellipsis.

| Parameter           | Type               | Default    | Description                       |
| :------------------ | :----------------- | :--------- | :-------------------------------- |
| `text`              | `string`           | *required* | The input string to truncate.     |
| `options.type`      | `'char' \| 'word'` | `'char'`   | Truncation mode.                  |
| `options.maxLength` | `number`           | `40`       | Maximum length before truncation. |

### `randomWord(options?)`

Generates pseudo-Latin random words without external dictionaries.

| Parameter              | Type                                         | Default        | Description                       |
| :--------------------- | :------------------------------------------- | :------------- | :-------------------------------- |
| `options.count`        | `number`                                     | `1`            | Number of words to generate.      |
| `options.length`       | `number`                                     | `random (3-8)` | Length of each word.              |
| `options.casing`       | `'lowercase' \| 'uppercase' \| 'capitalize'` | `'lowercase'`  | Output casing style.              |
| `options.separator`    | `string`                                     | `' '`          | Separator between words.          |
| `options.alphanumeric` | `boolean`                                    | `false`        | Includes numeric digits in words. |


# If
URL: https://www.spaceui.one/hooks/if

***

title: If
description: Declarative boolean conditional rendering with lazy function execution.
preview: demo-h-if-01
---------------------

## Installation

<ComponentInstallation name="hooks-components-if" />

## Usage

````tsx
import { If } from '@/components/if'

import { If } from '@/components/if'```

```tsx
<If condition={isLoggedIn} fallback={<p>Logged Out</p>}>
  <p>Welcome back!</p>
</If>
````

## API Reference

### Parameters / Props

| Prop        | Type                         | Default    | Description        |
| :---------- | :--------------------------- | :--------- | :----------------- |
| `condition` | `boolean \| (() => boolean)` | *required* | Boolean condition. |
| `fallback`  | `ReactNode`                  | `null`     | Fallback branch.   |

### Return Value

| Return Type | Description      |
| :---------- | :--------------- |
| `ReactNode` | Rendered output. |


# Image
URL: https://www.spaceui.one/hooks/image

***

title: Image
description: Progressive loading responsive image component.
preview: demo-h-image-01
------------------------

## Installation

<ComponentInstallation name="hooks-components-image" />

## Usage

````tsx
import { Image } from '@/components/image'

import { Image } from '@/components/image'```

```tsx
<Image src="/photo.jpg" alt="Space UI" fallback="/placeholder.jpg" />
````

## API Reference

### Parameters / Props

| Prop       | Type     | Default     | Description        |
| :--------- | :------- | :---------- | :----------------- |
| `src`      | `string` | *required*  | Image URL.         |
| `fallback` | `string` | `undefined` | Error placeholder. |

### Return Value

| Return Type    | Description    |
| :------------- | :------------- |
| `ReactElement` | Image element. |


# InView
URL: https://www.spaceui.one/hooks/in-view

***

title: InView
description: Viewport intersection trigger component wrapper.
preview: demo-h-in-view-01
--------------------------

## Installation

<ComponentInstallation name="hooks-components-in-view" />

## Usage

````tsx
import { InView } from '@/components/in-view'

import { InView } from '@/components/in-view'```

```tsx
<InView fallback={<Skeleton />}>
  <ExpensiveChart />
</InView>
````

## API Reference

### Parameters / Props

| Prop       | Type        | Default    | Description              |
| :--------- | :---------- | :--------- | :----------------------- |
| `fallback` | `ReactNode` | `null`     | Out of view placeholder. |
| `children` | `ReactNode` | *required* | Content when in view.    |

### Return Value

| Return Type | Description      |
| :---------- | :--------------- |
| `ReactNode` | Rendered branch. |


# React Hooks & Utilities
URL: https://www.spaceui.one/hooks

***

title: React Hooks & Utilities
description: Complete collection of 80 production-ready React hooks, declarative control-flow components, and pure utilities by Space UI.
-----------------------------------------------------------------------------------------------------------------------------------------

## Complete Category Summary

| Category               | Total Items      | Description                              | Key Exports                                                                                                          |
| :--------------------- | :--------------- | :--------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |
| **🌐 Browser Hooks**   | **18 hooks**     | Storage, network, screen, cookies, OS    | `useClipboard`, `useNetwork`, `useMediaQuery`, `useLocalStorage`, `useDeviceOS`, `useBatteryStatus`, `useFullscreen` |
| **🖱️ DOM Hooks**      | **12 hooks**     | Listeners, layout dimensions, scroll     | `useClickOutside`, `useLockBodyScroll`, `useKeyPress`, `useSize`, `useWindowSize`, `useMousePosition`                |
| **🔄 Lifecycle Hooks** | **16 hooks**     | Execution control, timers & debouncing   | `useDebounce`, `useInterval`, `useToggle`, `useIsomorphicLayoutEffect`, `useConfirmExit`, `useHold`                  |
| **✨ Animation Hooks**  | **5 hooks**      | Dynamic height, motion & state           | `useAutoHeight`, `useInView`, `useControlledState`, `useDataState`, `useMotionValueState`                            |
| **📝 Form Hooks**      | **10 hooks**     | Uploads, limits, reading time, mutations | `useFileUpload`, `useCharacterLimit`, `useReadingTime`, `useSanitizeContent`, `usePagination`                        |
| **🧱 Control-Flow**    | **8 components** | Declarative JSX control-flow             | `<For />`, `<Show />`, `<If />`, `<Switch />`, `<RenderAfter />`, `<Class />`, `<Image />`, `<InView />`             |
| **🛠️ Pure Utilities** | **11 utils**     | High-performance zero-dep helpers        | `formatBytes`, `rangeMap`, `mapRange`, `sleep`, `bindEvent`, `cookie`, `logger`, `cache`                             |

Install each hook from the registry. Browse the catalog below.


# isNegative
URL: https://www.spaceui.one/hooks/is-negative

***

title: isNegative
description: Negative numeric verification.
preview: demo-h-is-negative-01
------------------------------

## Installation

<ComponentInstallation name="hooks-utils-is-negative" />

## Usage

```tsx
import { isNegative } from '@/utils/is-negative'

isNegative(-5) // true
isNegative(0) // false
```

## API Reference

### Parameters / Props

| Parameter | Type     | Default    | Description      |
| :-------- | :------- | :--------- | :--------------- |
| `num`     | `number` | *required* | Number to check. |

### Return Value

| Return Type | Description                |
| :---------- | :------------------------- |
| `boolean`   | True if strictly negative. |


# logger
URL: https://www.spaceui.one/hooks/logger

***

title: logger
description: Scoped development and production logger.
preview: demo-h-logger-01
-------------------------

## Installation

<ComponentInstallation name="hooks-utils-logger" />

## Usage

```tsx
import { logger } from '@/utils/logger'

const log = logger.create('AUTH')
log.info('User logged in')
```

## API Reference

### Parameters / Props

| Method                     | Description            |
| :------------------------- | :--------------------- |
| `logger.create(namespace)` | Creates scoped logger. |
| `log.info(...args)`        | Info level log.        |
| `log.warn(...args)`        | Warning level log.     |
| `log.error(...args)`       | Error level log.       |

### Return Value

*Logger instance.*


# rangeMap & mapRange
URL: https://www.spaceui.one/hooks/range-map

***

title: rangeMap & mapRange
description: Generates mapped numeric arrays for iterations and maps numbers across ranges with linear interpolation.
preview: demo-h-range-map-01
----------------------------

### Example 2: Linear Range Interpolation (mapRange)

<ComponentPreview name="demo-h-range-map-02" />

## Installation

<ComponentInstallation name="hooks-utils-range-map" />

## Usage

```tsx
import { rangeMap, range, mapRange } from '@/utils/range-map'

rangeMap(5, (i) => i * 2) // => [0, 2, 4, 6, 8]
rangeMap({ n: 3, fn: (i) => i + 1 }) // => [1, 2, 3]
mapRange(0.5, 0, 1, 0, 100) // => 50
```

## API Reference

### Parameters / Props

| Parameter        | Type                           | Default     | Description                            |
| :--------------- | :----------------------------- | :---------- | :------------------------------------- |
| `countOrOptions` | `number \| RangeMapOptions<T>` | *required*  | Total element count or options object. |
| `mapFn`          | `(index: number) => T`         | `undefined` | Optional transformation function.      |

### Return Value

| Return Type | Description                 |
| :---------- | :-------------------------- |
| `T[]`       | Generated and mapped array. |


# RenderAfter
URL: https://www.spaceui.one/hooks/render-after

***

title: RenderAfter
description: Delayed lazy component mounting.
preview: demo-h-render-after-01
-------------------------------

## Installation

<ComponentInstallation name="hooks-components-render-after" />

## Usage

````tsx
import { RenderAfter } from '@/components/render-after'

import { RenderAfter } from '@/components/render-after'```

```tsx
<RenderAfter delay={1000}>
  <Popup />
</RenderAfter>
````

## API Reference

### Parameters / Props

| Prop       | Type        | Default    | Description          |
| :--------- | :---------- | :--------- | :------------------- |
| `delay`    | `number`    | *required* | Delay in ms.         |
| `fallback` | `ReactNode` | `null`     | Loading placeholder. |

### Return Value

| Return Type | Description      |
| :---------- | :--------------- |
| `ReactNode` | Rendered output. |


# Show
URL: https://www.spaceui.one/hooks/show

***

title: Show
description: Truthy conditional renderer that unwraps non-null data directly to children render function.
preview: demo-h-show-01
-----------------------

## Installation

<ComponentInstallation name="hooks-components-show" />

## Usage

````tsx
import { Show } from '@/components/show'

import { Show } from '@/components/show'```

```tsx
<Show when={currentUser} fallback={<p>Logged Out</p>}>
  {(user) => <h1>Hello, {user.name}</h1>}
</Show>
````

## API Reference

### Parameters / Props

| Prop       | Type                                                 | Default    | Description                          |
| :--------- | :--------------------------------------------------- | :--------- | :----------------------------------- |
| `when`     | `T \| null \| undefined \| false`                    | *required* | Condition data.                      |
| `fallback` | `ReactNode`                                          | `null`     | Falsy fallback.                      |
| `children` | `ReactNode \| ((data: NonNullable<T>) => ReactNode)` | *required* | Render callback with unwrapped data. |

### Return Value

| Return Type | Description      |
| :---------- | :--------------- |
| `ReactNode` | Rendered output. |


# sleep
URL: https://www.spaceui.one/hooks/sleep

***

title: sleep
description: Promise-based delay timer.
preview: demo-h-sleep-01
------------------------

## Installation

<ComponentInstallation name="hooks-utils-sleep" />

## Usage

```tsx
import { sleep } from '@/utils/sleep'

await sleep(1000) // delays for 1s
```

## API Reference

### Parameters / Props

| Parameter | Type     | Default    | Description            |
| :-------- | :------- | :--------- | :--------------------- |
| `ms`      | `number` | *required* | Delay in milliseconds. |

### Return Value

| Return Type     | Description           |
| :-------------- | :-------------------- |
| `Promise<void>` | Resolves after delay. |


# Switch
URL: https://www.spaceui.one/hooks/switch

***

title: Switch
description: Pattern-matching conditional container supporting Case and Default branches.
preview: demo-h-switch-01
-------------------------

### Example 2: Order Status Badge Renderer

<ComponentPreview name="demo-h-switch-02" />

## Installation

<ComponentInstallation name="hooks-components-switch" />

## Usage

````tsx
import { Switch, Case, Default } from '@/components/switch'

import { Switch, Case, Default } from '@/components/switch'```

```tsx
<Switch>
  <Case condition={tab === 'home'}>
    <Home />
  </Case>
  <Case condition={tab === 'profile'}>
    <Profile />
  </Case>
  <Default>
    <Settings />
  </Default>
</Switch>
````

## API Reference

### Parameters / Props

| Component     | Prop        | Description                  |
| :------------ | :---------- | :--------------------------- |
| `<Switch />`  | `children`  | Container for Case elements. |
| `<Case />`    | `condition` | Branch condition.            |
| `<Default />` | `children`  | Fallback branch.             |

### Return Value

| Return Type | Description     |
| :---------- | :-------------- |
| `ReactNode` | Matched branch. |


# useAutoHeight
URL: https://www.spaceui.one/hooks/use-auto-height

***

title: useAutoHeight
description: Container height measurement via ResizeObserver and requestAnimationFrame for smooth CSS transitions.
preview: demo-h-auto-height-01
------------------------------

### Example 2: FAQ Accordion Collapse

<ComponentPreview name="demo-h-auto-height-02" />

## Installation

<ComponentInstallation name="hooks-animation-use-auto-height" />

## Usage

```tsx
import * as React from 'react'
import { useAutoHeight } from '@/hooks/use-auto-height'

export default function SpaceUI({ items }: { items: React.ReactNode }) {
  const { ref, height } = useAutoHeight([items])

  return (
    <div style={{ height }}>
      <div ref={ref}>{items}</div>
    </div>
  )
}
```

## API Reference

### Parameters / Props

| Parameter | Type             | Default | Description      |
| :-------- | :--------------- | :------ | :--------------- |
| `deps`    | `DependencyList` | `[]`    | Dependency list. |

### Return Value

| Property | Type                     | Description              |
| :------- | :----------------------- | :----------------------- |
| `ref`    | `RefObject<HTMLElement>` | Inner measurable ref.    |
| `height` | `number`                 | Calculated height in px. |


# useBatteryStatus
URL: https://www.spaceui.one/hooks/use-battery-status

***

title: useBatteryStatus
description: Battery percentage and charging status.
preview: demo-h-battery-status-01
---------------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-battery-status" />

## Usage

```tsx
import { useBatteryStatus } from '@/hooks/use-battery-status'

const { level, charging } = useBatteryStatus()
```

## API Reference

### Parameters / Props

*None*

### Return Value

| Property   | Type      | Description            |
| :--------- | :-------- | :--------------------- |
| `level`    | `number`  | Battery charge 0 to 1. |
| `charging` | `boolean` | Connected to power.    |


# useCharacterLimit
URL: https://www.spaceui.one/hooks/use-character-limit

***

title: useCharacterLimit
description: Enforces maximum input length with live character counter and remaining quota.
preview: demo-h-character-limit-01
----------------------------------

### Example 2: Social Post Composer (Ring Progress)

<ComponentPreview name="demo-h-character-limit-02" />

## Installation

<ComponentInstallation name="hooks-form-use-character-limit" />

## Usage

```tsx
import { useCharacterLimit } from '@/hooks/use-character-limit'

const { value, remaining, percentage, onChange } = useCharacterLimit({ maxLength: 100 })
```

## API Reference

### Parameters / Props

| Parameter           | Type     | Default    | Description |
| :------------------ | :------- | :--------- | :---------- |
| `options.maxLength` | `number` | *required* | Max length. |

### Return Value

| Property     | Type     | Description         |
| :----------- | :------- | :------------------ |
| `value`      | `string` | Current text.       |
| `remaining`  | `number` | Leftover quota.     |
| `percentage` | `number` | Percentage (0-100). |


# useClickOutside
URL: https://www.spaceui.one/hooks/use-click-outside

***

title: useClickOutside
description: Outside click callback trigger.
preview: demo-h-click-outside-01
--------------------------------

## Installation

<ComponentInstallation name="hooks-dom-use-click-outside" />

## Usage

```tsx
import { useClickOutside } from '@/hooks/use-click-outside'

const ref = React.useRef(null)
useClickOutside(ref, () => setOpen(false))
```

## API Reference

### Parameters / Props

| Parameter | Type                     | Default    | Description     |
| :-------- | :----------------------- | :--------- | :-------------- |
| `ref`     | `RefObject<HTMLElement>` | *required* | Target element. |
| `handler` | `(e) => void`            | *required* | Callback.       |

### Return Value

*Returns void.*


# useClipboard
URL: https://www.spaceui.one/hooks/use-clipboard

***

title: useClipboard
description: Copies text to the system clipboard with automatic timeout reset and state feedback.
preview: demo-h-clipboard-01
----------------------------

### Example 2: Code Block with Copy Button

<ComponentPreview name="demo-h-clipboard-02" />

### Example 3: Multi-Credential API Keys

<ComponentPreview name="demo-h-clipboard-03" />

## Installation

<ComponentInstallation name="hooks-browser-use-clipboard" />

## Usage

```tsx
import { useClipboard } from '@/hooks/use-clipboard'

const { copy, copied } = useClipboard({ timeout: 2000 })
copy('Text to copy')
```

## API Reference

### Parameters / Props

| Parameter         | Type     | Default | Description                           |
| :---------------- | :------- | :------ | :------------------------------------ |
| `options.timeout` | `number` | `2000`  | Timeout in ms before `copied` resets. |

### Return Value

| Property | Type                                 | Description                       |
| :------- | :----------------------------------- | :-------------------------------- |
| `copy`   | `(text: string) => Promise<boolean>` | Triggers clipboard copy.          |
| `copied` | `boolean`                            | Whether text was recently copied. |
| `reset`  | `() => void`                         | Resets copied state immediately.  |


# useConfirmExit
URL: https://www.spaceui.one/hooks/use-confirm-exit

***

title: useConfirmExit
description: Unsaved changes tab exit guard.
preview: demo-h-confirm-exit-01
-------------------------------

## Installation

<ComponentInstallation name="hooks-lifecycle-use-confirm-exit" />

## Usage

```tsx
import { useConfirmExit } from '@/hooks/use-confirm-exit'

useConfirmExit(hasUnsavedChanges, 'You have unsaved changes.')
```

## API Reference

### Parameters / Props

| Parameter | Type      | Default     | Description       |
| :-------- | :-------- | :---------- | :---------------- |
| `enabled` | `boolean` | *required*  | Guard state.      |
| `message` | `string`  | `undefined` | Optional message. |

### Return Value

*Returns void.*


# useControlledState
URL: https://www.spaceui.one/hooks/use-controlled-state

***

title: useControlledState
description: Seamless synchronizer for both controlled and uncontrolled component state patterns.
preview: demo-h-controlled-state-01
-----------------------------------

## Installation

<ComponentInstallation name="hooks-animation-use-controlled-state" />

## Usage

```tsx
import { useControlledState } from '@/hooks/use-controlled-state'

// Pattern 1: Object config (Radix / Space UI standard)
const [value, setValue] = useControlledState({
  prop: props.value,
  defaultProp: 'Off',
  onChange: props.onChange,
})

// Pattern 2: Positional arguments
const [value, setValue] = useControlledState(props.value, 'Off', props.onChange)
```

## API Reference

### Parameters / Props

| Parameter             | Type               | Default     | Description                                     |
| :-------------------- | :----------------- | :---------- | :---------------------------------------------- |
| `options.prop`        | `T \| undefined`   | `undefined` | Controlled value passed from parent props.      |
| `options.defaultProp` | `T`                | `undefined` | Default value for uncontrolled usage.           |
| `options.onChange`    | `(val: T) => void` | `undefined` | Optional change callback fired on state update. |

### Return Value

| Property | Type                                   | Description                                                  |
| :------- | :------------------------------------- | :----------------------------------------------------------- |
| `[0]`    | `T`                                    | Current resolved state value.                                |
| `[1]`    | `(val: T \| ((prev: T) => T)) => void` | State updater function (supports value or updater callback). |


# useCookieListener
URL: https://www.spaceui.one/hooks/use-cookie-listener

***

title: useCookieListener
description: Observer callback triggered when a specific cookie value changes.
preview: demo-h-cookie-listener-01
----------------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-cookie-listener" />

## Usage

```tsx
import { useCookieListener } from '@/hooks/use-cookie-listener'

useCookieListener('token', (newToken) => console.log(newToken))
```

## API Reference

### Parameters / Props

| Parameter  | Type                            | Default    | Description         |
| :--------- | :------------------------------ | :--------- | :------------------ |
| `name`     | `string`                        | *required* | Target cookie name. |
| `callback` | `(val: string \| null) => void` | *required* | Change handler.     |

### Return Value

*Returns void.*


# useCookie
URL: https://www.spaceui.one/hooks/use-cookie

***

title: useCookie
description: Reactive cookie reader and setter.
preview: demo-h-use-cookie-01
-----------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-cookie" />

## Usage

```tsx
import { useCookie } from '@/hooks/use-cookie'

const [theme, setTheme, removeTheme] = useCookie('theme', 'dark')
```

## API Reference

### Parameters / Props

| Parameter      | Type     | Default     | Description      |
| :------------- | :------- | :---------- | :--------------- |
| `name`         | `string` | *required*  | Cookie name.     |
| `initialValue` | `string` | `undefined` | Initial default. |

### Return Value

| Return Type                                           | Description         |
| :---------------------------------------------------- | :------------------ |
| `[string \| null, (val: string) => void, () => void]` | Tuple cookie state. |


# useDataState
URL: https://www.spaceui.one/hooks/use-data-state

***

title: useDataState
description: Data attributes state mapper for CSS styling.
preview: demo-h-data-state-01
-----------------------------

## Installation

<ComponentInstallation name="hooks-animation-use-data-state" />

## Usage

```tsx
import { useDataState } from '@/hooks/use-data-state'

const state = useDataState(isOpen) // 'open' | 'closed'
```

## API Reference

### Parameters / Props

| Parameter | Type      | Default    | Description   |
| :-------- | :-------- | :--------- | :------------ |
| `isOpen`  | `boolean` | *required* | Open boolean. |

### Return Value

| Return Type          | Description        |
| :------------------- | :----------------- |
| `'open' \| 'closed'` | Data state string. |


# useDebounce
URL: https://www.spaceui.one/hooks/use-debounce

***

title: useDebounce
description: Debounces fast-changing state values with configurable delay.
preview: demo-h-debounce-01
---------------------------

### Example 2: Real-Time Member Filter

<ComponentPreview name="demo-h-debounce-02" />

## Installation

<ComponentInstallation name="hooks-lifecycle-use-debounce" />

## Usage

```tsx
import { useDebounce } from '@/hooks/use-debounce'

const debounced = useDebounce(query, 400)
```

## API Reference

### Parameters / Props

| Parameter | Type     | Default    | Description        |
| :-------- | :------- | :--------- | :----------------- |
| `value`   | `T`      | *required* | Value to debounce. |
| `delay`   | `number` | `500`      | Delay in ms.       |

### Return Value

| Return Type | Description      |
| :---------- | :--------------- |
| `T`         | Debounced value. |


# useDeviceOS
URL: https://www.spaceui.one/hooks/use-device-os

***

title: useDeviceOS
description: Detects operating system platform.
preview: demo-h-device-os-01
----------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-device-os" />

## Usage

```tsx
import { useDeviceOS } from '@/hooks/use-device-os'

const os = useDeviceOS() // 'macos' | 'windows' | 'ios' | 'android' | 'linux'
```

## API Reference

### Parameters / Props

*None*

### Return Value

| Return Type | Description  |
| :---------- | :----------- |
| `string`    | Detected OS. |


# useEventCallback
URL: https://www.spaceui.one/hooks/use-event-callback

***

title: useEventCallback
description: Stable guaranteed callback reference.
preview: demo-h-event-callback-01
---------------------------------

## Installation

<ComponentInstallation name="hooks-lifecycle-use-event-callback" />

## Usage

```tsx
import { useEventCallback } from '@/hooks/use-event-callback'

const onClick = useEventCallback(() => doSomething(state))
```

## API Reference

### Parameters / Props

| Parameter | Type | Default    | Description        |
| :-------- | :--- | :--------- | :----------------- |
| `fn`      | `T`  | *required* | Callback function. |

### Return Value

| Return Type | Description        |
| :---------- | :----------------- |
| `T`         | Memoized callback. |


# useEventListener
URL: https://www.spaceui.one/hooks/use-event-listener

***

title: useEventListener
description: Declarative event listener binding.
preview: demo-h-event-listener-01
---------------------------------

## Installation

<ComponentInstallation name="hooks-dom-use-event-listener" />

## Usage

```tsx
import { useEventListener } from '@/hooks/use-event-listener'

useEventListener('keydown', (e) => console.log(e.key))
```

## API Reference

### Parameters / Props

| Parameter   | Type       | Default    | Description    |
| :---------- | :--------- | :--------- | :------------- |
| `eventName` | `string`   | *required* | Event name.    |
| `handler`   | `Function` | *required* | Event handler. |

### Return Value

*Returns void.*


# useFileUpload
URL: https://www.spaceui.one/hooks/use-file-upload

***

title: useFileUpload
description: Advanced file upload and dropzone manager with preview generation, size validation, and file type presets.
preview: demo-h-file-upload-01
------------------------------

## Installation

<ComponentInstallation name="hooks-form-use-file-upload" />

## Usage

```tsx
import { useFileUpload } from '@/hooks/use-file-upload'

const { files, isDragging, errors, getRootProps, getInputProps, removeFile, clearFiles } = useFileUpload({
  accept: 'image',
  maxSize: '5MB',
  maxFiles: 3,
})
```

## API Reference

### Parameters / Props

| Parameter          | Type                                   | Default    | Description                                                                   |
| :----------------- | :------------------------------------- | :--------- | :---------------------------------------------------------------------------- |
| `options.accept`   | `string \| string[] \| FileTypePreset` | `'*'`      | Accepted file types or presets (`'image'`, `'video'`, `'pdf'`, `'document'`). |
| `options.maxSize`  | `number \| string`                     | `Infinity` | Maximum file size in bytes or human string (`'5MB'`, `'500KB'`).              |
| `options.maxFiles` | `number`                               | `Infinity` | Maximum number of allowed uploaded files.                                     |
| `options.multiple` | `boolean`                              | `false`    | Enable multi-file selection.                                                  |

### Return Value

| Property          | Type                 | Description                                                                    |
| :---------------- | :------------------- | :----------------------------------------------------------------------------- |
| `files`           | `UploadedFileItem[]` | Array of uploaded files with `id`, `name`, `size`, `type`, and `preview` url.  |
| `isDragging`      | `boolean`            | Whether files are currently dragged over the dropzone.                         |
| `errors`          | `string[]`           | Validation error messages if any.                                              |
| `getRootProps()`  | `Function`           | Dropzone container props (drag events, click handler, keyboard accessibility). |
| `getInputProps()` | `Function`           | Hidden `<input type="file" />` props and ref binder.                           |
| `removeFile(id)`  | `Function`           | Removes a file from the list by ID.                                            |
| `clearFiles()`    | `Function`           | Clears all uploaded files and revokes preview URLs.                            |


# useFirstRender
URL: https://www.spaceui.one/hooks/use-first-render

***

title: useFirstRender
description: First render cycle indicator.
preview: demo-h-first-render-01
-------------------------------

## Installation

<ComponentInstallation name="hooks-lifecycle-use-first-render" />

## Usage

```tsx
import { useFirstRender } from '@/hooks/use-first-render'

const isFirst = useFirstRender()
```

## API Reference

### Parameters / Props

*None*

### Return Value

| Return Type | Description                 |
| :---------- | :-------------------------- |
| `boolean`   | True only on initial mount. |


# useFirstVisit
URL: https://www.spaceui.one/hooks/use-first-visit

***

title: useFirstVisit
description: First user session identifier.
preview: demo-h-first-visit-01
------------------------------

## Installation

<ComponentInstallation name="hooks-lifecycle-use-first-visit" />

## Usage

```tsx
import { useFirstVisit } from '@/hooks/use-first-visit'

const isFirst = useFirstVisit('welcome_popup')
```

## API Reference

### Parameters / Props

| Parameter | Type     | Default    | Description |
| :-------- | :------- | :--------- | :---------- |
| `key`     | `string` | *required* | Visit key.  |

### Return Value

| Return Type | Description          |
| :---------- | :------------------- |
| `boolean`   | True on first visit. |


# useFullscreen
URL: https://www.spaceui.one/hooks/use-fullscreen

***

title: useFullscreen
description: Element fullscreen mode controller.
preview: demo-h-fullscreen-01
-----------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-fullscreen" />

## Usage

```tsx
import { useFullscreen } from '@/hooks/use-fullscreen'

const ref = React.useRef(null)
const { isFullscreen, toggle } = useFullscreen(ref)
```

## API Reference

### Parameters / Props

| Parameter   | Type                     | Default                    | Description     |
| :---------- | :----------------------- | :------------------------- | :-------------- |
| `targetRef` | `RefObject<HTMLElement>` | `document.documentElement` | Target element. |

### Return Value

| Property       | Type         | Description         |
| :------------- | :----------- | :------------------ |
| `isFullscreen` | `boolean`    | Fullscreen state.   |
| `toggle`       | `() => void` | Toggles fullscreen. |


# useHold
URL: https://www.spaceui.one/hooks/use-hold

***

title: useHold
description: Long-press hold gesture detector.
preview: demo-h-hold-01
-----------------------

## Installation

<ComponentInstallation name="hooks-lifecycle-use-hold" />

## Usage

```tsx
import { useHold } from '@/hooks/use-hold'

export default function SpaceUI({ onDelete }: { onDelete: () => void }) {
  const bind = useHold(() => onDelete(), { delay: 600 })

  return <button {...bind}>Hold to delete</button>
}
```

## API Reference

### Parameters / Props

| Parameter       | Type         | Default    | Description      |
| :-------------- | :----------- | :--------- | :--------------- |
| `callback`      | `() => void` | *required* | Action callback. |
| `options.delay` | `number`     | `500`      | Hold duration.   |

### Return Value

| Return Type      | Description         |
| :--------------- | :------------------ |
| `HTMLAttributes` | DOM event bindings. |


# useHover
URL: https://www.spaceui.one/hooks/use-hover

***

title: useHover
description: Observes mouse hover state on target DOM elements using either automatic ref tuples or external refs.
preview: demo-h-hover-01
------------------------

### Example 2: External Ref Passing

<ComponentPreview name="demo-h-hover-02" />

## Installation

<ComponentInstallation name="hooks-dom-use-hover" />

## Usage

```tsx
import { useHover } from '@/hooks/use-hover'

// Pattern 1: Automatic Ref Tuple
const [ref, isHovered] = useHover<HTMLDivElement>()

// Pattern 2: External Ref Passing
const buttonRef = useRef<HTMLButtonElement>(null)
const isHovered = useHover(buttonRef)
```

## API Reference

### Parameters / Props

| Parameter    | Type                             | Default     | Description                           |
| :----------- | :------------------------------- | :---------- | :------------------------------------ |
| `elementRef` | `RefObject<HTMLElement \| null>` | `undefined` | Optional external React ref to watch. |

### Return Value

| Return Type                                    | Description                                             |
| :--------------------------------------------- | :------------------------------------------------------ |
| `[RefObject<T>, boolean] & { ref, isHovered }` | Returned when called with no arguments (`useHover()`).  |
| `boolean`                                      | Returned when passed an external ref (`useHover(ref)`). |


# useIdle
URL: https://www.spaceui.one/hooks/use-idle

***

title: useIdle
description: User inactivity timeout monitor.
preview: demo-h-idle-01
-----------------------

## Installation

<ComponentInstallation name="hooks-lifecycle-use-idle" />

## Usage

```tsx
import { useIdle } from '@/hooks/use-idle'

const isIdle = useIdle(5000)
```

## API Reference

### Parameters / Props

| Parameter | Type     | Default | Description           |
| :-------- | :------- | :------ | :-------------------- |
| `timeout` | `number` | `60000` | Idle threshold in ms. |

### Return Value

| Return Type | Description   |
| :---------- | :------------ |
| `boolean`   | True if idle. |


# useInView
URL: https://www.spaceui.one/hooks/use-in-view

***

title: useInView
description: Tracks viewport intersection with IntersectionObserver.
preview: demo-h-use-in-view-01
------------------------------

## Installation

<ComponentInstallation name="hooks-animation-use-in-view" />

## Usage

```tsx
import { useInView } from '@/hooks/use-in-view'

const [ref, inView] = useInView({ threshold: 0.5 })
```

## API Reference

### Parameters / Props

| Parameter           | Type     | Default | Description      |
| :------------------ | :------- | :------ | :--------------- |
| `options.threshold` | `number` | `0`     | Ratio threshold. |

### Return Value

| Return Type                                           | Description  |
| :---------------------------------------------------- | :----------- |
| `[RefObject<T>, boolean, IntersectionObserverEntry?]` | State tuple. |


# useInputValue
URL: https://www.spaceui.one/hooks/use-input-value

***

title: useInputValue
description: Unified form input and textarea value binder supporting tuple destructuring, object spreading, and reset/clear actions.
preview: demo-h-input-value-01
------------------------------

## Installation

<ComponentInstallation name="hooks-form-use-input-value" />

## Usage

```tsx
import { useInputValue } from '@/hooks/use-input-value'

export default function SpaceUI() {
  // Pattern 1: Tuple destructuring with binder
  const [value, bind, { reset, clear }] = useInputValue('Space UI')

  return <input {...bind} />
}
```

## API Reference

### Parameters / Props

| Parameter      | Type     | Default | Description                       |
| :------------- | :------- | :------ | :-------------------------------- |
| `initialValue` | `string` | `''`    | Initial text value for the input. |

### Return Value

| Property           | Type                         | Description                                                     |
| :----------------- | :--------------------------- | :-------------------------------------------------------------- |
| `[0]` (or `value`) | `string`                     | Current string value.                                           |
| `[1]` (or `bind`)  | `{ value, onChange }`        | Ready-to-spread props object for `<input />` or `<textarea />`. |
| `[2]`              | `{ setValue, reset, clear }` | Action helpers object.                                          |
| `onChange`         | `Function`                   | React change event handler.                                     |
| `reset()`          | `Function`                   | Resets field to `initialValue`.                                 |
| `clear()`          | `Function`                   | Clears field to empty string.                                   |


# useIntersectionObserver
URL: https://www.spaceui.one/hooks/use-intersection-observer

***

title: useIntersectionObserver
description: Advanced IntersectionObserver hook.
preview: demo-h-intersection-observer-01
----------------------------------------

## Installation

<ComponentInstallation name="hooks-dom-use-intersection-observer" />

## Usage

```tsx
import { useIntersectionObserver } from '@/hooks/use-intersection-observer'

const [ref, entry] = useIntersectionObserver({ threshold: 0.5 })
```

## API Reference

### Parameters / Props

| Parameter | Type                       | Default        | Description              |
| :-------- | :------------------------- | :------------- | :----------------------- |
| `options` | `IntersectionObserverInit` | `&#123;&#125;` | Native observer options. |

### Return Value

| Return Type                                              | Description    |
| :------------------------------------------------------- | :------------- |
| `[RefObject<T>, IntersectionObserverEntry \| undefined]` | Ref and entry. |


# useInterval
URL: https://www.spaceui.one/hooks/use-interval

***

title: useInterval
description: Declarative timer with start, pause, and dynamic delay controls.
preview: demo-h-interval-01
---------------------------

### Example 2: Server Polling Simulator

<ComponentPreview name="demo-h-interval-02" />

## Installation

<ComponentInstallation name="hooks-lifecycle-use-interval" />

## Usage

```tsx
import { useInterval } from '@/hooks/use-interval'

const { start, stop } = useInterval(() => tick(), 1000)
```

## API Reference

### Parameters / Props

| Parameter  | Type             | Default    | Description    |
| :--------- | :--------------- | :--------- | :------------- |
| `callback` | `() => void`     | *required* | Tick function. |
| `delay`    | `number \| null` | `null`     | Delay in ms.   |

### Return Value

| Property | Type                       | Description      |
| :------- | :------------------------- | :--------------- |
| `start`  | `(delay?: number) => void` | Starts interval. |
| `stop`   | `() => void`               | Pauses interval. |


# useIsMac
URL: https://www.spaceui.one/hooks/use-is-mac

***

title: useIsMac
description: macOS platform detector for keyboard shortcut mappings.
preview: demo-h-is-mac-01
-------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-is-mac" />

## Usage

```tsx
import { useIsMac } from '@/hooks/use-is-mac'

const isMac = useIsMac()
```

## API Reference

### Parameters / Props

*None*

### Return Value

| Return Type | Description    |
| :---------- | :------------- |
| `boolean`   | True on macOS. |


# useIsMounted
URL: https://www.spaceui.one/hooks/use-is-mounted

***

title: useIsMounted
description: Check component mount state.
preview: demo-h-is-mounted-01
-----------------------------

## Installation

<ComponentInstallation name="hooks-lifecycle-use-is-mounted" />

## Usage

```tsx
import { useIsMounted } from '@/hooks/use-is-mounted'

const isMounted = useIsMounted()
if (isMounted()) updateState()
```

## API Reference

### Parameters / Props

*None*

### Return Value

| Return Type     | Description                       |
| :-------------- | :-------------------------------- |
| `() => boolean` | Function returning mount boolean. |


# useIsomorphicLayoutEffect
URL: https://www.spaceui.one/hooks/use-isomorphic-layout-effect

***

title: useIsomorphicLayoutEffect
description: SSR-safe layout effect using useEffect on server and useLayoutEffect on client.
preview: demo-h-isomorphic-layout-effect-01
-------------------------------------------

## Installation

<ComponentInstallation name="hooks-lifecycle-use-isomorphic-layout-effect" />

## Usage

```tsx
import { useIsomorphicLayoutEffect } from '@/hooks/use-isomorphic-layout-effect'

useIsomorphicLayoutEffect(() => {
  /* measurement */
}, [])
```

## API Reference

### Parameters / Props

Standard useEffect signature.

### Return Value

*Returns void.*


# useKeyPress
URL: https://www.spaceui.one/hooks/use-key-press

***

title: useKeyPress
description: Detect active pressed keyboard keys.
preview: demo-h-key-press-01
----------------------------

## Installation

<ComponentInstallation name="hooks-dom-use-key-press" />

## Usage

```tsx
import { useKeyPress } from '@/hooks/use-key-press'

const isEscape = useKeyPress('Escape')
```

## API Reference

### Parameters / Props

| Parameter   | Type     | Default    | Description |
| :---------- | :------- | :--------- | :---------- |
| `targetKey` | `string` | *required* | Key name.   |

### Return Value

| Return Type | Description         |
| :---------- | :------------------ |
| `boolean`   | True while pressed. |


# useLeaveDetection
URL: https://www.spaceui.one/hooks/use-leave-detection

***

title: useLeaveDetection
description: Comprehensive exit-intent, viewport boundary exit, split-screen window blur, and tab visibility switch detection.
preview: demo-h-leave-detection-01
----------------------------------

## Installation

<ComponentInstallation name="hooks-lifecycle-use-leave-detection" />

## Usage

```tsx
import { useLeaveDetection } from '@/hooks/use-leave-detection'

// Pattern 1: Reactive state & options
const { isOutside, leaveCount, direction, reset } = useLeaveDetection({
  detectBlur: true,
  detectVisibility: true,
  onLeave: (dir) => console.log('User left from:', dir),
  onEnter: () => console.log('User returned to window'),
})

// Pattern 2: Direct callback
useLeaveDetection(() => {
  openDiscountModal()
})
```

## API Reference

### Parameters / Props

| Parameter                  | Type                           | Default     | Description                                                           |
| :------------------------- | :----------------------------- | :---------- | :-------------------------------------------------------------------- |
| `options.detectBlur`       | `boolean`                      | `true`      | Detects window blur (e.g. clicking into another app in split screen). |
| `options.detectVisibility` | `boolean`                      | `true`      | Detects tab switching via Page Visibility API.                        |
| `options.once`             | `boolean`                      | `false`     | Trigger the exit handler only once.                                   |
| `options.onLeave`          | `(dir: ExitDirection) => void` | `undefined` | Callback fired when the user leaves.                                  |
| `options.onEnter`          | `() => void`                   | `undefined` | Callback fired when the user returns.                                 |

### Return Value

| Property     | Type                                                                         | Description                                                       |
| :----------- | :--------------------------------------------------------------------------- | :---------------------------------------------------------------- |
| `isOutside`  | `boolean`                                                                    | `true` while the user is outside the window or focused elsewhere. |
| `hasLeft`    | `boolean`                                                                    | `true` if the user has left at least once.                        |
| `leaveCount` | `number`                                                                     | Total number of exit events detected.                             |
| `direction`  | `'top' \| 'bottom' \| 'left' \| 'right' \| 'blur' \| 'visibility' \| 'none'` | Last exit origin.                                                 |
| `reset()`    | `Function`                                                                   | Resets exit states and triggers.                                  |


# useLoadMore
URL: https://www.spaceui.one/hooks/use-load-more

***

title: useLoadMore
description: Universal pagination and load-more trigger supporting async data fetchers and client-side array batching.
preview: demo-h-load-more-01
----------------------------

## Installation

<ComponentInstallation name="hooks-form-use-load-more" />

## Usage

```tsx
import { useLoadMore } from '@/hooks/use-load-more'

// Pattern 1: Async loader function
const { loading, trigger, page } = useLoadMore(async (pageNumber) => {
  await fetchArticles(pageNumber)
})

// Pattern 2: Client-side array slicing
const { data, loadMore, loading, hasMore } = useLoadMore({
  dataSource: allProducts,
  initialCount: 6,
  incrementCount: 6,
})
```

## API Reference

### Parameters / Props

| Parameter                | Type                             | Default     | Description                          |
| :----------------------- | :------------------------------- | :---------- | :----------------------------------- |
| `fetcher`                | `(page: number) => Promise<any>` | `undefined` | Async loader callback function.      |
| `options.dataSource`     | `T[]`                            | `undefined` | Array to paginate client-side.       |
| `options.initialCount`   | `number`                         | `3`         | Initial number of items to display.  |
| `options.incrementCount` | `number`                         | `3`         | Number of items to add on each load. |

### Return Value

| Property   | Type                  | Description                                                         |
| :--------- | :-------------------- | :------------------------------------------------------------------ |
| `loading`  | `boolean`             | Whether data loading is currently in progress (alias: `isLoading`). |
| `loadMore` | `() => Promise<void>` | Triggers the next batch or fetcher call (alias: `trigger`).         |
| `hasMore`  | `boolean`             | Whether more items are available.                                   |
| `data`     | `T[]`                 | Currently visible items (when using `dataSource`).                  |
| `page`     | `number`              | Current page number.                                                |
| `reset()`  | `Function`            | Resets pagination state to initial values.                          |


# useLocalStorage
URL: https://www.spaceui.one/hooks/use-local-storage

***

title: useLocalStorage
description: Synchronizes state with window\.localStorage across tabs.
preview: demo-h-local-storage-01
--------------------------------

### Example 2: Form Settings Object

<ComponentPreview name="demo-h-local-storage-02" />

### Example 3: Persistent Todo List

<ComponentPreview name="demo-h-local-storage-03" />

## Installation

<ComponentInstallation name="hooks-browser-use-local-storage" />

## Usage

```tsx
import { useLocalStorage } from '@/hooks/use-local-storage'

const [count, setCount, remove] = useLocalStorage('key', 0)
```

## API Reference

### Parameters / Props

| Parameter      | Type     | Default    | Description     |
| :------------- | :------- | :--------- | :-------------- |
| `key`          | `string` | *required* | Storage key.    |
| `initialValue` | `T`      | *required* | Fallback value. |

### Return Value

| Return Type                         | Description                 |
| :---------------------------------- | :-------------------------- |
| `[T, (val: T) => void, () => void]` | Value, setter, and remover. |


# useLockBodyScroll
URL: https://www.spaceui.one/hooks/use-lock-body-scroll

***

title: useLockBodyScroll
description: Locks page scrolling without layout shift.
preview: demo-h-lock-body-scroll-01
-----------------------------------

## Installation

<ComponentInstallation name="hooks-dom-use-lock-body-scroll" />

## Usage

```tsx
import { useLockBodyScroll } from '@/hooks/use-lock-body-scroll'

const { isLocked, toggle } = useLockBodyScroll(false)
```

## API Reference

### Parameters / Props

| Parameter       | Type      | Default | Description    |
| :-------------- | :-------- | :------ | :------------- |
| `initialLocked` | `boolean` | `true`  | Initial state. |

### Return Value

| Property   | Type         | Description   |
| :--------- | :----------- | :------------ |
| `isLocked` | `boolean`    | Locked state. |
| `toggle`   | `() => void` | Toggles lock. |


# useMap
URL: https://www.spaceui.one/hooks/use-map

***

title: useMap
description: Reactive Map collection state manager.
preview: demo-h-map-01
----------------------

## Installation

<ComponentInstallation name="hooks-form-use-map" />

## Usage

```tsx
import { useMap } from '@/hooks/use-map'

const [map, actions] = useMap([['key', 'val']])
actions.set('key', 'newVal')
```

## API Reference

### Parameters / Props

| Parameter        | Type       | Default | Description    |
| :--------------- | :--------- | :------ | :------------- |
| `initialEntries` | `[K, V][]` | `[]`    | Initial pairs. |

### Return Value

| Property  | Type        | Description                    |
| :-------- | :---------- | :----------------------------- |
| `map`     | `Map<K, V>` | Reactive Map instance.         |
| `actions` | `Object`    | `set`, `delete`, `clear`, etc. |


# useMediaQuery
URL: https://www.spaceui.one/hooks/use-media-query

***

title: useMediaQuery
description: Evaluates CSS media queries with useSyncExternalStore for zero layout shift.
preview: demo-h-media-query-01
------------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-media-query" />

## Usage

```tsx
import { useMediaQuery } from '@/hooks/use-media-query'

const isMobile = useMediaQuery('(max-width: 640px)')
```

## API Reference

### Parameters / Props

| Parameter | Type     | Default    | Description             |
| :-------- | :------- | :--------- | :---------------------- |
| `query`   | `string` | *required* | CSS media query string. |

### Return Value

| Return Type | Description            |
| :---------- | :--------------------- |
| `boolean`   | True if query matches. |


# useMotionValueState
URL: https://www.spaceui.one/hooks/use-motion-value-state

***

title: useMotionValueState
description: Framer Motion value reactive state subscriber.
preview: demo-h-motion-value-state-01
-------------------------------------

## Installation

<ComponentInstallation name="hooks-animation-use-motion-value-state" />

## Usage

```tsx
import { useMotionValueState } from '@/hooks/use-motion-value-state'

const currentVal = useMotionValueState(motionVal)
```

## API Reference

### Parameters / Props

| Parameter     | Type             | Default    | Description   |
| :------------ | :--------------- | :--------- | :------------ |
| `motionValue` | `MotionValue<T>` | *required* | Motion value. |

### Return Value

| Return Type | Description     |
| :---------- | :-------------- |
| `T`         | Reactive value. |


# useMousePosition
URL: https://www.spaceui.one/hooks/use-mouse-position

***

title: useMousePosition
description: Tracks real-time cursor coordinates.
preview: demo-h-mouse-position-01
---------------------------------

## Installation

<ComponentInstallation name="hooks-dom-use-mouse-position" />

## Usage

```tsx
import { useMousePosition } from '@/hooks/use-mouse-position'

const { x, y } = useMousePosition()
```

## API Reference

### Parameters / Props

*None*

### Return Value

| Property | Type     | Description             |
| :------- | :------- | :---------------------- |
| `x`      | `number` | X coordinate in pixels. |
| `y`      | `number` | Y coordinate in pixels. |


# useMutation
URL: https://www.spaceui.one/hooks/use-mutation

***

title: useMutation
description: Robust async mutation runner with loading, success, error tracking, and lifecycle callbacks.
preview: demo-h-mutation-01
---------------------------

## Installation

<ComponentInstallation name="hooks-form-use-mutation" />

## Usage

```tsx
import { useMutation } from '@/hooks/use-mutation'

const { mutate, mutateAsync, loading, data, error, isSuccess, isError, reset } = useMutation(
  async (payload) => {
    return await api.createRecord(payload)
  },
  {
    onSuccess: (data) => console.log('Saved:', data),
    onError: (err) => console.error('Failed:', err),
  },
)

// Trigger mutation
mutate({ name: 'New Item' })
```

## API Reference

### Parameters / Props

| Parameter           | Type                                                | Default     | Description                                  |
| :------------------ | :-------------------------------------------------- | :---------- | :------------------------------------------- |
| `mutationFn`        | `(variables: TVariables) => Promise<TData>`         | *required*  | Async operation to execute.                  |
| `options.onSuccess` | `(data: TData, variables: TVariables) => void`      | `undefined` | Success callback.                            |
| `options.onError`   | `(error: any, variables: TVariables) => void`       | `undefined` | Error callback.                              |
| `options.onSettled` | `(data: TData \| null, error: any \| null) => void` | `undefined` | Settled callback (runs on success or error). |

### Return Value

| Property                 | Type            | Description                                                          |
| :----------------------- | :-------------- | :------------------------------------------------------------------- |
| `mutate(variables)`      | `Function`      | Triggers the mutation safely without throwing unhandled exceptions.  |
| `mutateAsync(variables)` | `Function`      | Triggers the mutation and returns a Promise that rejects on error.   |
| `loading`                | `boolean`       | Whether mutation is currently executing (alias: `isLoading`).        |
| `data`                   | `TData \| null` | Resolved data from the last successful mutation (alias: `response`). |
| `error`                  | `any \| null`   | Error object if mutation rejected.                                   |
| `isSuccess`              | `boolean`       | `true` if last mutation succeeded.                                   |
| `isError`                | `boolean`       | `true` if last mutation threw an error.                              |
| `isIdle`                 | `boolean`       | `true` before any mutation has executed.                             |
| `reset()`                | `Function`      | Resets all mutation state back to idle.                              |


# useNetwork
URL: https://www.spaceui.one/hooks/use-network

***

title: useNetwork
description: Real-time network connection monitor providing online/offline state and bandwidth.
preview: demo-h-network-01
--------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-network" />

## Usage

```tsx
import { useNetwork } from '@/hooks/use-network'

const { isOnline, downlink, effectiveType } = useNetwork()
```

## API Reference

### Parameters / Props

*None*

### Return Value

| Property        | Type                  | Description                |
| :-------------- | :-------------------- | :------------------------- |
| `isOnline`      | `boolean`             | Internet connection state. |
| `downlink`      | `number \| undefined` | Bandwidth in Mbps.         |
| `effectiveType` | `string \| undefined` | Connection tier.           |


# useOrientation
URL: https://www.spaceui.one/hooks/use-orientation

***

title: useOrientation
description: Screen orientation angles and type.
preview: demo-h-orientation-01
------------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-orientation" />

## Usage

```tsx
import { useOrientation } from '@/hooks/use-orientation'

const { angle, type } = useOrientation()
```

## API Reference

### Parameters / Props

*None*

### Return Value

| Property | Type     | Description              |
| :------- | :------- | :----------------------- |
| `angle`  | `number` | Angle in degrees.        |
| `type`   | `string` | 'portrait-primary', etc. |


# usePagination
URL: https://www.spaceui.one/hooks/use-pagination

***

title: usePagination
description: Smart pagination calculation with dynamic range arrays, boundary and sibling pages, and navigation controls.
preview:
name: demo-h-pagination-01
contained: false
----------------

## Installation

<ComponentInstallation name="hooks-form-use-pagination" />

## Usage

```tsx
import { usePagination } from '@/hooks/use-pagination'

const {
  page,
  setPage,
  totalPages,
  range,
  startIndex,
  endIndex,
  nextPage,
  prevPage,
  firstPage,
  lastPage,
  hasNext,
  hasPrev,
} = usePagination({
  total: 100,
  pageSize: 10,
  initialPage: 1,
  siblings: 1,
})
```

## API Reference

### Parameters / Props

| Parameter             | Type     | Default | Description                                                        |
| :-------------------- | :------- | :------ | :----------------------------------------------------------------- |
| `options.total`       | `number` | `0`     | Total number of items in the dataset (alias: `totalItems`).        |
| `options.pageSize`    | `number` | `10`    | Number of items displayed per page.                                |
| `options.initialPage` | `number` | `1`     | Initial active page (1-indexed).                                   |
| `options.siblings`    | `number` | `1`     | Number of sibling buttons visible on each side of the active page. |
| `options.boundaries`  | `number` | `1`     | Number of boundary page buttons visible at start and end.          |

### Return Value

| Property      | Type                  | Description                                                              |
| :------------ | :-------------------- | :----------------------------------------------------------------------- |
| `page`        | `number`              | Current active page (alias: `currentPage`).                              |
| `totalPages`  | `number`              | Total number of calculated pages.                                        |
| `range`       | `(number \| '...')[]` | Array of page numbers and ellipsis tokens for rendering pagination bars. |
| `startIndex`  | `number`              | Zero-based starting index for the current page slice.                    |
| `endIndex`    | `number`              | Zero-based ending index for the current page slice.                      |
| `nextPage()`  | `Function`            | Advances to next page (alias: `next`).                                   |
| `prevPage()`  | `Function`            | Returns to previous page (alias: `prev`).                                |
| `firstPage()` | `Function`            | Jumps to first page.                                                     |
| `lastPage()`  | `Function`            | Jumps to last page.                                                      |
| `setPage(p)`  | `Function`            | Directly sets active page.                                               |
| `hasNext`     | `boolean`             | Whether a next page exists.                                              |
| `hasPrev`     | `boolean`             | Whether a previous page exists.                                          |


# useParseMarkdown
URL: https://www.spaceui.one/hooks/use-parse-markdown

***

title: useParseMarkdown
description: Fast client-side markdown compiler.
preview: demo-h-parse-markdown-01
---------------------------------

## Installation

<ComponentInstallation name="hooks-form-use-parse-markdown" />

## Usage

```tsx
import { useParseMarkdown } from '@/hooks/use-parse-markdown'

const html = useParseMarkdown('# Hello Markdown')
```

## API Reference

### Parameters / Props

| Parameter  | Type     | Default    | Description      |
| :--------- | :------- | :--------- | :--------------- |
| `markdown` | `string` | *required* | Markdown string. |

### Return Value

| Return Type | Description           |
| :---------- | :-------------------- |
| `string`    | Compiled HTML string. |


# usePerformanceMode
URL: https://www.spaceui.one/hooks/use-performance-mode

***

title: usePerformanceMode
description: Battery/CPU low-power mode optimizer.
preview: demo-h-performance-mode-01
-----------------------------------

## Installation

<ComponentInstallation name="hooks-lifecycle-use-performance-mode" />

## Usage

```tsx
import { usePerformanceMode } from '@/hooks/use-performance-mode'

const isEco = usePerformanceMode()
```

## API Reference

### Parameters / Props

*None*

### Return Value

| Return Type | Description                    |
| :---------- | :----------------------------- |
| `boolean`   | True if in eco/low-power mode. |


# usePrefersTheme
URL: https://www.spaceui.one/hooks/use-prefers-theme

***

title: usePrefersTheme
description: System color scheme detector.
preview: demo-h-prefers-theme-01
--------------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-prefers-theme" />

## Usage

```tsx
import { usePrefersTheme } from '@/hooks/use-prefers-theme'

const theme = usePrefersTheme() // 'dark' | 'light'
```

## API Reference

### Parameters / Props

*None*

### Return Value

| Return Type         | Description   |
| :------------------ | :------------ |
| `'dark' \| 'light'` | System theme. |


# useReadingTime
URL: https://www.spaceui.one/hooks/use-reading-time

***

title: useReadingTime
description: Real-time article reading time calculator with CJK multilingual support, Markdown/HTML stripping, and code/image weighting.
preview: demo-h-reading-time-01
-------------------------------

## Installation

<ComponentInstallation name="hooks-form-use-reading-time" />

## Usage

```tsx
import { useReadingTime, formatTime } from '@/hooks/use-reading-time'

const stats = useReadingTime(articleContent, {
  wordsPerMinute: 200,
  includeImages: true,
  includeCodeBlocks: true,
})

const formatted = formatTime(stats, 'short') // "2m 15s"
```

## API Reference

### Parameters / Props

| Parameter                   | Type      | Default | Description                                     |
| :-------------------------- | :-------- | :------ | :---------------------------------------------- |
| `content`                   | `string`  | `''`    | Raw text, Markdown, or HTML content to analyze. |
| `options.wordsPerMinute`    | `number`  | `200`   | Average reading speed in words per minute.      |
| `options.includeImages`     | `boolean` | `true`  | Add extra reading weight for image elements.    |
| `options.includeCodeBlocks` | `boolean` | `true`  | Weight code block tokens.                       |

### Return Value

| Property       | Type     | Description                        |
| :------------- | :------- | :--------------------------------- |
| `minutes`      | `number` | Integer minutes portion.           |
| `seconds`      | `number` | Remaining seconds portion.         |
| `totalSeconds` | `number` | Total duration in seconds.         |
| `wordCount`    | `number` | Total word count (alias: `words`). |
| `imageCount`   | `number` | Detected image tag count.          |


# useSanitizeContent
URL: https://www.spaceui.one/hooks/use-sanitize-content

***

title: useSanitizeContent
description: SSR-safe HTML sanitizer that strips XSS threats while preserving rich formatting.
preview: demo-h-sanitize-content-01
-----------------------------------

## Installation

<ComponentInstallation name="hooks-form-use-sanitize-content" />

## Usage

```tsx
import { useSanitizeContent } from '@/hooks/use-sanitize-content'

const safeHtml = useSanitizeContent('<p>Safe content</p><script>alert(1)</script>')
```

## API Reference

### Parameters / Props

| Parameter | Type                                          | Default    | Description |
| :-------- | :-------------------------------------------- | :--------- | :---------- |
| `input`   | `string \| &#123; description: string &#125;` | *required* | Dirty HTML. |

### Return Value

| Return Type | Description                  |
| :---------- | :--------------------------- |
| `string`    | Clean, XSS-safe HTML string. |


# useScript
URL: https://www.spaceui.one/hooks/use-script

***

title: useScript
description: Dynamic script loader with load status.
preview: demo-h-script-01
-------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-script" />

## Usage

```tsx
import { useScript } from '@/hooks/use-script'

const status = useScript('https://example.com/lib.js')
```

## API Reference

### Parameters / Props

| Parameter | Type     | Default    | Description |
| :-------- | :------- | :--------- | :---------- |
| `src`     | `string` | *required* | Script URL. |

### Return Value

| Return Type                                 | Description     |
| :------------------------------------------ | :-------------- |
| `'idle' \| 'loading' \| 'ready' \| 'error'` | Loading status. |


# useScrollDevice
URL: https://www.spaceui.one/hooks/use-scroll-device

***

title: useScrollDevice
description: Real-time 8-directional scroll detection (cardinal & diagonal) with hardware gesture recognition (touchpad 2D swipe, mouse wheel, touch, keyboard).
preview: demo-h-scroll-device-01
--------------------------------

## Installation

<ComponentInstallation name="hooks-dom-use-scroll-device" />

## Usage

```tsx
import { useScrollDevice } from '@/hooks/use-scroll-device'

const {
  device,
  direction,
  directionX,
  directionY,
  isScrolling,
  isDiagonal,
  isScrollingUp,
  isScrollingDown,
  isScrollingLeft,
  isScrollingRight,
  deltaX,
  deltaY,
} = useScrollDevice({ threshold: 3, idleTimeout: 250 })
```

## API Reference

### Parameters / Props

| Parameter             | Type     | Default | Description                                                                |
| :-------------------- | :------- | :------ | :------------------------------------------------------------------------- |
| `options.threshold`   | `number` | `3`     | Minimum delta in pixels before triggering direction change.                |
| `options.idleTimeout` | `number` | `250`   | Inactivity delay in milliseconds before resetting scrolling state to idle. |

### Return Value

| Property           | Type                                                                                                      | Description                                                       |
| :----------------- | :-------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |
| `device`           | `'wheel' \| 'touchpad' \| 'touch' \| 'keyboard' \| null`                                                  | Detected user input method.                                       |
| `direction`        | `'up' \| 'down' \| 'left' \| 'right' \| 'up-left' \| 'up-right' \| 'down-left' \| 'down-right' \| 'none'` | Real-time 8-directional compass direction.                        |
| `directionX`       | `'left' \| 'right' \| 'none'`                                                                             | Horizontal scroll axis direction.                                 |
| `directionY`       | `'up' \| 'down' \| 'none'`                                                                                | Vertical scroll axis direction.                                   |
| `isDiagonal`       | `boolean`                                                                                                 | `true` when simultaneous X & Y scrolling occurs.                  |
| `isScrolling`      | `boolean`                                                                                                 | `true` while gesture or scrolling is active.                      |
| `isScrollingUp`    | `boolean`                                                                                                 | `true` when scrolling upwards (includes up-left, up-right).       |
| `isScrollingDown`  | `boolean`                                                                                                 | `true` when scrolling downwards (includes down-left, down-right). |
| `isScrollingLeft`  | `boolean`                                                                                                 | `true` when scrolling leftwards.                                  |
| `isScrollingRight` | `boolean`                                                                                                 | `true` when scrolling rightwards.                                 |
| `deltaX`           | `number`                                                                                                  | Real-time pixel delta on horizontal axis.                         |
| `deltaY`           | `number`                                                                                                  | Real-time pixel delta on vertical axis.                           |


# useScrollPosition
URL: https://www.spaceui.one/hooks/use-scroll-position

***

title: useScrollPosition
description: Real-time window or element scroll offset coordinates (X and Y).
preview: demo-h-scroll-position-01
----------------------------------

## Installation

<ComponentInstallation name="hooks-dom-use-scroll-position" />

## Usage

```tsx
import { useScrollPosition } from '@/hooks/use-scroll-position'

// Pattern 1: Object destructuring with scrollX / scrollY
const { scrollX, scrollY } = useScrollPosition()

// Pattern 2: Object destructuring with x / y
const { x, y } = useScrollPosition()

// Pattern 3: Array tuple destructuring
const [x, y] = useScrollPosition()

// Pattern 4: Target container element
const containerRef = useRef<HTMLDivElement>(null)
const { scrollY } = useScrollPosition(containerRef)
```

## API Reference

### Parameters / Props

| Parameter   | Type                             | Default     | Description                                                |
| :---------- | :------------------------------- | :---------- | :--------------------------------------------------------- |
| `targetRef` | `RefObject<HTMLElement \| null>` | `undefined` | Optional DOM element ref to measure instead of the window. |

### Return Value

| Property  | Type     | Description                                              |
| :-------- | :------- | :------------------------------------------------------- |
| `scrollX` | `number` | Horizontal scroll offset in pixels (alias: `x` / `[0]`). |
| `scrollY` | `number` | Vertical scroll offset in pixels (alias: `y` / `[1]`).   |
| `x`       | `number` | Horizontal coordinate.                                   |
| `y`       | `number` | Vertical coordinate.                                     |


# useScrollTo
URL: https://www.spaceui.one/hooks/use-scroll-to

***

title: useScrollTo
description: Programmatic smooth scrolling helper supporting window or custom scrollable containers, element IDs, selectors, refs, and pixel coordinates.
preview: demo-h-scroll-to-01
----------------------------

## Installation

<ComponentInstallation name="hooks-dom-use-scroll-to" />

## Usage

```tsx
import { useScrollTo } from '@/hooks/use-scroll-to'

// Pattern 1: Direct function call
const scrollTo = useScrollTo()
scrollTo({ top: 0, behavior: 'smooth' })
scrollTo('#section-contact')
scrollTo(500)

// Pattern 2: Helper methods
const { scrollToTop, scrollToBottom, scrollToElement } = useScrollTo()
scrollToTop()
scrollToBottom()

// Pattern 3: Custom scrollable container
const containerRef = useRef<HTMLDivElement>(null)
const scrollTo = useScrollTo(containerRef)
scrollTo('#item-5', { block: 'center' })
```

## API Reference

### Parameters / Props

| Parameter      | Type                             | Default     | Description                                                 |
| :------------- | :------------------------------- | :---------- | :---------------------------------------------------------- |
| `containerRef` | `RefObject<HTMLElement \| null>` | `undefined` | Optional DOM container ref to scroll instead of the window. |

### Return Value

| Property                           | Type       | Description                                                          |
| :--------------------------------- | :--------- | :------------------------------------------------------------------- |
| `scrollTo(target, options)`        | `Function` | Scrolls to pixel offset, ID string, React ref, or `ScrollToOptions`. |
| `scrollToTop(options)`             | `Function` | Smoothly scrolls to the top (0px).                                   |
| `scrollToBottom(options)`          | `Function` | Smoothly scrolls to the bottom of the container or document.         |
| `scrollToElement(el, options)`     | `Function` | Scrolls a specific element into view.                                |
| `scrollToElementById(id, options)` | `Function` | Scrolls an element with matching DOM ID into view.                   |


# useSessionStorage
URL: https://www.spaceui.one/hooks/use-session-storage

***

title: useSessionStorage
description: Synchronizes reactive state with window\.sessionStorage.
preview: demo-h-session-storage-01
----------------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-session-storage" />

## Usage

```tsx
import { useSessionStorage } from '@/hooks/use-session-storage'

const [views, setViews] = useSessionStorage('views', 1)
```

## API Reference

### Parameters / Props

| Parameter      | Type     | Default    | Description    |
| :------------- | :------- | :--------- | :------------- |
| `key`          | `string` | *required* | Session key.   |
| `initialValue` | `T`      | *required* | Initial value. |

### Return Value

| Return Type                         | Description  |
| :---------------------------------- | :----------- |
| `[T, (val: T) => void, () => void]` | Tuple state. |


# useShare
URL: https://www.spaceui.one/hooks/use-share

***

title: useShare
description: Native Web Share API caller.
preview: demo-h-share-01
------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-share" />

## Usage

```tsx
import { useShare } from '@/hooks/use-share'

const { share, isSupported } = useShare()
```

## API Reference

### Parameters / Props

*None*

### Return Value

| Property      | Type                      | Description            |
| :------------ | :------------------------ | :--------------------- |
| `share`       | `(data) => Promise<void>` | Triggers share dialog. |
| `isSupported` | `boolean`                 | Feature support.       |


# useSingleEffect
URL: https://www.spaceui.one/hooks/use-single-effect

***

title: useSingleEffect
description: Guaranteed exactly-once execution effect (StrictMode safe).
preview: demo-h-single-effect-01
--------------------------------

## Installation

<ComponentInstallation name="hooks-lifecycle-use-single-effect" />

## Usage

```tsx
import { useSingleEffect } from '@/hooks/use-single-effect'

useSingleEffect(() => {
  initAnalytics()
})
```

## API Reference

### Parameters / Props

| Parameter | Type         | Default    | Description               |
| :-------- | :----------- | :--------- | :------------------------ |
| `effect`  | `() => void` | *required* | Run-once effect function. |

### Return Value

*Returns void.*


# useSize
URL: https://www.spaceui.one/hooks/use-size

***

title: useSize
description: Measures real-time element pixel dimensions with ResizeObserver.
preview: demo-h-size-01
-----------------------

## Installation

<ComponentInstallation name="hooks-dom-use-size" />

## Usage

```tsx
import { useSize } from '@/hooks/use-size'

const ref = React.useRef(null)
const { width, height } = useSize(ref)
```

## API Reference

### Parameters / Props

| Parameter   | Type                     | Default    | Description     |
| :---------- | :----------------------- | :--------- | :-------------- |
| `targetRef` | `RefObject<HTMLElement>` | *required* | Ref to measure. |

### Return Value

| Property | Type     | Description       |
| :------- | :------- | :---------------- |
| `width`  | `number` | Width in pixels.  |
| `height` | `number` | Height in pixels. |


# useTabNotification
URL: https://www.spaceui.one/hooks/use-tab-notification

***

title: useTabNotification
description: Document title badge notification counter.
preview: demo-h-tab-notification-01
-----------------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-tab-notification" />

## Usage

```tsx
import { useTabNotification } from '@/hooks/use-tab-notification'

useTabNotification(3)
```

## API Reference

### Parameters / Props

| Parameter | Type     | Default    | Description   |
| :-------- | :------- | :--------- | :------------ |
| `count`   | `number` | *required* | Unread count. |

### Return Value

*Returns void.*


# useTitle
URL: https://www.spaceui.one/hooks/use-title

***

title: useTitle
description: Document head title modifier.
preview: demo-h-title-01
------------------------

## Installation

<ComponentInstallation name="hooks-browser-use-title" />

## Usage

```tsx
import { useTitle } from '@/hooks/use-title'

useTitle('Dashboard - Space UI')
```

## API Reference

### Parameters / Props

| Parameter | Type     | Default    | Description |
| :-------- | :------- | :--------- | :---------- |
| `title`   | `string` | *required* | New title.  |

### Return Value

*Returns void.*


# useToggle
URL: https://www.spaceui.one/hooks/use-toggle

***

title: useToggle
description: Boolean state toggle switch.
preview: demo-h-toggle-01
-------------------------

## Installation

<ComponentInstallation name="hooks-lifecycle-use-toggle" />

## Usage

```tsx
import { useToggle } from '@/hooks/use-toggle'

const [isOn, toggle, setVal] = useToggle(false)
```

## API Reference

### Parameters / Props

| Parameter      | Type      | Default | Description    |
| :------------- | :-------- | :------ | :------------- |
| `initialValue` | `boolean` | `false` | Initial state. |

### Return Value

| Return Type                                   | Description |
| :-------------------------------------------- | :---------- |
| `[boolean, () => void, (v: boolean) => void]` | Tuple.      |


# useUpdateEffect
URL: https://www.spaceui.one/hooks/use-update-effect

***

title: useUpdateEffect
description: Effect executed only on dependencies update, skipping mount.
preview: demo-h-update-effect-01
--------------------------------

## Installation

<ComponentInstallation name="hooks-lifecycle-use-update-effect" />

## Usage

```tsx
import { useUpdateEffect } from '@/hooks/use-update-effect'

useUpdateEffect(() => {
  console.log('Updated!')
}, [dep])
```

## API Reference

### Parameters / Props

Standard useEffect signature.

### Return Value

*Returns void.*


# useUrgentUpdate
URL: https://www.spaceui.one/hooks/use-urgent-update

***

title: useUrgentUpdate
description: React 18 transition priority switcher.
preview: demo-h-urgent-update-01
--------------------------------

## Installation

<ComponentInstallation name="hooks-lifecycle-use-urgent-update" />

## Usage

```tsx
import { useUrgentUpdate } from '@/hooks/use-urgent-update'

const urgent = useUrgentUpdate()
urgent(() => setCount((c) => c + 1))
```

## API Reference

### Parameters / Props

*None*

### Return Value

| Return Type                | Description            |
| :------------------------- | :--------------------- |
| `(fn: () => void) => void` | Urgent update wrapper. |


# useWindowSize
URL: https://www.spaceui.one/hooks/use-window-size

***

title: useWindowSize
description: Viewport dimensions tracker.
preview: demo-h-window-size-01
------------------------------

## Installation

<ComponentInstallation name="hooks-dom-use-window-size" />

## Usage

```tsx
import { useWindowSize } from '@/hooks/use-window-size'

const { width, height } = useWindowSize()
```

## API Reference

### Parameters / Props

*None*

### Return Value

| Property | Type     | Description      |
| :------- | :------- | :--------------- |
| `width`  | `number` | Viewport width.  |
| `height` | `number` | Viewport height. |


# Agent Activity Feed
URL: https://www.spaceui.one/interactions/agent-activity-feed

***

title: Agent Activity Feed
description: Real-time telemetry event stream monitoring tool executions, state diffs, tokens expended, and security policy checks.
component: true
base: base
isPro: true
preview:
name: interactions-agent-activity-feed
contained: false
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="interactions-agent-activity-feed" />

## Usage

```tsx
import { AgentActivityFeed } from '@/registry/interactions/agent-activity-feed'
```

```tsx
<AgentActivityFeed autoPlay={true} speed={1} />
```

## API Reference

### AgentActivityFeed Props

| Prop           | Type                     | Default     | Description                                                  |
| :------------- | :----------------------- | :---------- | :----------------------------------------------------------- |
| `preset`       | `AgentActivityPresetKey` | `'general'` | Active preset stream containing agent operational telemetry. |
| `autoPlay`     | `boolean`                | `true`      | Cycles through event filters and presets automatically.      |
| `speed`        | `number`                 | `1`         | Speed multiplier for auto-advance transitions.               |
| `pauseOnHover` | `boolean`                | `true`      | Pauses autonomous cycling while pointer is over the frame.   |
| `className`    | `string`                 | `''`        | Additional Tailwind utility classes for the outer container. |


# Agent Clearance Deck
URL: https://www.spaceui.one/interactions/agent-clearance-deck

***

title: Agent Clearance Deck
description: Autonomous credential and permission elevation deck with interactive risk scopes, countdown timer, and audit logs.
component: true
base: base
isPro: true
preview:
name: interactions-agent-clearance-deck
contained: false
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="interactions-agent-clearance-deck" />

## Usage

```tsx
import { AgentClearanceDeck } from '@/registry/interactions/agent-clearance-deck'
```

```tsx
<AgentClearanceDeck autoPlay={true} speed={1} onSequenceComplete={() => console.log('Clearance cycle finished')} />
```

## API Reference

### AgentClearanceDeck Props

| Prop                 | Type                 | Default              | Description                                                                |
| :------------------- | :------------------- | :------------------- | :------------------------------------------------------------------------- |
| `initialRequests`    | `ClearanceRequest[]` | `CLEARANCE_REQUESTS` | List of credential elevation requests with scopes, TTLs, and risk ratings. |
| `autoPlay`           | `boolean`            | `true`               | Automatically cycles and resolves clearance requests in sequence.          |
| `speed`              | `number`             | `1`                  | Speed multiplier for approval countdown timers.                            |
| `className`          | `string`             | `''`                 | Additional Tailwind utility classes for the outer card.                    |
| `onSequenceComplete` | `() => void`         | `-`                  | Callback invoked when all requests in the deck have been processed.        |


# Agent Genesis Forge
URL: https://www.spaceui.one/interactions/agent-genesis-forge

***

title: Agent Genesis Forge
description: Specialized agent synthesis and provisioning studio with skill matrix configuration, persona tuning, and live code preview.
component: true
base: base
isPro: true
preview:
name: interactions-agent-genesis-forge
contained: false
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="interactions-agent-genesis-forge" />

## Usage

```tsx
import { AgentGenesisForge } from '@/registry/interactions/agent-genesis-forge'
```

```tsx
<AgentGenesisForge
  initialActivePresetIndex={0}
  autoPlay={true}
  speed={1}
  onSequenceComplete={() => console.log('Agent synthesized successfully')}
/>
```

## API Reference

### AgentGenesisForge Props

| Prop                       | Type            | Default         | Description                                                                        |
| :------------------------- | :-------------- | :-------------- | :--------------------------------------------------------------------------------- |
| `presets`                  | `AgentPreset[]` | `AGENT_PRESETS` | Available agent archetypes, system prompt templates, and default skill selections. |
| `initialActivePresetIndex` | `number`        | `0`             | Initially selected agent archetype.                                                |
| `autoPlay`                 | `boolean`       | `true`          | Cycles through synthesis and calibration phases automatically.                     |
| `speed`                    | `number`        | `1`             | Playback speed multiplier for forging progress.                                    |
| `className`                | `string`        | `''`            | Additional Tailwind utility classes for the outer container.                       |
| `onSequenceComplete`       | `() => void`    | `-`             | Callback invoked when agent instantiation successfully finalizes.                  |


# Agent Pipeline
URL: https://www.spaceui.one/interactions/agent-pipeline

***

title: Agent Pipeline
description: A living multi-agent workflow that models task routing, research, drafting, and approvals with real-time physics, activity feeds, and playback controls.
component: true
base: base
isPro: true
preview:
name: interactions-agent-pipeline
contained: false
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="interactions-agent-pipeline" />

## Usage

```tsx
import { AgentPipeline } from '@/components/interactions/agent-pipeline'
```

```tsx
<AgentPipeline />
```

## API Reference

### AgentPipeline

| Prop             | Type          | Default                    | Description                                                    |
| :--------------- | :------------ | :------------------------- | :------------------------------------------------------------- |
| `preset`         | `string`      | `'incident'`               | Selected workflow preset ('incident', 'codereview', etc.).     |
| `flow`           | `string`      | `'success'`                | Selected flow variant ('success' or 'error').                  |
| `cyclePresets`   | `boolean`     | `false`                    | Automatically cycle through all presets across runs.           |
| `cycleFlows`     | `boolean`     | `true`                     | Automatically cycle through all flows across consecutive runs. |
| `taskTitle`      | `string`      | Preset task title          | Title of the task assigned to the multi-agent team.            |
| `runId`          | `string`      | Auto-generated (`sp_XXXX`) | Identifier displayed for the pipeline execution.               |
| `agents`         | `AgentStep[]` | Preset agents              | Custom sequence of agents, their roles, steps, and durations.  |
| `autoPlay`       | `boolean`     | `true`                     | Automatically runs and loops the pipeline when mounted.        |
| `speed`          | `number`      | `1`                        | Speed multiplier for pipeline execution.                       |
| `travelDuration` | `number`      | `0.7`                      | Transfer duration in seconds between agent relays.             |
| `className`      | `string`      | -                          | Additional CSS classes for the outer container.                |


# Agent Usage Card
URL: https://www.spaceui.one/interactions/agent-usage-card

***

title: Agent Usage Card
description: An interactive agent status and usage card with segmented progress tracking, live telemetry hours advancement, morph icon controls, squircle buttons, squishmoji status avatar, and a collapsible cost breakdown.
component: true
base: base
isPro: true
preview:
name: interactions-agent-usage-card
contained: false
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="interactions-agent-usage-card" />

## Usage

```tsx
import { AgentUsageCard } from '@/components/interactions/agent-usage-card'
```

```tsx
<AgentUsageCard
  title="Site Reliability Agent"
  description="Autonomous incident mitigation and cluster telemetry."
  usedHours={185}
  totalHours={320}
  resetLabel="Resets in 8 days"
  defaultWorking={true}
/>
```

## API Reference

### AgentUsageCard Props

| Prop              | Type                         | Default                                                   | Description                                            |
| ----------------- | ---------------------------- | --------------------------------------------------------- | ------------------------------------------------------ |
| `title`           | `string`                     | `"Site Reliability Agent"`                                | Title of the agent or service                          |
| `description`     | `string`                     | `"Autonomous incident mitigation and cluster telemetry."` | Subtitle description beneath the title                 |
| `usedHours`       | `number`                     | `185`                                                     | Number of hours consumed so far                        |
| `totalHours`      | `number`                     | `320`                                                     | Total monthly quota in hours                           |
| `resetLabel`      | `string`                     | `"Resets in 8 days"`                                      | Helper text indicating when the billing quota resets   |
| `costItems`       | `CostItem[]`                 | `DEFAULT_COST_ITEMS`                                      | Breakdown of hourly costs per component/model          |
| `defaultWorking`  | `boolean`                    | `false`                                                   | Initial working / running state                        |
| `defaultExpanded` | `boolean`                    | `false`                                                   | Initial expanded state of the cost breakdown accordion |
| `onWorkingChange` | `(working: boolean) => void` | -                                                         | Callback triggered when the agent is started or paused |
| `className`       | `string`                     | -                                                         | Additional class name applied to outer card container  |


# Capability Matrix
URL: https://www.spaceui.one/interactions/capability-matrix

***

title: Capability Matrix
description: Dynamic capability registry showcasing multi-modal agent skills, verification states, and runtime sandboxing telemetry.
component: true
base: base
isPro: true
preview:
name: interactions-capability-matrix
contained: false
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="interactions-capability-matrix" />

## Usage

```tsx
import { CapabilityMatrix } from '@/registry/interactions/capability-matrix'
```

```tsx
<CapabilityMatrix autoPlay={true} speed={1} onSequenceComplete={() => console.log('Capability audit complete')} />
```

## API Reference

### CapabilityMatrix Props

| Prop                  | Type               | Default                | Description                                                                       |
| :-------------------- | :----------------- | :--------------------- | :-------------------------------------------------------------------------------- |
| `initialCapabilities` | `CapabilityItem[]` | `DEFAULT_CAPABILITIES` | Registered agent tool definitions, security compliance levels, and health status. |
| `autoPlay`            | `boolean`          | `true`                 | Automatically runs periodic sandbox health checks and verification runs.          |
| `speed`               | `number`           | `1`                    | Speed multiplier for verification transitions.                                    |
| `className`           | `string`           | `''`                   | Additional Tailwind utility classes for the outer container.                      |
| `onSequenceComplete`  | `() => void`       | `-`                    | Callback triggered upon completing a full capability audit pass.                  |


# Cognitive Pulse Monitor
URL: https://www.spaceui.one/interactions/cognitive-pulse-monitor

***

title: Cognitive Pulse Monitor
description: Real-time neural load monitor visualizing agent attention distribution, context window pressure, and reasoning heatmaps.
component: true
base: base
isPro: true
preview:
name: interactions-cognitive-pulse-monitor
contained: false
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="interactions-cognitive-pulse-monitor" />

## Usage

```tsx
import { CognitivePulseMonitor } from '@/registry/interactions/cognitive-pulse-monitor'
```

```tsx
<CognitivePulseMonitor autoPlay={true} speed={1} onSequenceComplete={() => console.log('Telemetry cycle concluded')} />
```

## API Reference

### CognitivePulseMonitor Props

| Prop                 | Type             | Default          | Description                                                                                  |
| :------------------- | :--------------- | :--------------- | :------------------------------------------------------------------------------------------- |
| `agents`             | `AgentProfile[]` | `AGENT_PROFILES` | Worker agent profiles with live cognitive load, token throughput, and context depth metrics. |
| `autoPlay`           | `boolean`        | `true`           | Simulates active reasoning spikes and context expansion dynamics.                            |
| `speed`              | `number`         | `1`              | Sampling frequency multiplier for neural pulse waves.                                        |
| `className`          | `string`         | `''`             | Additional Tailwind utility classes for the outer container.                                 |
| `onSequenceComplete` | `() => void`     | `-`              | Callback fired upon completing a full cognitive monitoring epoch.                            |


# Currency Converter
URL: https://www.spaceui.one/interactions/currency-converter

***

title: Currency Converter
description: An interactive currency converter and token swap card with real-time exchange rates, NumberFlow spring animations, Space UI Select with flags, and a liquid metal squircle button.
component: true
base: base
isPro: true
preview:
name: interactions-currency-converter
contained: false
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="interactions-currency-converter" />

## Usage

```tsx
import { CurrencyConverter } from '@/components/interactions/currency-converter'
```

```tsx
<CurrencyConverter />
```

## API Reference

### CurrencyConverter Props

| Prop                  | Type                                        | Default              | Description                                                  |
| --------------------- | ------------------------------------------- | -------------------- | ------------------------------------------------------------ |
| `initialFromCurrency` | `string`                                    | `"USD"`              | Initial currency code for sending                            |
| `initialToCurrency`   | `string`                                    | `"EUR"`              | Initial currency code for receiving                          |
| `initialAmount`       | `number`                                    | `100`                | Initial numerical amount to convert                          |
| `currencies`          | `Currency[]`                                | `DEFAULT_CURRENCIES` | Custom array of available currency rates and metadata        |
| `onConvert`           | `(details: CurrencyConvertDetails) => void` | -                    | Callback triggered when the convert action button is pressed |
| `className`           | `string`                                    | -                    | Additional class name applied to outer Frame container       |


# Deploy Pipeline
URL: https://www.spaceui.one/interactions/deploy-pipeline

***

title: Deploy Pipeline
description: A deploy pipeline that plays itself — steps advance, badges update, and details unfold on their own, no click required.
component: true
base: base
isPro: true
preview:
name: interactions-deploy-pipeline
contained: false
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="interactions-deploy-pipeline" />

## Usage

```tsx
import { DeployPipeline } from '@/components/interactions/deploy-pipeline'
```

```tsx
<DeployPipeline />
```

## API Reference

### DeployPipeline

| Prop           | Type                    | Default | Description                                                |
| :------------- | :---------------------- | :------ | :--------------------------------------------------------- |
| `steps`        | `DeployPipelineStep[]`  | sample  | Steps rendered in the pipeline.                            |
| `cycle`        | `DeployPipelineFrame[]` | sample  | Keyframes the pipeline auto-advances through.              |
| `autoPlay`     | `boolean`               | `true`  | Auto-advance through `cycle` on a timer.                   |
| `pauseOnHover` | `boolean`               | `true`  | Pause auto-advance while the pointer is over the pipeline. |
| `speed`        | `number`                | `1`     | Multiplier applied to each frame's duration.               |
| `className`    | `string`                | -       | Additional CSS classes for the outer card.                 |


# Hallucination Radar
URL: https://www.spaceui.one/interactions/hallucination-radar

***

title: Hallucination Radar
description: Real-time hallucination defense radar tracking semantic grounding scores, citation provenance, and contradiction risk.
component: true
base: base
isPro: true
preview:
name: interactions-hallucination-radar
contained: false
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="interactions-hallucination-radar" />

## Usage

```tsx
import { HallucinationRadar } from '@/registry/interactions/hallucination-radar'
```

```tsx
<HallucinationRadar autoPlay={true} speed={1} />
```

## API Reference

### FactGroundingRadar Props

| Prop                 | Type          | Default       | Description                                                                            |
| :------------------- | :------------ | :------------ | :------------------------------------------------------------------------------------- |
| `claims`             | `FactClaim[]` | `FACT_CLAIMS` | Claims under evaluation with provenance source links and grounding confidence indices. |
| `autoPlay`           | `boolean`     | `true`        | Performs continuous rotational radar sweeps and claim evaluations.                     |
| `speed`              | `number`      | `1`           | Radar angular velocity and evaluation speed multiplier.                                |
| `className`          | `string`      | `''`          | Additional Tailwind utility classes for the outer container.                           |
| `onSequenceComplete` | `() => void`  | `-`           | Callback triggered when all claims have undergone factual verification.                |


# Interactions
URL: https://www.spaceui.one/interactions

***

title: Interactions
description: Living components that move, respond and never sit still.
----------------------------------------------------------------------


# Priority Sort Lane
URL: https://www.spaceui.one/interactions/priority-sort-lane

***

title: Priority Sort Lane
description: Dynamic priority queue sorting high-urgency agent goals with interactive reordering and urgency-decay visualizations.
component: true
base: base
isPro: true
preview:
name: interactions-priority-sort-lane
contained: false
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="interactions-priority-sort-lane" />

## Usage

```tsx
import { PrioritySortLane } from '@/registry/interactions/priority-sort-lane'
```

```tsx
<PrioritySortLane autoPlay={true} speed={1} onSequenceComplete={() => console.log('Sort lane rebalanced')} />
```

## API Reference

### PrioritySortLane Props

| Prop                 | Type         | Default         | Description                                                       |
| :------------------- | :----------- | :-------------- | :---------------------------------------------------------------- |
| `initialTasks`       | `LaneTask[]` | `DEFAULT_TASKS` | Priority-tagged agent subgoals distributed across urgency levels. |
| `autoPlay`           | `boolean`    | `true`          | Dynamically rebalances and promotes high-urgency tasks.           |
| `speed`              | `number`     | `1`             | Speed multiplier for automatic priority shift intervals.          |
| `className`          | `string`     | `''`            | Additional Tailwind utility classes for the outer container.      |
| `onSequenceComplete` | `() => void` | `-`             | Callback fired when all pending tasks in the lane are sorted.     |


# Realtime Voice
URL: https://www.spaceui.one/interactions/realtime-voice

***

title: Realtime Voice
description: An interactive conversational AI voice interface with dynamic Bloop Orb visualizer, audio waveform ripples, live transcription, and turn-taking orchestration.
component: true
base: base
isPro: true
preview:
name: interactions-realtime-voice
contained: false
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="interactions-realtime-voice" />

## Usage

```tsx
import { RealtimeVoice } from '@/components/interactions/realtime-voice'
```

```tsx
<RealtimeVoice />
```

## API Reference

### RealtimeVoice

| Prop                 | Type                  | Default       | Description                                                             |
| :------------------- | :-------------------- | :------------ | :---------------------------------------------------------------------- |
| `preset`             | `VoicePresetKey`      | `'developer'` | Active scenario preset (`'developer'`, `'designer'`, `'support'`, etc.) |
| `dialogues`          | `VoiceDialogueTurn[]` | Preset turns  | Custom conversational turns overriding preset dialogues.                |
| `modelName`          | `string`              | Preset model  | Label displayed for the AI voice model (e.g. `'GPT-4o Voice'`).         |
| `autoPlay`           | `boolean`             | `true`        | Whether the conversation plays and advances automatically.              |
| `loop`               | `boolean`             | `true`        | Whether the conversation loops continuously upon completing all turns.  |
| `cyclePresets`       | `boolean`             | `true`        | Automatically advance to the next preset scenario on cycle completion.  |
| `speed`              | `number`              | `1`           | Speed multiplier for speech timing and state transitions.               |
| `showWaveform`       | `boolean`             | `true`        | Whether to render animated audio waveform bars.                         |
| `enableSounds`       | `boolean`             | `true`        | Enable or mute tactile audio micro-interactions and speech chimes.      |
| `targetLoops`        | `number`              | `undefined`   | Target number of sequence cycles before halting (for recorder sync).    |
| `onSequenceComplete` | `() => void`          | `undefined`   | Callback triggered once target sequence loops are finished.             |
| `className`          | `string`              | -             | Additional CSS classes for the outer container.                         |


# Status Badge Glow
URL: https://www.spaceui.one/interactions/status-badge-glow

***

title: Status Badge Glow
description: An interactive status monitor with glowing radial reflections, spring-animated status transitions, and staggered character animations for pending, success, and failed states.
component: true
base: base
isPro: true
preview:
name: interactions-status-badge-glow
contained: false
className: '\*\*:\[.preview]:h-auto'
------------------------------------

## Installation

<ComponentInstallation name="interactions-status-badge-glow" />

## Usage

```tsx
import { StatusBadgeGlow, StatusBadgeGlowTable } from '@/components/interactions/status-badge-glow'
```

```tsx
<StatusBadgeGlow state="success" />
<StatusBadgeGlow state="pending" />
<StatusBadgeGlow state="failed" />
```

### Interactive Table

```tsx
<StatusBadgeGlowTable />
```

## API Reference

### StatusBadgeGlow Props

| Prop        | Type                                   | Default                                                        | Description                                                       |
| ----------- | -------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------- |
| `state`     | `"pending" \| "success" \| "failed"`   | `"pending"`                                                    | Semantic execution status controlling glow color, icon and label  |
| `labels`    | `Partial<Record<StatusState, string>>` | `{ pending: "Pending", success: "Success", failed: "Failed" }` | Custom labels for each state                                      |
| `onClick`   | `() => void`                           | -                                                              | Optional click handler (enables interactive cycling or drilldown) |
| `className` | `string`                               | -                                                              | Additional class name applied to badge container                  |


# Accordion
URL: https://www.spaceui.one/primitives/accordion

***

title: Accordion
description: Allows you to display content in collapsible panels, making it easy for users to explore details on demand while conserving screen space.

links:
doc: [https://base-ui.com/react/components/accordion#api-reference](https://base-ui.com/react/components/accordion#api-reference)
preview: demo-p-accordion-01
----------------------------

## Installation

<ComponentInstallation name="primitives-accordion" />

## Usage

```tsx
import { Accordion, AccordionItem, AccordionPanel, AccordionTrigger } from '@/components/ui/accordion'
```

```tsx
<Accordion>
  <AccordionItem value="item-1">
    <AccordionTrigger>Your Accordion Title Goes Here</AccordionTrigger>
    <AccordionPanel>
      This is where your accordion content will appear. You can customize this text with any message.
    </AccordionPanel>
  </AccordionItem>
</Accordion>
```

## Anatomy

```tsx
<Accordion>
  <AccordionItem>
    <AccordionTrigger />
    <AccordionPanel />
  </AccordionItem>
</Accordion>
```

## Accessibility

* Adheres to the [WAI-ARIA Accordion Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/).
* Each accordion header trigger is wrapped with the proper `aria-expanded` and `aria-controls` attributes.

### Keyboard Interactions

| Key                                 | Action                                            |
| :---------------------------------- | :------------------------------------------------ |
| <Kbd>Space</Kbd> / <Kbd>Enter</Kbd> | Expands or collapses the focused accordion panel. |
| <Kbd>ArrowDown</Kbd>                | Moves focus to the next accordion trigger.        |
| <Kbd>ArrowUp</Kbd>                  | Moves focus to the previous accordion trigger.    |
| <Kbd>Home</Kbd>                     | Moves focus to the first accordion trigger.       |
| <Kbd>End</Kbd>                      | Moves focus to the last accordion trigger.        |

## API Reference

### Accordion

Root component. Alias for `Accordion.Root` from Base UI.

### AccordionItem

Individual accordion item container. Styled wrapper for `Accordion.Item` from Base UI with bottom border styling.

### AccordionTrigger

Trigger button that toggles the accordion panel. Styled wrapper for `Accordion.Trigger` from Base UI. Includes a built-in chevron icon that rotates when expanded.

### AccordionPanel

Collapsible content panel. Styled wrapper for `Accordion.Panel` from Base UI with animated height transitions. Also exported as `AccordionContent`.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-accordion-02" description="Accordion allowing multiple panels open" />

  <ShowcaseCard name="demo-p-accordion-03" description="Bordered accordion items" />
</ShowcaseGrid>


# Alert Dialog
URL: https://www.spaceui.one/primitives/alert-dialog

***

title: Alert Dialog
description: Displays a modal window that asks users to confirm important actions before proceeding, helping prevent accidental deletions or irreversible mistakes.

links:
doc: [https://base-ui.com/react/components/alert-dialog#api-reference](https://base-ui.com/react/components/alert-dialog#api-reference)
preview: demo-p-alert-dialog-01
-------------------------------

## Installation

<ComponentInstallation name="primitives-alert-dialog" />

## Usage

```tsx
import {
  AlertDialog,
  AlertDialogClose,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogPopup,
  AlertDialogTitle,
  AlertDialogTrigger,
} from '@/components/ui/alert-dialog'
```

```tsx
<AlertDialog>
  <AlertDialogTrigger>Delete Account</AlertDialogTrigger>
  <AlertDialogPopup>
    <AlertDialogHeader>
      <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone. This will permanently delete your account and remove your data from our servers.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogClose>Cancel</AlertDialogClose>
      <AlertDialogClose>Delete Account</AlertDialogClose>
    </AlertDialogFooter>
  </AlertDialogPopup>
</AlertDialog>
```

## Anatomy

```tsx
<AlertDialog>
  <AlertDialogTrigger />
  <AlertDialogBackdrop />
  <AlertDialogPopup>
    <AlertDialogHeader>
      <AlertDialogTitle />
      <AlertDialogDescription />
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogClose />
    </AlertDialogFooter>
  </AlertDialogPopup>
</AlertDialog>
```

## Features

### Bare Footer

An alert dialog with a bare footer (`variant="bare"`), removing the default border and background styling.

<ComponentPreview name="demo-p-alert-dialog-02" />

## Accessibility

* Follows the [WAI-ARIA Alert and Message Dialog Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/).
* Traps keyboard focus within the dialog and locks background body scrolling while open.

### Keyboard Interactions

| Key                    | Action                                                           |
| :--------------------- | :--------------------------------------------------------------- |
| <Kbd>Tab</Kbd>         | Moves focus to the next focusable element within the dialog.     |
| <Kbd>Shift + Tab</Kbd> | Moves focus to the previous focusable element within the dialog. |
| <Kbd>Escape</Kbd>      | Closes the alert dialog and returns focus to the trigger.        |

## API Reference

### AlertDialog

Root component. Alias for `AlertDialog.Root` from Base UI.

### AlertDialogTrigger

Trigger button that opens the alert dialog. Alias for `AlertDialog.Trigger` from Base UI.

### AlertDialogPopup

Popup container that displays the alert dialog content. Also exported as `AlertDialogContent`.

| Prop                  | Type                       | Default | Description                                                                                                    |
| --------------------- | -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `bottomStickOnMobile` | `boolean`                  | `true`  | When true, sticks to the bottom of the screen on mobile devices                                                |
| `portalProps`         | `AlertDialog.Portal.Props` | -       | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Alert Dialog portal API |

### AlertDialogHeader

Container for the alert dialog title and description.

### AlertDialogFooter

Footer section for action buttons.

Unlike [Dialog](/ui-kit/primitives/dialog), alert dialog has no `AlertDialogPanel`. Put title and description in `AlertDialogHeader`, actions in `AlertDialogFooter`, and use a plain element with `className` if you need extra body content between them.

| Prop      | Type                  | Default     | Description                                                                                |
| --------- | --------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `variant` | `"default" \| "bare"` | `"default"` | Controls the footer styling. `default` includes border and background, `bare` removes them |

**Example:**

```tsx
// Default variant (with border and background)
<AlertDialogFooter>
  <AlertDialogClose>Cancel</AlertDialogClose>
  <AlertDialogClose>Delete</AlertDialogClose>
</AlertDialogFooter>

// Bare variant (no border or background)
<AlertDialogFooter variant="bare">
  <AlertDialogClose>Cancel</AlertDialogClose>
  <AlertDialogClose>Delete</AlertDialogClose>
</AlertDialogFooter>
```

### AlertDialogTitle

Title component. Alias for `AlertDialog.Title` from Base UI.

### AlertDialogDescription

Description component. Alias for `AlertDialog.Description` from Base UI.

### AlertDialogClose

Close button component. Alias for `AlertDialog.Close` from Base UI.

### AlertDialogPortal

Portal component for rendering outside the DOM hierarchy. Alias for `AlertDialog.Portal` from Base UI.

### AlertDialogBackdrop

Backdrop/overlay component. Also exported as `AlertDialogOverlay`. Alias for `AlertDialog.Backdrop` from Base UI.

### AlertDialogViewport

Viewport component for positioning. Alias for `AlertDialog.Viewport` from Base UI.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-dialog-04" description="Alert dialog with close confirmation" />
</ShowcaseGrid>


# Alert
URL: https://www.spaceui.one/primitives/alert

***

title: Alert
description: Displays a prominent message box for important notices, warnings, or success messages to keep users informed without interrupting their work.
preview: demo-p-alert-01
------------------------

## Installation

<ComponentInstallation name="primitives-alert" />

## Usage

```tsx
import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert'
```

```tsx
<Alert>
  <AlertTitle>Your Alert Title Goes Here</AlertTitle>
  <AlertDescription>
    This is where your alert description will appear. You can customize this text with any message.
  </AlertDescription>
</Alert>
```

## Features

### Variants

All available alert variants in one overview: `default`, `info`, `warning`, `error`, `success`.

<ComponentPreview name="demo-p-alert-01" />

### Badge Icon

Alert variants rendered with a badge container for the icon.

<ComponentPreview name="demo-p-alert-02" />

### With Actions

Alert with interactive dismiss and action buttons.

<ComponentPreview name="demo-p-alert-03" />

## API Reference

This is a custom component, not a Base UI wrapper.

### Alert

Root container for the alert.

| Prop      | Type                                                       | Default     | Description                                 |
| --------- | ---------------------------------------------------------- | ----------- | ------------------------------------------- |
| `variant` | `"default" \| "error" \| "info" \| "success" \| "warning"` | `"default"` | Controls the alert styling and color scheme |

### AlertIcon

Container for the alert icon. Supports standalone icon rendering or badge container styling.

| Prop    | Type      | Default | Description                                                                  |
| ------- | --------- | ------- | ---------------------------------------------------------------------------- |
| `badge` | `boolean` | `false` | Renders the icon inside a badge container styled according to parent variant |

### AlertTitle

Title text for the alert. Renders as a styled `div`.

### AlertDescription

Description text for the alert. Renders as a styled `div` with muted foreground color.

### AlertAction

Container for action buttons. Automatically positions to the right on larger screens.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-alert-04" description="Compact stroke alerts with action buttons" />
</ShowcaseGrid>


# Aspect Ratio
URL: https://www.spaceui.one/primitives/aspect-ratio

***

title: Aspect Ratio
description: Maintains a consistent width-to-height ratio for images, videos, and embeds, preventing layout shifts when pages load or resize.
links:
doc: [https://base-ui.com/react/components/aspect-ratio#api-reference](https://base-ui.com/react/components/aspect-ratio#api-reference)
preview: demo-p-aspect-ratio-01
-------------------------------

## Installation

<ComponentInstallation name="primitives-aspect-ratio" />

## Usage

```tsx
import { AspectRatio } from '@/components/ui/aspect-ratio'
```

```tsx
<AspectRatio ratio={16 / 9}>
  <imgalt="Image" className="h-full w-full object-cover" />
</AspectRatio>
```

## API Reference

### AspectRatio Props

| Prop        | Type                    | Default | Description                                   |
| :---------- | :---------------------- | :------ | :-------------------------------------------- |
| `ratio`     | `number`                | -       | The desired aspect ratio (e.g. `16 / 9`, `1`) |
| `className` | `string`                | -       | Custom class name applied to the container    |
| `...props`  | `ComponentProps<'div'>` | -       | All native HTML div attributes                |

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-aspect-ratio-02" description="4:3 standard aspect ratio" />

  <ShowcaseCard name="demo-p-aspect-ratio-03" description="1:1 square aspect ratio" />

  <ShowcaseCard name="demo-p-aspect-ratio-04" description="21:9 ultrawide aspect ratio" />

  <ShowcaseCard name="demo-p-aspect-ratio-05" description="9:16 portrait aspect ratio" />

  <ShowcaseCard name="demo-p-aspect-ratio-06" description="3:2 classic photography aspect ratio" />

  <ShowcaseCard name="demo-p-aspect-ratio-07" description="4:5 social media portrait aspect ratio" />

  <ShowcaseCard name="demo-p-aspect-ratio-08" description="16:10 computer monitor aspect ratio" />
</ShowcaseGrid>


# Autocomplete
URL: https://www.spaceui.one/primitives/autocomplete

***

title: Autocomplete
description: Displays matching suggestions as users type into an input field, helping them find items quickly and reducing typing errors.

links:
doc: [https://base-ui.com/react/components/autocomplete#api-reference](https://base-ui.com/react/components/autocomplete#api-reference)
preview: demo-p-autocomplete-01
-------------------------------

## Installation

<ComponentInstallation name="primitives-autocomplete" />

## Usage

```tsx
import {
  Autocomplete,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
} from '@/components/ui/autocomplete'

const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
  { value: "grape", label: "Grape" },
]

<Autocomplete items={items}>
  <AutocompleteInput placeholder="Search..." />
  <AutocompletePopup>
    <AutocompleteEmpty>No results found.</AutocompleteEmpty>
    <AutocompleteList>
      {(item) => <AutocompleteItem key={item.value} value={item}>{item.label}</AutocompleteItem>}
    </AutocompleteList>
  </AutocompletePopup>
</Autocomplete>
```

## Features

### Sizes

Autocomplete inputs in `sm`, `default`, and `lg` sizes.

<ComponentPreview name="demo-p-autocomplete-02" />

## API Reference

### Autocomplete

The root autocomplete component. Manages the autocomplete state and provides context to child components.

| Prop       | Type                                        | Description                                       |
| ---------- | ------------------------------------------- | ------------------------------------------------- |
| `items`    | `readonly unknown[]`                        | The array of items to display in the autocomplete |
| `open`     | `boolean`                                   | Controls whether the popup is open                |
| `...props` | `React.ComponentProps<typeof Autocomplete>` | All Base UI Autocomplete props are supported      |

### AutocompleteInput

The input field component with extended features for size variants and addon support.

| Prop           | Type                             | Default     | Description                                                                                     |
| -------------- | -------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| `size`         | `"sm" \| "default" \| "lg"`      | `"default"` | The size variant of the input field                                                             |
| `startAddon`   | `React.ReactNode`                | -           | Element to display at the start (left side) of the input, such as an icon                       |
| `showTrigger`  | `boolean`                        | `false`     | Whether to display a trigger button (chevron icon) on the right side of the input               |
| `showClear`    | `boolean`                        | `false`     | Whether to display a clear button (X icon) on the right side of the input when there is a value |
| `triggerProps` | `Autocomplete.Trigger.Props`     | -           | Props forwarded to the internal trigger button, useful for overriding `aria-label`              |
| `clearProps`   | `Autocomplete.Clear.Props`       | -           | Props forwarded to the internal clear button, useful for overriding `aria-label`                |
| `className`    | `string`                         | -           | Additional CSS classes to apply to the component                                                |
| `...props`     | Base UI Autocomplete Input props | -           | All standard autocomplete input attributes are supported                                        |

### AutocompletePopup

The popup container that displays the autocomplete suggestions.

| Prop          | Type                                          | Default    | Description                                                                                                                         |
| ------------- | --------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `side`        | `"top" \| "bottom" \| "left" \| "right"`      | `"bottom"` | Preferred edge to position the popup relative to the trigger/input                                                                  |
| `sideOffset`  | `number`                                      | `4`        | Distance from the trigger in pixels                                                                                                 |
| `align`       | `"start" \| "center" \| "end"`                | `"center"` | Alignment relative to the trigger along the cross-axis                                                                              |
| `alignOffset` | `number`                                      | `0`        | Distance in pixels to shift the popup along the alignment axis                                                                      |
| `anchor`      | `Element \| null \| React.RefObject<Element>` | -          | Custom anchor element or ref to anchor the popup against                                                                            |
| `portalProps` | `Autocomplete.Portal.Props`                   | -          | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Combobox portal API (autocomplete reuses it) |
| `className`   | `string`                                      | -          | Additional CSS classes to apply to the component                                                                                    |
| `...props`    | Base UI Autocomplete Popup props              | -          | All standard autocomplete popup attributes are supported                                                                            |

### AutocompleteList

A scrollable container for autocomplete items.

| Prop        | Type                            | Description                                             |
| ----------- | ------------------------------- | ------------------------------------------------------- |
| `className` | `string`                        | Additional CSS classes to apply to the component        |
| `...props`  | Base UI Autocomplete List props | All standard autocomplete list attributes are supported |

### AutocompleteItem

An individual selectable autocomplete item.

| Prop        | Type                            | Description                                             |
| ----------- | ------------------------------- | ------------------------------------------------------- |
| `value`     | `unknown`                       | The value of the item                                   |
| `className` | `string`                        | Additional CSS classes to apply to the component        |
| `...props`  | Base UI Autocomplete Item props | All standard autocomplete item attributes are supported |

### AutocompleteEmpty

Displays a message when no results are found.

| Prop        | Type                             | Description                                              |
| ----------- | -------------------------------- | -------------------------------------------------------- |
| `className` | `string`                         | Additional CSS classes to apply to the component         |
| `...props`  | Base UI Autocomplete Empty props | All standard autocomplete empty attributes are supported |

### AutocompleteGroup

Groups related autocomplete items together.

| Prop        | Type                             | Description                                              |
| ----------- | -------------------------------- | -------------------------------------------------------- |
| `items`     | `readonly unknown[]`             | The array of items in this group                         |
| `className` | `string`                         | Additional CSS classes to apply to the component         |
| `...props`  | Base UI Autocomplete Group props | All standard autocomplete group attributes are supported |

### AutocompleteGroupLabel

Displays a label for an autocomplete group.

| Prop        | Type                                   | Description                                                    |
| ----------- | -------------------------------------- | -------------------------------------------------------------- |
| `className` | `string`                               | Additional CSS classes to apply to the component               |
| `...props`  | Base UI Autocomplete Group Label props | All standard autocomplete group label attributes are supported |

### AutocompleteCollection

Used to wrap items within a group for rendering.

| Prop       | Type                                  | Description                                                   |
| ---------- | ------------------------------------- | ------------------------------------------------------------- |
| `...props` | Base UI Autocomplete Collection props | All standard autocomplete collection attributes are supported |

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-autocomplete-03" description="Large autocomplete" />

  <ShowcaseCard name="demo-p-autocomplete-04" description="Autocomplete with label" />

  <ShowcaseCard name="demo-p-autocomplete-05" description="Autocomplete autofilling the input with the highlighted item" />

  <ShowcaseCard name="demo-p-autocomplete-06" description="Autocomplete auto highlighting the first option" />

  <ShowcaseCard name="demo-p-autocomplete-07" description="Autocomplete with clear button" />

  <ShowcaseCard name="demo-p-autocomplete-08" description="Autocomplete with trigger and clear buttons" />

  <ShowcaseCard name="demo-p-autocomplete-09" description="Autocomplete with grouped items" />

  <ShowcaseCard name="demo-p-autocomplete-10" description="Autocomplete with limited number of results" />

  <ShowcaseCard name="demo-p-autocomplete-11" description="Autocomplete with async items loading" />

  <ShowcaseCard name="demo-p-autocomplete-12" description="Autocomplete form" />

  <ShowcaseCard name="demo-p-autocomplete-13" description="Autocomplete form" />

  <ShowcaseCard name="demo-p-autocomplete-14" description="Pill-shaped autocomplete" />

  <ShowcaseCard name="demo-p-autocomplete-15" description="Address autocomplete with Google Maps Places API" />
</ShowcaseGrid>


# Avatar
URL: https://www.spaceui.one/primitives/avatar

***

title: Avatar
description: Displays user profile pictures, avatars, or fallback initials, giving users an easy way to identify people throughout the app.

links:
doc: [https://base-ui.com/react/components/avatar#api-reference](https://base-ui.com/react/components/avatar#api-reference)
preview: demo-p-avatar-01
-------------------------

## Installation

<ComponentInstallation name="primitives-avatar" />

## Usage

```tsx
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar'
```

```tsx
<Avatar>
  <AvatarImage src="/avatars/01.png" alt="User avatar" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
```

## Features

### Sizes

Avatar in multiple size options from `xs` to `xl`.

<ComponentPreview name="demo-p-avatar-02" />

## API Reference

### Avatar

Root component. Styled wrapper for `Avatar.Root` from Base UI with default size of 32px (8 units) and rounded-full styling.

### AvatarImage

Image element for the avatar. Styled wrapper for `Avatar.Image` from Base UI.

### AvatarFallback

Fallback content displayed when the image fails to load. Styled wrapper for `Avatar.Fallback` from Base UI with muted background.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-avatar-03" description="Avatar with customizable offset rings" />

  <ShowcaseCard name="demo-p-avatar-04" description="Avatar with user icon fallback" />

  <ShowcaseCard name="demo-p-avatar-05" description="Avatar with dot indicators." />

  <ShowcaseCard name="demo-p-avatar-06" description="Avatar with verified badge" />

  <ShowcaseCard name="demo-p-avatar-07" description="Avatar group with overlapping edge" />

  <ShowcaseCard name="demo-p-avatar-08" description="Avatar with notification badge" />
</ShowcaseGrid>


# Badge
URL: https://www.spaceui.one/primitives/badge

***

title: Badge
description: Displays small colored label tags for status flags, counts, or categories, helping users quickly scan and spot key information.
preview: demo-p-badge-01
------------------------

## Installation

<ComponentInstallation name="primitives-badge" />

## Usage

```tsx
import { Badge } from '@/components/ui/badge'
```

```tsx
<Badge>Badge</Badge>
```

## Features

### Variants

All available badge variants in one overview: `default`, `secondary`, `outline`, `destructive`, `info`, `success`, `warning`, `error`.

<ComponentPreview name="demo-p-badge-01" />

### Sizes

Standard sizing options: `sm`, `default`, `lg`.

<ComponentPreview name="demo-p-badge-02" />

### Square / Numeric

Badges with equal aspect ratio for counts, indicators, or single characters.

<ComponentPreview name="demo-p-badge-03" />

### With Icon

<ComponentPreview name="demo-p-badge-04" />

### Link as Badge

<ComponentPreview name="demo-p-badge-05" />

## API Reference

This is a custom component using Base UI's `useRender` hook, not a direct Base UI wrapper.

### Badge

A badge component with variant and size options.

| Prop      | Type                                                                                                    | Default     | Description                                         |
| --------- | ------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------- |
| `variant` | `"default" \| "destructive" \| "error" \| "info" \| "outline" \| "secondary" \| "success" \| "warning"` | `"default"` | Controls the badge styling and color scheme         |
| `size`    | `"default" \| "sm" \| "lg"`                                                                             | `"default"` | Controls the badge size                             |
| `square`  | `boolean`                                                                                               | `false`     | Sets aspect-ratio square for numbers or icon badges |
| `render`  | `React.ReactElement`                                                                                    | -           | Render as a different element (e.g., Link)          |

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-badge-06" description="Badge with count" />

  <ShowcaseCard name="demo-p-badge-07" description="Full rounded badge (pill)" />

  <ShowcaseCard name="demo-p-badge-08" description="Badge with number after text" />

  <ShowcaseCard name="demo-p-badge-09" description="Status badges with indicator dots" />
</ShowcaseGrid>


# Breadcrumb
URL: https://www.spaceui.one/primitives/breadcrumb

***

title: Breadcrumb
description: Displays a horizontal trail of links showing the user’s current location within the page hierarchy, making navigation back to parent pages simple.
preview:
name: demo-p-breadcrumb-01
contained: true
---------------

## Installation

<ComponentInstallation name="primitives-breadcrumb" />

## Usage

```tsx
import {
  Breadcrumb,
  BreadcrumbEllipsis,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from '@/components/ui/breadcrumb'
```

```tsx
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbEllipsis />
    </BreadcrumbItem>
    <BreadcrumbItem>
      <BreadcrumbLink href="/components">Components</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

## Features

### Custom Separator

Customizes the separator element between breadcrumb items using the `BreadcrumbSeparator` component.

<ComponentPreview name="demo-p-breadcrumb-02" />

### With Icons

Breadcrumb items rendered with leading contextual icons.

<ComponentPreview name="demo-p-breadcrumb-05" />

## API Reference

This is a custom component, not a Base UI wrapper.

### Breadcrumb

Root navigation container with `aria-label="breadcrumb"`.

### BreadcrumbList

Ordered list container for breadcrumb items.

### BreadcrumbItem

Individual breadcrumb item container.

### BreadcrumbLink

Link element for navigable breadcrumb items. Supports the `render` prop to use custom link components (e.g., Next.js Link).

| Prop     | Type                 | Default | Description                                        |
| -------- | -------------------- | ------- | -------------------------------------------------- |
| `render` | `React.ReactElement` | -       | Render as a different element (e.g., Next.js Link) |

### BreadcrumbPage

Non-interactive element representing the current page. Includes `aria-current="page"`.

### BreadcrumbSeparator

Separator between breadcrumb items. Defaults to a chevron icon but accepts custom children.

### BreadcrumbEllipsis

Ellipsis indicator for collapsed breadcrumb items.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-breadcrumb-03" description="Breadcrumb with home icon for home link only" />

  <ShowcaseCard name="demo-p-breadcrumb-04" description="Breadcrumb with folders icon menu" />

  <ShowcaseCard name="demo-p-breadcrumb-06" description="Breadcrumb with dot separators" />

  <ShowcaseCard name="demo-p-breadcrumb-07" description="Breadcrumb with select dropdown" />
</ShowcaseGrid>

### With custom separator

<ComponentPreview name="demo-p-breadcrumb-02" />


# Button
URL: https://www.spaceui.one/primitives/button

***

title: Button
description: Allows users to trigger actions, submit forms, or navigate with a single click, providing clear visual feedback and hover effects.
links:
doc: [https://base-ui.com/react/components/button#api-reference](https://base-ui.com/react/components/button#api-reference)
preview:
name: demo-p-button-01
contained: false
----------------

## Installation

<ComponentInstallation name="primitives-button" />

## Usage

```tsx
import { Button } from '@/components/ui/button'
```

```tsx
<Button>Button</Button>
```

## Link

You can use the [`render`](https://base-ui.com/react/utils/use-render#migrating-from-radix-ui) prop to render another element (like Next.js `Link` or React Router) with button styles.

```tsx
import Link from 'next/link'
import { Button } from '@/components/ui/button'

export function LinkAsButton() {
  return <Button render={<Link href="/login" />}>Login</Button>
}
```

## Features

### Variants

### Sizes

Standard sizing options: `xs`, `sm`, `default`, `lg`, `xl`.

<ComponentPreview name="demo-p-button-02" />

### Icon Sizes

Square button sizes designed specifically for single icons: `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl`.

<ComponentPreview name="demo-p-button-04" />

### Loading State

Support for native loading spinners via the `loading` prop.

<ComponentPreview name="demo-p-button-29" />

### Disabled

Button rendered in a disabled state via the `disabled` prop.

<ComponentPreview name="demo-p-button-03" />

### With Icon

<ComponentPreview name="demo-p-button-05" />

### Link as Button

<ComponentPreview name="demo-p-button-06" />

## API Reference

### Button Props

| Prop       | Type                                                                                                      | Default     | Description                                           |
| :--------- | :-------------------------------------------------------------------------------------------------------- | :---------- | :---------------------------------------------------- |
| `variant`  | `"default" \| "destructive" \| "destructive-outline" \| "ghost" \| "link" \| "outline" \| "secondary"`    | `"default"` | Controls the button visual style                      |
| `size`     | `"default" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs" \| "lg" \| "sm" \| "xl" \| "xs"` | `"default"` | Controls the button size                              |
| `loading`  | `boolean`                                                                                                 | `false`     | Shows a spinner and disables the button while loading |
| `disabled` | `boolean`                                                                                                 | `false`     | Disables pointer interactions and dims appearance     |
| `render`   | `React.ReactElement`                                                                                      | -           | Polymorphic render prop (e.g. Next.js Link)           |

When `loading` is `true`, the component:

* Renders a spinner (`data-slot="button-loading-indicator"`)
* Adds `data-loading` on the button root
* Disables interaction and sets `aria-disabled="true"`
* Preserves button layout without jumping

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-button-07" description="Custom loading button with manual Spinner" />

  <ShowcaseCard name="demo-p-button-08" description="Expandable show more/less toggle button" />

  <ShowcaseCard name="demo-p-button-09" description="Back link button with chevron" />

  <ShowcaseCard name="demo-p-button-10" description="Card-style button with heading and description" />

  <ShowcaseCard name="demo-p-button-11" description="Directional pad control buttons" />

  <ShowcaseCard name="demo-p-button-12" description="Outline like button with count" />

  <ShowcaseCard name="demo-p-button-13" description="Social login icon buttons" />

  <ShowcaseCard name="demo-p-button-14" description="Star button with count badge" />

  <ShowcaseCard name="demo-p-button-15" description="Button group with QR code icon and sign in" />

  <ShowcaseCard name="demo-p-button-16" description="Button with avatar" />

  <ShowcaseCard name="demo-p-button-17" description="Pill-shaped button with rounded-full styling" />

  <ShowcaseCard name="demo-p-button-18" description="Button with animated arrow on hover" />

  <ShowcaseCard name="demo-p-button-19" description="Button with keyboard shortcut indicator" />

  <ShowcaseCard name="demo-p-button-20" description="Button with notification badge" />

  <ShowcaseCard name="demo-p-button-21" description="Paired buttons (Cancel/Save)" />

  <ShowcaseCard name="demo-p-button-22" description="Button with animated status dot" />

  <ShowcaseCard name="demo-p-button-23" description="Icon-only copy button with feedback" />

  <ShowcaseCard name="demo-p-button-24" description="Copy button with feedback" />

  <ShowcaseCard name="demo-p-button-25" description="Rotating icon button (FAB-style toggle)" />

  <ShowcaseCard name="demo-p-button-26" description="Social login buttons (Google, X, GitHub)" />

  <ShowcaseCard name="demo-p-button-27" description="Hamburger menu button with animated icon" />

  <ShowcaseCard name="demo-p-button-28" description="Download button with progress and cancel action" />
</ShowcaseGrid>


# Calendar
URL: https://www.spaceui.one/primitives/calendar

***

title: Calendar
description: Displays an interactive month grid that lets users browse dates, select individual days, or choose date ranges for scheduling.

links:
doc: [https://daypicker.dev/](https://daypicker.dev/)
preview: demo-p-calendar-01
---------------------------

## Installation

<ComponentInstallation name="primitives-calendar" />

## Usage

```tsx
import { Calendar } from '@/components/ui/calendar'
```

```tsx
<Calendar />
```

## Features

### Disabled Dates

Calendar configured with specific disabled dates and range constraints.

<ComponentPreview name="demo-p-calendar-07" />

## API Reference

This component wraps [@daypicker/react](https://daypicker.dev/) with custom styling.

### Calendar

A calendar component for date selection.

| Prop              | Type                                                             | Default    | Description                                                |
| ----------------- | ---------------------------------------------------------------- | ---------- | ---------------------------------------------------------- |
| `mode`            | `"single" \| "multiple" \| "range"`                              | `"single"` | Selection mode for the calendar                            |
| `captionLayout`   | `"label" \| "dropdown" \| "dropdown-months" \| "dropdown-years"` | `"label"`  | Caption layout - use `"dropdown"` for month/year dropdowns |
| `selected`        | `Date \| Date[] \| DateRange`                                    | -          | The selected date(s)                                       |
| `onSelect`        | `(date: Date \| Date[] \| DateRange) => void`                    | -          | Callback when date selection changes                       |
| `showOutsideDays` | `boolean`                                                        | `true`     | Show days from adjacent months                             |
| `startMonth`      | `Date`                                                           | -          | First month to show in dropdown navigation                 |
| `endMonth`        | `Date`                                                           | -          | Last month to show in dropdown navigation                  |
| `buttonVariant`   | `"ghost" \| "outline" \| ...`                                    | `"ghost"`  | Button variant for navigation buttons                      |
| `classNames`      | `object`                                                         | -          | Custom class names for calendar parts                      |
| `components`      | `object`                                                         | -          | Custom components to override defaults                     |

For the full list of props, see the [@daypicker/react documentation](https://daypicker.dev/).

### Customizing Cell Size

The calendar uses CSS custom properties for cell sizing. By default, the cell size is `--spacing(9)` on mobile and `--spacing(8)` on larger screens:

```css
[--cell-size:--spacing(10)] sm:[--cell-size:--spacing(9)]
```

You can customize the cell size by passing a custom `className`:

```tsx
<Calendar className="[--cell-size:--spacing(11)]" />
```

Or use responsive values:

```tsx
<Calendar className="[--cell-size:--spacing(11)] sm:[--cell-size:--spacing(10)]" />
```

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-calendar-02" description="Calendar with custom cell size" />

  <ShowcaseCard name="demo-p-calendar-03" description="Calendar with date range selection" />

  <ShowcaseCard name="demo-p-calendar-04" description="Calendar with month/year dropdown navigation" />

  <ShowcaseCard name="demo-p-calendar-05" description="Calendar with custom Select dropdown for month/year" />

  <ShowcaseCard name="demo-p-calendar-06" description="Calendar with Combobox dropdown for month/year" />

  <ShowcaseCard name="demo-p-calendar-08" description="Calendar with multiple date selection" />

  <ShowcaseCard name="demo-p-calendar-09" description="Calendar with rounded day buttons" />

  <ShowcaseCard name="demo-p-calendar-10" description="Calendar with rounded range selection style" />

  <ShowcaseCard name="demo-p-calendar-11" description="Calendar with right-aligned navigation" />

  <ShowcaseCard name="demo-p-calendar-12" description="Calendar with week numbers" />

  <ShowcaseCard name="demo-p-calendar-13" description="Calendar with year-only combobox dropdown" />

  <ShowcaseCard name="demo-p-calendar-14" description="Calendar without arrow navigation (dropdown only)" />

  <ShowcaseCard name="demo-p-calendar-15" description="Calendar with current month button" />

  <ShowcaseCard name="demo-p-calendar-16" description="Calendar with today button" />

  <ShowcaseCard name="demo-p-calendar-17" description="Calendar with date input" />

  <ShowcaseCard name="demo-p-calendar-18" description="Calendar with time input" />

  <ShowcaseCard name="demo-p-calendar-19" description="Calendar with time slots (appointment picker)" />

  <ShowcaseCard name="demo-p-calendar-20" description="Calendar with date presets" />

  <ShowcaseCard name="demo-p-calendar-21" description="Range calendar with date presets" />

  <ShowcaseCard name="demo-p-calendar-22" description="Two months calendar" />

  <ShowcaseCard name="demo-p-calendar-23" description="Three months calendar" />

  <ShowcaseCard name="demo-p-calendar-24" description="Pricing calendar with custom day buttons" />

  <ShowcaseCard name="demo-p-calendar-25" description="Calendar with 24-hour autocomplete time input" />
</ShowcaseGrid>


# Card
URL: https://www.spaceui.one/primitives/card

***

title: Card
description: Groups related information, images, and action buttons into a bordered container, creating clear visual sections on the page.
preview: demo-p-card-01
-----------------------

## Installation

<ComponentInstallation name="primitives-card" />

## Usage

```tsx
import { Card, CardDescription, CardFooter, CardHeader, CardPanel, CardTitle } from '@/components/ui/card'
```

```tsx
<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
    <CardDescription>Description</CardDescription>
  </CardHeader>
  <CardPanel>Content</CardPanel>
  <CardFooter>Footer</CardFooter>
</Card>
```

## Anatomy

```tsx
<Card>
  <CardHeader>
    <CardTitle />
    <CardDescription />
  </CardHeader>
  <CardContent />
  <CardFooter />
</Card>
```

## Features

### CardFrame with header action

Use `CardFrame` when you need a framed layout with an action button in the header (e.g. "Add", "Connect"):

```tsx
import {
  CardFrame,
  CardFrameAction,
  CardFrameDescription,
  CardFrameHeader,
  CardFrameTitle,
  CardPanel,
} from '@/components/ui/card'
import { Button } from '@/components/ui/button'
import { PlusIcon } from 'lucide-react'

export function FramedCardExample() {
  return (
    <CardFrame>
      <CardFrameHeader>
        <CardFrameTitle>Project</CardFrameTitle>
        <CardFrameDescription>Manage your project settings and configuration</CardFrameDescription>
        <CardFrameAction>
          <Button variant="outline">
            <PlusIcon />
            Add
          </Button>
        </CardFrameAction>
      </CardFrameHeader>
      <Card>
        <CardPanel>Content</CardPanel>
      </Card>
    </CardFrame>
  )
}
```

## API Reference

### Card Props

| Prop     | Type                 | Default | Description                   |
| :------- | :------------------- | :------ | :---------------------------- |
| `render` | `React.ReactElement` | -       | Render as a different element |

### CardHeader Props

Header section container. Supports the `render` prop.

### CardTitle Props

Title text for the card. Supports the `render` prop.

### CardDescription Props

Description text for the card. Supports the `render` prop.

### CardAction Props

Container for action buttons in the header. Automatically positions to the right. Supports the `render` prop.

### CardPanel Props

Main content area of the card. Also exported as `CardContent`. Supports the `render` prop.

### CardFooter Props

Footer section for the card. Supports the `render` prop.

### CardFrame Props

Root container for the framed card layout. Supports the `render` prop.

### CardFrameHeader Props

Header section for the frame. Contains title, description, and optionally `CardFrameAction`. Supports the `render` prop.

### CardFrameTitle Props

Title text for the frame. Supports the `render` prop.

### CardFrameDescription Props

Description text for the frame. Supports the `render` prop.

### CardFrameAction Props

Container for action buttons in the header. Positioned in the top-right via CSS grid. Supports the `render` prop.

### CardFrameFooter Props

Footer section for the frame. Supports the `render` prop.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-card-02" description="Authentication card with actions" />

  <ShowcaseCard name="demo-p-card-03" description="Authentication card with separators" />

  <ShowcaseCard name="demo-p-card-04" description="Framed card with footer" />

  <ShowcaseCard name="demo-p-card-05" description="Framed card with header" />

  <ShowcaseCard name="demo-p-card-06" description="Framed card with header and footer" />

  <ShowcaseCard name="demo-p-card-07" description="Framed card with no rounded bottom" />

  <ShowcaseCard name="demo-p-card-08" description="Card within a frame and footer" />

  <ShowcaseCard name="demo-p-card-09" description="Card within a frame and footer" />

  <ShowcaseCard name="demo-p-card-10" description="Card within a frame with header and footer" />

  <ShowcaseCard name="demo-p-card-11" description="CardFrame with header action" />
</ShowcaseGrid>


# Checkbox Group
URL: https://www.spaceui.one/primitives/checkbox-group

***

title: Checkbox Group
description: Groups multiple related checkboxes together under a single control, making it easy for users to select one or several choices.

links:
doc: [https://base-ui.com/react/components/checkbox-group#api-reference](https://base-ui.com/react/components/checkbox-group#api-reference)
preview: demo-p-checkbox-group-01
---------------------------------

## Installation

<ComponentInstallation name="primitives-checkbox-group" />

## Usage

```tsx
import { Checkbox } from '@/components/ui/checkbox'
import { CheckboxGroup } from '@/components/ui/checkbox-group'
```

```tsx
<CheckboxGroup>
  <Label>
    <Checkbox defaultChecked />
    Next.js
  </Label>
  <Label>
    <Checkbox />
    Vite
  </Label>
  <Label>
    <Checkbox />
    Astro
  </Label>
</CheckboxGroup>
```

## Features

### Disabled Items

Checkbox group with individual disabled option items.

<ComponentPreview name="demo-p-checkbox-group-02" />

## API Reference

### CheckboxGroup

Styled wrapper for `CheckboxGroup` from Base UI. Provides shared state management for a group of checkboxes with flex column layout.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-checkbox-group-03" description="Checkbox group with parent checkbox" />

  <ShowcaseCard name="demo-p-checkbox-group-04" description="Nested checkbox group with parent" />

  <ShowcaseCard name="demo-p-checkbox-group-05" description="Checkbox group form" />
</ShowcaseGrid>


# Checkbox
URL: https://www.spaceui.one/primitives/checkbox

***

title: Checkbox
description: Allows users to turn a single option on or off, or select multiple items from a list with clear checkmarks and partial states.

links:
doc: [https://base-ui.com/react/components/checkbox#api-reference](https://base-ui.com/react/components/checkbox#api-reference)
preview: demo-p-checkbox-01
---------------------------

## Installation

<ComponentInstallation name="primitives-checkbox" />

## Usage

```tsx
import { Checkbox } from '@/components/ui/checkbox'
```

```tsx
<Checkbox />
```

## Anatomy

```tsx
<Checkbox>
  <CheckboxIndicator />
</Checkbox>
```

## Features

### Sizes

Checkboxes in `sm`, `default`, and `lg` sizes.

<ComponentPreview name="demo-p-checkbox-02" />

## Accessibility

* Follows the [WAI-ARIA Checkbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/).

### Keyboard Interactions

| Key              | Action                                                    |
| :--------------- | :-------------------------------------------------------- |
| <Kbd>Space</Kbd> | Toggles the checkbox state between checked and unchecked. |

## API Reference

### Checkbox

Styled wrapper for `Checkbox.Root` from Base UI. Includes a built-in indicator with checkmark and indeterminate icons.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-checkbox-03" description="Card-style checkbox" />

  <ShowcaseCard name="demo-p-checkbox-04" description="Checkbox form" />
</ShowcaseGrid>


# Collapsible
URL: https://www.spaceui.one/primitives/collapsible

***

title: Collapsible
description: Hides extra content behind a simple toggle button, allowing users to expand and read details only when they need them.

links:
doc: [https://base-ui.com/react/components/collapsible#api-reference](https://base-ui.com/react/components/collapsible#api-reference)
preview: demo-p-collapsible-01
------------------------------

## Installation

<ComponentInstallation name="primitives-collapsible" />

## Usage

```tsx
import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from '@/components/ui/collapsible'
```

```tsx
<Collapsible>
  <CollapsibleTrigger>Can I access the file in the cloud?</CollapsibleTrigger>
  <CollapsiblePanel>Yes, you can access the file in the cloud.</CollapsiblePanel>
</Collapsible>
```

## Anatomy

```tsx
<Collapsible>
  <CollapsibleTrigger />
  <CollapsiblePanel />
</Collapsible>
```

## Accessibility

* Adheres to the WAI-ARIA disclosure pattern with `aria-expanded` state updates.

### Keyboard Interactions

| Key                                 | Action                                   |
| :---------------------------------- | :--------------------------------------- |
| <Kbd>Space</Kbd> / <Kbd>Enter</Kbd> | Toggles the expanded state of the panel. |

## API Reference

### Collapsible

Root component. Alias for `Collapsible.Root` from Base UI.

### CollapsibleTrigger

Trigger button that toggles the collapsible panel. Styled wrapper for `Collapsible.Trigger` from Base UI.

### CollapsiblePanel

Collapsible content panel. Styled wrapper for `Collapsible.Panel` from Base UI with animated height transitions. Also exported as `CollapsibleContent`.


# Combobox
URL: https://www.spaceui.one/primitives/combobox

***

title: Combobox
description: Combines a text search input with a dropdown menu, allowing users to filter and select options from large lists easily.

links:
doc: [https://base-ui.com/react/components/combobox#api-reference](https://base-ui.com/react/components/combobox#api-reference)
preview: demo-p-combobox-01
---------------------------

## Installation

<ComponentInstallation name="primitives-combobox" />

## Usage

### Single Selection

```tsx
import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
} from '@/components/ui/combobox'

const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
  { value: "grape", label: "Grape" },
]

<Combobox items={items}>
  <ComboboxInput placeholder="Select an item..." />
  <ComboboxPopup>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => <ComboboxItem key={item.value} value={item}>{item.label}</ComboboxItem>}
    </ComboboxList>
  </ComboboxPopup>
</Combobox>
```

## Anatomy

```tsx
<Combobox>
  <ComboboxInput />
  <ComboboxPopup>
    <ComboboxList>
      <ComboboxItem />
      <ComboboxEmpty />
    </ComboboxList>
  </ComboboxPopup>
</Combobox>
```

### Multiple Selection

```tsx
import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxEmpty,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxValue,
} from '@/components/ui/combobox'

const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
  { value: "grape", label: "Grape" },
]

<Combobox items={items} multiple>
  <ComboboxChips>
    <ComboboxValue>
      {(value: { value: string; label: string }[]) => (
        <>
          {value?.map((item) => (
            <ComboboxChip key={item.value} aria-label={item.value}>
              {item.label}
            </ComboboxChip>
          ))}
          <ComboboxChipsInput
            placeholder={value.length > 0 ? undefined : "Select an item..."}
            aria-label="Select an item"
          />
        </>
      )}
    </ComboboxValue>
  </ComboboxChips>
  <ComboboxPopup>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => <ComboboxItem value={item}>{item.label}</ComboboxItem>}
    </ComboboxList>
  </ComboboxPopup>
</Combobox>
```

## Features

### Sizes

Combobox inputs in `sm`, `default`, and `lg` sizes.

<ComponentPreview name="demo-p-combobox-02" />

## Accessibility

* Follows the [WAI-ARIA Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
* Search input controls list focus via `aria-activedescendant`.

### Keyboard Interactions

| Key                  | Action                                           |
| :------------------- | :----------------------------------------------- |
| <Kbd>ArrowDown</Kbd> | Moves focus to the next matching suggestion.     |
| <Kbd>ArrowUp</Kbd>   | Moves focus to the previous matching suggestion. |
| <Kbd>Enter</Kbd>     | Confirms the currently highlighted suggestion.   |
| <Kbd>Escape</Kbd>    | Closes the suggestion list popup.                |

## API Reference

### Combobox

The root combobox component. Manages the combobox state and provides context to child components.

| Prop       | Type                                    | Description                                   |
| ---------- | --------------------------------------- | --------------------------------------------- |
| `items`    | `readonly unknown[]`                    | The array of items to display in the combobox |
| `multiple` | `boolean`                               | Whether to allow multiple selection           |
| `open`     | `boolean`                               | Controls whether the popup is open            |
| `...props` | `React.ComponentProps<typeof Combobox>` | All Base UI Combobox props are supported      |

### ComboboxInput

The input field component for single selection mode with extended features for size variants and addon support.

| Prop           | Type                         | Default     | Description                                                                                     |
| -------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| `size`         | `"sm" \| "default" \| "lg"`  | `"default"` | The size variant of the input field                                                             |
| `startAddon`   | `React.ReactNode`            | -           | Element to display at the start (left side) of the input, such as an icon                       |
| `showTrigger`  | `boolean`                    | `true`      | Whether to display a trigger button (chevron icon) on the right side of the input               |
| `showClear`    | `boolean`                    | `false`     | Whether to display a clear button (X icon) on the right side of the input when there is a value |
| `triggerProps` | `Combobox.Trigger.Props`     | -           | Props forwarded to the internal trigger button, useful for overriding `aria-label`              |
| `clearProps`   | `Combobox.Clear.Props`       | -           | Props forwarded to the internal clear button, useful for overriding `aria-label`                |
| `className`    | `string`                     | -           | Additional CSS classes to apply to the component                                                |
| `...props`     | Base UI Combobox Input props | -           | All standard combobox input attributes are supported                                            |

### ComboboxPopup

The popup container that displays the combobox options.

| Prop          | Type                                          | Default    | Description                                                                                                |
| ------------- | --------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- |
| `side`        | `"top" \| "bottom" \| "left" \| "right"`      | `"bottom"` | Preferred edge to position the popup relative to the trigger/input                                         |
| `sideOffset`  | `number`                                      | `4`        | Distance from the trigger in pixels                                                                        |
| `align`       | `"start" \| "center" \| "end"`                | `"center"` | Alignment relative to the trigger along the cross-axis                                                     |
| `alignOffset` | `number`                                      | `0`        | Distance in pixels to shift the popup along the alignment axis                                             |
| `anchor`      | `Element \| null \| React.RefObject<Element>` | -          | Custom anchor element or ref to anchor the popup against                                                   |
| `portalProps` | `Combobox.Portal.Props`                       | -          | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Combobox portal API |
| `className`   | `string`                                      | -          | Additional CSS classes to apply to the component                                                           |
| `...props`    | Base UI Combobox Popup props                  | -          | All standard combobox popup attributes are supported                                                       |

### ComboboxList

A scrollable container for combobox items.

| Prop        | Type                        | Description                                         |
| ----------- | --------------------------- | --------------------------------------------------- |
| `className` | `string`                    | Additional CSS classes to apply to the component    |
| `...props`  | Base UI Combobox List props | All standard combobox list attributes are supported |

### ComboboxItem

An individual selectable combobox item.

| Prop        | Type                        | Description                                         |
| ----------- | --------------------------- | --------------------------------------------------- |
| `value`     | `unknown`                   | The value of the item                               |
| `className` | `string`                    | Additional CSS classes to apply to the component    |
| `...props`  | Base UI Combobox Item props | All standard combobox item attributes are supported |

### ComboboxEmpty

Displays a message when no results are found.

| Prop        | Type                         | Description                                          |
| ----------- | ---------------------------- | ---------------------------------------------------- |
| `className` | `string`                     | Additional CSS classes to apply to the component     |
| `...props`  | Base UI Combobox Empty props | All standard combobox empty attributes are supported |

### ComboboxGroup

Groups related combobox items together.

| Prop        | Type                         | Description                                          |
| ----------- | ---------------------------- | ---------------------------------------------------- |
| `items`     | `readonly unknown[]`         | The array of items in this group                     |
| `className` | `string`                     | Additional CSS classes to apply to the component     |
| `...props`  | Base UI Combobox Group props | All standard combobox group attributes are supported |

### ComboboxGroupLabel

Displays a label for a combobox group.

| Prop        | Type                               | Description                                                |
| ----------- | ---------------------------------- | ---------------------------------------------------------- |
| `className` | `string`                           | Additional CSS classes to apply to the component           |
| `...props`  | Base UI Combobox Group Label props | All standard combobox group label attributes are supported |

### ComboboxCollection

Used to wrap items within a group for rendering.

| Prop       | Type                              | Description                                               |
| ---------- | --------------------------------- | --------------------------------------------------------- |
| `...props` | Base UI Combobox Collection props | All standard combobox collection attributes are supported |

### ComboboxChips

Container for displaying selected chips in multiple selection mode.

| Prop         | Type                          | Description                                                   |
| ------------ | ----------------------------- | ------------------------------------------------------------- |
| `startAddon` | `React.ReactNode`             | Element to display at the start (left side) of the chips area |
| `className`  | `string`                      | Additional CSS classes to apply to the component              |
| `...props`   | `React.ComponentProps<'div'>` | All standard div attributes are supported                     |

### ComboboxChipsInput

The input field component for use inside `ComboboxChips` in multiple selection mode. This is a minimal input without the wrapper, trigger, or clear button.

| Prop        | Type                         | Default     | Description                                          |
| ----------- | ---------------------------- | ----------- | ---------------------------------------------------- |
| `size`      | `"sm" \| "default" \| "lg"`  | `"default"` | The size variant of the input field                  |
| `className` | `string`                     | -           | Additional CSS classes to apply to the component     |
| `...props`  | Base UI Combobox Input props | -           | All standard combobox input attributes are supported |

### ComboboxChip

An individual chip representing a selected item in multiple selection mode.

| Prop          | Type                        | Description                                                                       |
| ------------- | --------------------------- | --------------------------------------------------------------------------------- |
| `removeProps` | `Combobox.ChipRemove.Props` | Props forwarded to the internal remove button, useful for overriding `aria-label` |
| `className`   | `string`                    | Additional CSS classes to apply to the component                                  |
| `...props`    | Base UI Combobox Chip props | All standard combobox chip attributes are supported                               |

### ComboboxValue

Provides access to the current value for custom rendering.

| Prop       | Type                         | Description                                          |
| ---------- | ---------------------------- | ---------------------------------------------------- |
| `...props` | Base UI Combobox Value props | All standard combobox value attributes are supported |

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-combobox-03" description="Large combobox" />

  <ShowcaseCard name="demo-p-combobox-04" description="Combobox with label" />

  <ShowcaseCard name="demo-p-combobox-05" description="Combobox auto highlighting the first option" />

  <ShowcaseCard name="demo-p-combobox-06" description="Combobox with clear button" />

  <ShowcaseCard name="demo-p-combobox-07" description="Combobox with grouped items" />

  <ShowcaseCard name="demo-p-combobox-08" description="Combobox with multiple selection" />

  <ShowcaseCard name="demo-p-combobox-09" description="Combobox with input inside popup" />

  <ShowcaseCard name="demo-p-combobox-10" description="Combobox form" />

  <ShowcaseCard name="demo-p-combobox-11" description="Combobox multiple form" />

  <ShowcaseCard name="demo-p-combobox-12" description="Combobox with start addon" />

  <ShowcaseCard name="demo-p-combobox-13" description="Combobox multiple with start addon" />

  <ShowcaseCard name="demo-p-combobox-14" description="Pill-shaped combobox" />

  <ShowcaseCard name="demo-p-combobox-15" description="Timezone combobox" />

  <ShowcaseCard name="demo-p-combobox-16" description="Timezone combobox with search input" />

  <ShowcaseCard name="demo-p-combobox-17" description="Combobox with select trigger" />

  <ShowcaseCard name="demo-p-combobox-18" description="Combobox multiple with stacked chips" />

  <ShowcaseCard name="demo-p-combobox-19" description="Combobox multiple with stacked divided chips" />
</ShowcaseGrid>


# Command
URL: https://www.spaceui.one/primitives/command

***

title: Command
description: Provides a searchable command menu that lets users navigate pages, find resources, and trigger shortcuts directly from their keyboard.

links:
doc: [https://base-ui.com/react/components/autocomplete#api-reference](https://base-ui.com/react/components/autocomplete#api-reference)
preview: demo-p-command-01
--------------------------

## Installation

<ComponentInstallation name="primitives-command" />

## Usage

```tsx
import {
  Command,
  CommandCollection,
  CommandDialog,
  CommandDialogPopup,
  CommandDialogTrigger,
  CommandEmpty,
  CommandFooter,
  CommandGroup,
  CommandGroupLabel,
  CommandInput,
  CommandItem,
  CommandList,
  CommandPanel,
  CommandSeparator,
  CommandShortcut,
} from '@/components/ui/command'
import { Button } from '@/components/ui/button'

const items = [
  { value: 'linear', label: 'Linear' },
  { value: 'figma', label: 'Figma' },
  { value: 'slack', label: 'Slack' },
]

export default function SpaceUI() {
  return (
    <CommandDialog>
      <CommandDialogTrigger render={<Button variant="outline" />}>Open Command Palette</CommandDialogTrigger>

      <CommandDialogPopup>
        <Command items={items}>
          <CommandInput placeholder="Search..." />
          <CommandEmpty>No results found.</CommandEmpty>
          <CommandList>
            {(item) => (
              <CommandItem key={item.value} value={item.value}>
                {item.label}
              </CommandItem>
            )}
          </CommandList>
        </Command>
      </CommandDialogPopup>
    </CommandDialog>
  )
}
```

## Anatomy

```tsx
<Command>
  <CommandInput />
  <CommandList>
    <CommandEmpty />
    <CommandGroup>
      <CommandItem>
        <CommandShortcut />
      </CommandItem>
    </CommandGroup>
  </CommandList>
</Command>
```

## Accessibility

* Keyboard-first navigation with live search announcement.
* Selection updates seamlessly using `aria-selected` attributes.

### Keyboard Interactions

| Key                  | Action                                        |
| :------------------- | :-------------------------------------------- |
| <Kbd>ArrowDown</Kbd> | Moves highlight to the next command item.     |
| <Kbd>ArrowUp</Kbd>   | Moves highlight to the previous command item. |
| <Kbd>Enter</Kbd>     | Executes the highlighted action.              |
| <Kbd>Escape</Kbd>    | Closes the command palette.                   |

## API Reference

### Command

The root component that wraps the autocomplete functionality. It's an alias for `Autocomplete.Root` with sensible defaults for command palette behavior: `autoHighlight="always"`, `keepHighlight={true}`, and `open={true}`.

| Prop            | Type                                   | Default    | Description                                  |
| --------------- | -------------------------------------- | ---------- | -------------------------------------------- |
| `items`         | `readonly unknown[]`                   | -          | The array of items to display in the command |
| `open`          | `boolean`                              | `true`     | Controls whether the command is open         |
| `autoHighlight` | `boolean \| "always"`                  | `"always"` | Controls automatic highlighting of items     |
| `keepHighlight` | `boolean`                              | `true`     | Whether to maintain highlight state          |
| `...props`      | `React.ComponentProps<typeof Command>` | -          | All Base UI Autocomplete props are supported |

### CommandDialog

A wrapper component that provides the dialog root functionality. It's an alias for `Dialog.Root` from Base UI.

| Prop           | Type                 | Description                                  |
| -------------- | -------------------- | -------------------------------------------- |
| `open`         | `boolean`            | Controls whether the dialog is open          |
| `onOpenChange` | `function`           | Callback fired when the open state changes   |
| `...props`     | Base UI Dialog props | All standard dialog attributes are supported |

### CommandDialogTrigger

The trigger button that opens the command dialog. Renders as a button by default.

| Prop        | Type                         | Description                                          |
| ----------- | ---------------------------- | ---------------------------------------------------- |
| `render`    | `React.ReactElement`         | Element to render as the trigger                     |
| `className` | `string`                     | Additional CSS classes to apply to the component     |
| `...props`  | Base UI Dialog Trigger props | All standard dialog trigger attributes are supported |

### CommandDialogPopup

The popup content container that displays the command palette inside a dialog.

| Prop          | Type                       | Description                                                                                              |
| ------------- | -------------------------- | -------------------------------------------------------------------------------------------------------- |
| `className`   | `string`                   | Additional CSS classes to apply to the component                                                         |
| `portalProps` | `Dialog.Portal.Props`      | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Dialog portal API |
| `...props`    | Base UI Dialog Popup props | All standard dialog popup attributes are supported                                                       |

### CommandInput

The search input field with an integrated search icon. Automatically includes a search icon via `startAddon` and is sized to `lg` by default.

| Prop          | Type                             | Description                                              |
| ------------- | -------------------------------- | -------------------------------------------------------- |
| `placeholder` | `string`                         | The placeholder text for the input                       |
| `className`   | `string`                         | Additional CSS classes to apply to the component         |
| `...props`    | Base UI Autocomplete Input props | All standard autocomplete input attributes are supported |

### CommandList

A scrollable container for command items. It wraps `AutocompleteList` with scroll functionality.

| Prop        | Type                            | Description                                             |
| ----------- | ------------------------------- | ------------------------------------------------------- |
| `className` | `string`                        | Additional CSS classes to apply to the component        |
| `...props`  | Base UI Autocomplete List props | All standard autocomplete list attributes are supported |

### CommandPanel

A container component that provides styling for command content outside of dialogs. Useful when building standalone command interfaces with a bordered, elevated appearance.

| Prop        | Type                          | Description                                      |
| ----------- | ----------------------------- | ------------------------------------------------ |
| `className` | `string`                      | Additional CSS classes to apply to the component |
| `...props`  | `React.ComponentProps<'div'>` | All standard div attributes are supported        |

### CommandEmpty

Displays a message when no results are found.

| Prop        | Type                             | Description                                              |
| ----------- | -------------------------------- | -------------------------------------------------------- |
| `className` | `string`                         | Additional CSS classes to apply to the component         |
| `...props`  | Base UI Autocomplete Empty props | All standard autocomplete empty attributes are supported |

### CommandGroup

Groups related command items together. Wraps `AutocompleteGroup`.

| Prop        | Type                             | Description                                              |
| ----------- | -------------------------------- | -------------------------------------------------------- |
| `items`     | `readonly unknown[]`             | The array of items in this group                         |
| `className` | `string`                         | Additional CSS classes to apply to the component         |
| `...props`  | Base UI Autocomplete Group props | All standard autocomplete group attributes are supported |

### CommandGroupLabel

Displays a label for a command group.

| Prop        | Type                                   | Description                                                    |
| ----------- | -------------------------------------- | -------------------------------------------------------------- |
| `className` | `string`                               | Additional CSS classes to apply to the component               |
| `...props`  | Base UI Autocomplete Group Label props | All standard autocomplete group label attributes are supported |

### CommandItem

An individual selectable command item. Extends `AutocompleteItem`.

| Prop        | Type                            | Description                                             |
| ----------- | ------------------------------- | ------------------------------------------------------- |
| `value`     | `unknown`                       | The value of the item                                   |
| `className` | `string`                        | Additional CSS classes to apply to the component        |
| `...props`  | Base UI Autocomplete Item props | All standard autocomplete item attributes are supported |

### CommandSeparator

A visual separator between command groups or items. Includes default vertical spacing with `my-2` className.

| Prop        | Type                                 | Description                                                                |
| ----------- | ------------------------------------ | -------------------------------------------------------------------------- |
| `className` | `string`                             | Additional CSS classes to apply to the component (default includes `my-2`) |
| `...props`  | Base UI Autocomplete Separator props | All standard autocomplete separator attributes are supported               |

### CommandShortcut

Displays keyboard shortcuts in a styled span element.

| Prop        | Type                           | Description                                      |
| ----------- | ------------------------------ | ------------------------------------------------ |
| `className` | `string`                       | Additional CSS classes to apply to the component |
| `...props`  | `React.ComponentProps<'span'>` | All standard span attributes are supported       |

### CommandFooter

A footer section for displaying hints or additional keyboard shortcuts. Renders as a styled `div` with padding and border.

| Prop        | Type                          | Description                                      |
| ----------- | ----------------------------- | ------------------------------------------------ |
| `className` | `string`                      | Additional CSS classes to apply to the component |
| `...props`  | `React.ComponentProps<'div'>` | All standard div attributes are supported        |

### CommandCollection

Used within `CommandGroup` to wrap items when using grouped data. It's an alias for `AutocompleteCollection` from the Autocomplete component.

| Prop       | Type                                  | Description                                                   |
| ---------- | ------------------------------------- | ------------------------------------------------------------- |
| `...props` | Base UI Autocomplete Collection props | All standard autocomplete collection attributes are supported |

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-command-02" description="Command palette with AI assistant" />
</ShowcaseGrid>

### With Keyboard Shortcut

You can add a keyboard shortcut to open the command palette:

```tsx
React.useEffect(() => {
  const down = (e: KeyboardEvent) => {
    if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
      e.preventDefault()
      setOpen((open) => !open)
    }
  }

  document.addEventListener('keydown', down)
  return () => document.removeEventListener('keydown', down)
}, [])
```

### With Grouped Items

```tsx
const groupedItems = [
  {
    value: "Suggestions",
    items: [
      { value: "linear", label: "Linear" },
      { value: "figma", label: "Figma" },
    ]
  },
  {
    value: "Commands",
    items: [
      { value: "clipboard", label: "Clipboard History" },
      { value: "settings", label: "System Preferences" },
    ]
  },
]

<Command items={groupedItems}>
  <CommandInput placeholder="Search..." />
  <CommandEmpty>No results found.</CommandEmpty>
  <CommandList>
    {(group, index) => (
      <React.Fragment key={group.value}>
        <CommandGroup items={group.items}>
          <CommandGroupLabel>{group.value}</CommandGroupLabel>
          <CommandCollection>
            {(item) => (
              <CommandItem key={item.value} value={item.value}>
                {item.label}
              </CommandItem>
            )}
          </CommandCollection>
        </CommandGroup>
        {index < groupedItems.length - 1 && <CommandSeparator />}
      </React.Fragment>
    )}
  </CommandList>
</Command>
```

### Standalone Command (Without Dialog)

You can use the Command component without a dialog wrapper:

```tsx
<Command open items={items}>
  <CommandInput placeholder="Type a command..." />
  <CommandEmpty>No results found.</CommandEmpty>
  <CommandList>
    {(item) => (
      <CommandItem key={item.value} value={item.value}>
        {item.label}
      </CommandItem>
    )}
  </CommandList>
</Command>
```


# Context Menu
URL: https://www.spaceui.one/primitives/context-menu

***

title: Context Menu
description: Opens a custom action menu right at the cursor position when users right-click or long-press an element on the screen.

links:
doc: [https://base-ui.com/react/components/context-menu#api-reference](https://base-ui.com/react/components/context-menu#api-reference)
preview: demo-p-context-menu-01
-------------------------------

## Installation

<ComponentInstallation name="primitives-context-menu" />

## Usage

```tsx
import {
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuGroup,
  ContextMenuGroupLabel,
  ContextMenuItem,
  ContextMenuLinkItem,
  ContextMenuPopup,
  ContextMenuRadioGroup,
  ContextMenuRadioItem,
  ContextMenuSeparator,
  ContextMenuSub,
  ContextMenuSubPopup,
  ContextMenuSubTrigger,
  ContextMenuTrigger,
} from '@/components/ui/context-menu'
```

```tsx
<ContextMenu>
  <ContextMenuTrigger className="flex h-32 items-center justify-center rounded-lg border border-dashed">
    Right click here
  </ContextMenuTrigger>
  <ContextMenuPopup>
    <ContextMenuItem>Back</ContextMenuItem>
    <ContextMenuItem>Forward</ContextMenuItem>
    <ContextMenuSeparator />
    <ContextMenuLinkItem render={<Link href="/docs" />}>Documentation</ContextMenuLinkItem>
    <ContextMenuSeparator />
    <ContextMenuSub>
      <ContextMenuSubTrigger>More tools</ContextMenuSubTrigger>
      <ContextMenuSubPopup>
        <ContextMenuItem>Inspect</ContextMenuItem>
        <ContextMenuItem>View source</ContextMenuItem>
      </ContextMenuSubPopup>
    </ContextMenuSub>
  </ContextMenuPopup>
</ContextMenu>
```

## Anatomy

```tsx
<ContextMenu>
  <ContextMenuTrigger />
  <ContextMenuPopup>
    <ContextMenuItem />
    <ContextMenuSeparator />
    <ContextMenuSub>
      <ContextMenuSubTrigger />
      <ContextMenuSubPopup />
    </ContextMenuSub>
  </ContextMenuPopup>
</ContextMenu>
```

## Accessibility

* Follows the [WAI-ARIA Menu Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/).
* Activated on right-click or long-press, with full keyboard traversal.

### Keyboard Interactions

| Key                                          | Action                                  |
| :------------------------------------------- | :-------------------------------------- |
| <Kbd>ArrowDown</Kbd> / <Kbd>ArrowUp</Kbd>    | Navigates through context menu options. |
| <Kbd>ArrowRight</Kbd> / <Kbd>ArrowLeft</Kbd> | Opens and closes submenus.              |
| <Kbd>Escape</Kbd>                            | Dismisses the context menu.             |

## API Reference

### ContextMenu

Root component. Alias for `ContextMenu.Root` from Base UI.

### ContextMenuTrigger

An area that opens the menu on right click or long press. Renders a `<div>` element.

### ContextMenuPopup

Popup container that displays the menu content at the pointer.

| Prop          | Type                                          | Default    | Description                                                                                                    |
| ------------- | --------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
| `side`        | `"top" \| "bottom" \| "left" \| "right"`      | `"bottom"` | Side of the anchor to position the popup                                                                       |
| `align`       | `"start" \| "center" \| "end"`                | `"center"` | Alignment relative to the anchor                                                                               |
| `sideOffset`  | `number`                                      | `4`        | Distance from the anchor in pixels                                                                             |
| `alignOffset` | `number`                                      | -          | Offset along the alignment axis                                                                                |
| `anchor`      | `Element \| null \| React.RefObject<Element>` | -          | Custom anchor element or ref to anchor the popup against                                                       |
| `portalProps` | `ContextMenu.Portal.Props`                    | -          | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Context Menu portal API |

### ContextMenuGroup

Groups related menu items. Alias for `ContextMenu.Group` from Base UI.

### ContextMenuItem

Individual menu item.

| Prop      | Type                         | Default     | Description                                           |
| --------- | ---------------------------- | ----------- | ----------------------------------------------------- |
| `inset`   | `boolean`                    | -           | Adds left padding to align with items that have icons |
| `variant` | `"default" \| "destructive"` | `"default"` | Controls the item styling                             |

**Using `inset`:** When mixing items with and without icons, use `inset` on icon-less items to maintain alignment:

```tsx
<ContextMenuItem><PencilIcon /> Edit</ContextMenuItem>
<ContextMenuItem inset>Properties</ContextMenuItem>
```

### ContextMenuLinkItem

Link menu item for navigation. **`LinkItem`** renders a native **`<a>`** when you pass **`href`**. Styled like **`ContextMenuItem`**.

| Prop           | Type                         | Default     | Description                                           |
| -------------- | ---------------------------- | ----------- | ----------------------------------------------------- |
| `inset`        | `boolean`                    | -           | Adds left padding to align with items that have icons |
| `variant`      | `"default" \| "destructive"` | `"default"` | Controls the item styling                             |
| `closeOnClick` | `boolean`                    | `true`      | Whether the menu closes when the link is clicked      |

If you were using **`ContextMenuItem render={<Link href="..." />}`**, migrate to **`ContextMenuLinkItem`** but **keep `render`** — do not replace it with **`href`** alone when using a router **`Link`**.

```tsx
<ContextMenuLinkItem render={<Link href="/docs" />}>Docs</ContextMenuLinkItem>
```

Use **`href`** only for plain anchor links:

```tsx
<ContextMenuLinkItem href="/docs">Docs</ContextMenuLinkItem>
```

### ContextMenuCheckboxItem

Checkbox menu item.

| Prop      | Type                    | Default     | Description                                              |
| --------- | ----------------------- | ----------- | -------------------------------------------------------- |
| `variant` | `"default" \| "switch"` | `"default"` | Display style - `switch` shows a toggle switch indicator |

### ContextMenuRadioGroup

Groups radio menu items. Alias for `ContextMenu.RadioGroup` from Base UI.

### ContextMenuRadioItem

Radio menu item. Styled wrapper for `ContextMenu.RadioItem` from Base UI.

### ContextMenuGroupLabel

Label for a menu group.

| Prop    | Type      | Default | Description                                           |
| ------- | --------- | ------- | ----------------------------------------------------- |
| `inset` | `boolean` | -       | Adds left padding to align with items that have icons |

### ContextMenuSeparator

Visual separator between menu items.

### ContextMenuShortcut

Displays keyboard shortcut text. Custom component (not a Base UI wrapper).

### ContextMenuSub

Submenu container. Alias for `ContextMenu.SubmenuRoot` from Base UI.

### ContextMenuSubTrigger

Trigger for opening a submenu.

| Prop    | Type      | Default | Description                                           |
| ------- | --------- | ------- | ----------------------------------------------------- |
| `inset` | `boolean` | -       | Adds left padding to align with items that have icons |

### ContextMenuSubPopup

Popup for submenu content.

| Prop          | Type                           | Default   | Description                                                                      |
| ------------- | ------------------------------ | --------- | -------------------------------------------------------------------------------- |
| `align`       | `"start" \| "center" \| "end"` | `"start"` | Alignment relative to the trigger                                                |
| `sideOffset`  | `number`                       | `0`       | Distance from the trigger in pixels                                              |
| `alignOffset` | `number`                       | `-5`      | Offset along the alignment axis. Defaults to `-5` when `align` is not `"center"` |

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-context-menu-02" description="Context menu with link items" />

  <ShowcaseCard name="demo-p-context-menu-03" description="Nested context menu" />

  <ShowcaseCard name="demo-p-context-menu-04" description="Context menu with checkbox items" />

  <ShowcaseCard name="demo-p-context-menu-05" description="Context menu with group labels" />

  <ShowcaseCard name="demo-p-context-menu-06" description="Context menu with icons" />

  <ShowcaseCard name="demo-p-context-menu-07" description="Context menu with radio group" />

  <ShowcaseCard name="demo-p-context-menu-08" description="Context menu with switch checkbox items" />
</ShowcaseGrid>


# Date Picker
URL: https://www.spaceui.one/primitives/date-picker

***

title: Date Picker
description: Combines a date input box with a popup calendar, letting users pick dates or ranges without navigating away from the form.
preview: demo-p-date-picker-01
------------------------------

## Installation

The Date Picker is a composition pattern combining Calendar, Popover, and Button primitives. Install each component:

<ComponentInstallation name="primitives-calendar" />

<ComponentInstallation name="primitives-popover" />

<ComponentInstallation name="primitives-button" />

## Usage

```tsx
import * as React from 'react'
import { format } from 'date-fns'
import { IconCalendar } from '@tabler/icons-react'

import { Button } from '@/components/ui/button'
import { Calendar } from '@/components/ui/calendar'
import { Popover, PopoverPopup, PopoverTrigger } from '@/components/ui/popover'

export default function SpaceUI() {
  const [date, setDate] = React.useState<Date>()

  return (
    <Popover>
      <PopoverTrigger render={<Button className="w-[280px] justify-start text-left font-normal" variant="outline" />}>
        <IconCalendar className="size-4" />
        {date ? format(date, 'PPP') : <span>Pick a date</span>}
      </PopoverTrigger>
      <PopoverPopup align="start" className="w-auto p-0">
        <Calendar mode="single" selected={date} onSelect={setDate} />
      </PopoverPopup>
    </Popover>
  )
}
```

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-date-picker-02" description="Date range picker" />

  <ShowcaseCard name="demo-p-date-picker-03" description="Date picker with field and dropdown navigation" />

  <ShowcaseCard name="demo-p-date-picker-04" description="Date picker with presets" />

  <ShowcaseCard name="demo-p-date-picker-05" description="Date picker with input" />

  <ShowcaseCard name="demo-p-date-picker-06" description="Date picker that closes on select" />

  <ShowcaseCard name="demo-p-date-picker-07" description="Multiple dates picker" />

  <ShowcaseCard name="demo-p-date-picker-08" description="Date picker with select-like trigger" />

  <ShowcaseCard name="demo-p-date-picker-09" description="Two months calendar with range date" />
</ShowcaseGrid>


# Dialog
URL: https://www.spaceui.one/primitives/dialog

***

title: Dialog
description: Opens a focused popup window over the main page, allowing users to complete a dedicated task or view details without losing page context.

links:
doc: [https://base-ui.com/react/components/dialog#api-reference](https://base-ui.com/react/components/dialog#api-reference)
preview: demo-p-dialog-01
-------------------------

## Installation

<ComponentInstallation name="primitives-dialog" />

## Usage

```tsx
import {
  Dialog,
  DialogClose,
  DialogDescription,
  DialogPanel,
  DialogFooter,
  DialogHeader,
  DialogPopup,
  DialogTitle,
  DialogTrigger,
} from '@/components/ui/dialog'
```

```tsx
<Dialog>
  <DialogTrigger>Open Dialog</DialogTrigger>
  <DialogPopup>
    <DialogHeader>
      <DialogTitle>Dialog Title</DialogTitle>
      <DialogDescription>Dialog Description</DialogDescription>
    </DialogHeader>
    <DialogPanel>Content</DialogPanel>
    <DialogFooter>
      <DialogClose>Close</DialogClose>
    </DialogFooter>
  </DialogPopup>
</Dialog>
```

## Anatomy

```tsx
<Dialog>
  <DialogTrigger />
  <DialogBackdrop />
  <DialogPopup>
    <DialogHeader>
      <DialogTitle />
      <DialogDescription />
    </DialogHeader>
    <DialogPanel />
    <DialogFooter>
      <DialogClose />
    </DialogFooter>
  </DialogPopup>
</Dialog>
```

## Features

### Bare Footer

Dialog with a bare footer (`variant="bare"`), removing the default border and background styling.

<ComponentPreview name="demo-p-dialog-06" />

## Accessibility

* Follows the [WAI-ARIA Dialog (Modal) Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/).
* Traps keyboard focus within the dialog and locks background body scrolling while open.

### Keyboard Interactions

| Key                    | Action                                                           |
| :--------------------- | :--------------------------------------------------------------- |
| <Kbd>Tab</Kbd>         | Moves focus to the next focusable element inside the dialog.     |
| <Kbd>Shift + Tab</Kbd> | Moves focus to the previous focusable element inside the dialog. |
| <Kbd>Escape</Kbd>      | Closes the dialog and restores focus to the trigger element.     |

## API Reference

### Dialog

Root component. Alias for `Dialog.Root` from Base UI.

### DialogTrigger

Trigger button that opens the dialog. Alias for `Dialog.Trigger` from Base UI.

### DialogCreateHandle

Creates a handle for detached dialog triggers. Use it when the trigger and popup need to be coordinated across different parts of the tree.

### DialogPopup

Popup container that displays the dialog content. Also exported as `DialogContent`.

| Prop                  | Type                  | Default | Description                                                                                              |
| --------------------- | --------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `showCloseButton`     | `boolean`             | `true`  | When true, displays a close button in the top-right corner                                               |
| `bottomStickOnMobile` | `boolean`             | `true`  | When true, sticks to the bottom of the screen on mobile devices                                          |
| `closeProps`          | `Dialog.Close.Props`  | -       | Props forwarded to the internal close button, useful for overriding `aria-label`                         |
| `portalProps`         | `Dialog.Portal.Props` | -       | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Dialog portal API |

### DialogHeader

Container for the dialog title and description. Supports the `render` prop for polymorphic composition (e.g. `render={<Link href="/" />}`).

### DialogFooter

Footer section for action buttons. Supports the `render` prop for polymorphic composition.

| Prop      | Type                  | Default     | Description                                                                                |
| --------- | --------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `variant` | `"default" \| "bare"` | `"default"` | Controls the footer styling. `default` includes border and background, `bare` removes them |

**Example:**

```tsx
// Default variant (with border and background)
<DialogFooter>
  <DialogClose>Cancel</DialogClose>
  <Button>Save</Button>
</DialogFooter>

// Bare variant (no border or background)
<DialogFooter variant="bare">
  <DialogClose>Cancel</DialogClose>
  <Button>Save</Button>
</DialogFooter>
```

### DialogTitle

Title component. Alias for `Dialog.Title` from Base UI.

### DialogDescription

Description component. Alias for `Dialog.Description` from Base UI.

### DialogPanel

Scrollable content container. Automatically wraps content in a `ScrollArea` component. Supports the `render` prop for polymorphic composition.

| Prop         | Type      | Default | Description                                    |
| ------------ | --------- | ------- | ---------------------------------------------- |
| `scrollFade` | `boolean` | `true`  | When true, shows a fade effect at scroll edges |

**Example:**

```tsx
<DialogPanel>
  {/* Long content that will scroll if it exceeds the dialog height */}
  <div>...</div>
</DialogPanel>
```

### DialogClose

Close button component. Alias for `Dialog.Close` from Base UI.

### DialogPortal

Portal component for rendering outside the DOM hierarchy. Alias for `Dialog.Portal` from Base UI.

### DialogBackdrop

Backdrop/overlay component. Also exported as `DialogOverlay`. Alias for `Dialog.Backdrop` from Base UI.

### DialogViewport

Viewport component for positioning. Alias for `Dialog.Viewport` from Base UI.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-dialog-02" description="Dialog opened from menu" />

  <ShowcaseCard name="demo-p-dialog-03" description="Nested dialogs" />

  <ShowcaseCard name="demo-p-dialog-04" description="Dialog with close confirmation" />

  <ShowcaseCard name="demo-p-dialog-05" description="Dialog with long content" />
</ShowcaseGrid>


# Drawer
URL: https://www.spaceui.one/primitives/drawer

***

title: Drawer
description: Slides an interactive panel in from the edge of the screen, giving users quick access to secondary tools, forms, or menus with swipe gestures.

links:
doc: [https://base-ui.com/react/components/drawer](https://base-ui.com/react/components/drawer)
preview: demo-p-drawer-01
-------------------------

## Installation

<ComponentInstallation name="primitives-drawer" />

## Usage

```tsx
import {
  Drawer,
  DrawerCreateHandle,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerMenu,
  DrawerMenuCheckboxItem,
  DrawerMenuGroup,
  DrawerMenuGroupLabel,
  DrawerMenuItem,
  DrawerMenuRadioGroup,
  DrawerMenuRadioItem,
  DrawerMenuSeparator,
  DrawerPanel,
  DrawerPopup,
  DrawerMenuTrigger,
  DrawerTitle,
  DrawerTrigger,
} from '@/components/ui/drawer'
```

```tsx
<Drawer>
  <DrawerTrigger>Open</DrawerTrigger>
  <DrawerPopup>
    <DrawerHeader>
      <DrawerTitle>Drawer Title</DrawerTitle>
      <DrawerDescription>Drawer Description</DrawerDescription>
    </DrawerHeader>
    <DrawerPanel>Content</DrawerPanel>
    <DrawerFooter>
      <DrawerClose>Close</DrawerClose>
    </DrawerFooter>
  </DrawerPopup>
</Drawer>
```

## Anatomy

```tsx
<Drawer>
  <DrawerTrigger />
  <DrawerBackdrop />
  <DrawerPopup>
    <DrawerHeader>
      <DrawerTitle />
      <DrawerDescription />
    </DrawerHeader>
    <DrawerPanel />
    <DrawerFooter>
      <DrawerClose />
    </DrawerFooter>
  </DrawerPopup>
</Drawer>
```

## Features

### Positions

Drawer positioned along different screen edges (`position="bottom" | "top" | "left" | "right"`).

<ComponentPreview name="demo-p-drawer-02" />

## Accessibility

* Traps focus within the drawer panel while open and locks background scroll.
* Supports physical swipe-down gestures and keyboard escape dismissal.

### Keyboard Interactions

| Key               | Action                                                       |
| :---------------- | :----------------------------------------------------------- |
| <Kbd>Tab</Kbd>    | Cycles focus through interactive elements inside the drawer. |
| <Kbd>Escape</Kbd> | Dismisses the drawer and returns focus to the trigger.       |

### Inset Variant

Drawer configured with inset margins across all four edge positions.

<ComponentPreview name="demo-p-drawer-04" />

### Straight Variant

Standard full-bleed straight drawer without rounded inset margins.

<ComponentPreview name="demo-p-drawer-05" />

## API Reference

### Drawer

Root component. Wraps `Drawer.Root` from Base UI with automatic `swipeDirection` mapping based on `position`.

| Prop             | Type                                     | Default    | Description                                                                                                                 |
| ---------------- | ---------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `position`       | `"right" \| "left" \| "top" \| "bottom"` | `"bottom"` | Controls which edge the drawer opens from. Sets the swipe direction automatically and flows to child components via context |
| `swipeDirection` | `"up" \| "down" \| "left" \| "right"`    | derived    | Overrides the swipe direction derived from `position`. Use when you need different swipe behavior                           |

All other props from `Drawer.Root` are supported, including `open`, `onOpenChange`, `modal`, `snapPoints`, `snapPoint`, `onSnapPointChange`, and `snapToSequentialPoints`. Note: Snap points only work for bottom drawers.

### DrawerCreateHandle

Creates a handle for detached drawer triggers. Use it when triggers and drawer content need to be coordinated across different parts of the tree.

### DrawerTrigger

Trigger button that opens the drawer. Alias for `Drawer.Trigger` from Base UI.

### DrawerPopup

Popup container that displays the drawer content.

| Prop              | Type                                 | Default     | Description                                                                                                              |
| ----------------- | ------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| `variant`         | `"default" \| "straight" \| "inset"` | `"default"` | Controls the drawer style. `straight` removes rounded corners, `inset` adds spacing around the drawer on desktop screens |
| `showCloseButton` | `boolean`                            | `false`     | When true, displays a close button in the top-right corner                                                               |
| `showBar`         | `boolean`                            | `false`     | When true, displays a drag bar indicator                                                                                 |
| `portalProps`     | `Drawer.Portal.Props`                | -           | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Drawer portal API                 |

**Example:**

```tsx
// Bottom drawer (default)
<Drawer>
  <DrawerPopup>...</DrawerPopup>
</Drawer>

// Right side drawer
<Drawer position="right">
  <DrawerPopup>...</DrawerPopup>
</Drawer>

// Left side drawer
<Drawer position="left">
  <DrawerPopup>...</DrawerPopup>
</Drawer>

// Drawer with inset variant
<Drawer position="right">
  <DrawerPopup variant="inset">...</DrawerPopup>
</Drawer>
```

### DrawerHeader

Container for the drawer title and description. Supports the `render` prop for polymorphic composition (e.g. `render={<header />}`).

| Prop             | Type      | Default | Description                                                                                             |
| ---------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `allowSelection` | `boolean` | `false` | When true, wraps the header in `DrawerContent` to reduce swipe interference during mouse text selection |

### DrawerFooter

Footer section for action buttons. Supports the `render` prop for polymorphic composition.

| Prop             | Type                  | Default     | Description                                                                                             |
| ---------------- | --------------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
| `variant`        | `"default" \| "bare"` | `"default"` | Controls the footer styling. `default` includes border and background, `bare` removes them              |
| `allowSelection` | `boolean`             | `true`      | When true, wraps the footer in `DrawerContent` to reduce swipe interference during mouse text selection |

### DrawerTitle

Title component. Alias for `Drawer.Title` from Base UI.

### DrawerDescription

Description component. Alias for `Drawer.Description` from Base UI.

### DrawerPanel

Content container. When `scrollable` is true (default), wraps content in a `ScrollArea` component. Supports the `render` prop for polymorphic composition.

| Prop             | Type      | Default | Description                                                                                            |
| ---------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `scrollable`     | `boolean` | `true`  | When true, wraps content in a `ScrollArea`. Set to false for non-scrollable content                    |
| `scrollFade`     | `boolean` | `true`  | When true, shows a fade effect at scroll edges (only applies when `scrollable` is true)                |
| `allowSelection` | `boolean` | `true`  | When true, wraps the panel in `DrawerContent` to reduce swipe interference during mouse text selection |

### DrawerMenu

Container for drawer menu items. Use with `DrawerMenuItem`, `DrawerMenuSeparator`, `DrawerMenuGroup`, `DrawerMenuGroupLabel`, `DrawerMenuCheckboxItem`, `DrawerMenuRadioGroup`, `DrawerMenuRadioItem`, and `DrawerMenuTrigger` to build menus that mirror the Menu component API. Supports the `render` prop for polymorphic composition.

### DrawerMenuItem

Styled menu item that matches `MenuItem` appearance. Does not close the drawer — wrap with `DrawerClose` when close-on-click is needed. Supports the `render` prop for polymorphic composition.

| Prop       | Type                         | Default     | Description                                     |
| ---------- | ---------------------------- | ----------- | ----------------------------------------------- |
| `variant`  | `"default" \| "destructive"` | `"default"` | When `destructive`, uses destructive text color |
| `disabled` | `boolean`                    | —           | When true, disables the item                    |

**Example:** Use with `DrawerClose` for close-on-click: `<DrawerClose render={<DrawerMenuItem />}>Edit</DrawerClose>`

### DrawerMenuSeparator

Horizontal separator between menu items or groups. Supports the `render` prop for polymorphic composition.

### DrawerMenuGroup

Container for grouping related menu items. Use with `DrawerMenuGroupLabel` for labeled sections. Supports the `render` prop for polymorphic composition.

### DrawerMenuGroupLabel

Label for a `DrawerMenuGroup` section. Renders muted, smaller text above a group of items. In nested drawers, use as a section title at the top of the menu (no back button needed — swipe to go back). Supports the `render` prop for polymorphic composition.

### DrawerMenuTrigger

Trigger that opens a nested drawer. Styled like a menu item with a trailing chevron. Use for menu items that open nested drawers (e.g. "Add to Playlist" → nested drawer with playlist options). Wraps `DrawerTrigger` internally.

**Example:** `<DrawerMenuTrigger>Add to Playlist</DrawerMenuTrigger>` opens a nested drawer when tapped.

### DrawerMenuCheckboxItem

Checkbox menu item for independent toggles. Supports `variant="switch"` for toggle-style switches, `checked`, `defaultChecked`, and `onCheckedChange`. For selection groups, use `DrawerMenuRadioGroup` with `DrawerMenuRadioItem`.

### DrawerMenuRadioGroup

Container for radio menu items. Use with `DrawerMenuRadioItem` for mutually exclusive options (e.g. "Sort by" with Artist, Album, Title).

### DrawerMenuRadioItem

Radio menu item. Must be used inside `DrawerMenuRadioGroup` with a `value` prop.

### DrawerClose

Close button component. Alias for `Drawer.Close` from Base UI.

### DrawerPortal

Portal component for rendering outside the DOM hierarchy. Alias for `Drawer.Portal` from Base UI.

### DrawerBackdrop

Backdrop/overlay component. Alias for `Drawer.Backdrop` from Base UI.

### DrawerViewport

Viewport component for positioning. Alias for `Drawer.Viewport` from Base UI. Typically not used directly — `DrawerPopup` renders it internally.

### DrawerBar

Drag handle indicator shown when `showBar` is true on `DrawerPopup`. Typically not used directly.

### DrawerContent

Primitive content wrapper used for polymorphic composition with the `render` prop. Alias for `Drawer.Content` from Base UI.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-drawer-03" description="Drawer with close button" />

  <ShowcaseCard name="demo-p-drawer-06" description="Scrollable content with terms and conditions" />

  <ShowcaseCard name="demo-p-drawer-07" description="Nested bottom drawers with centered content" />

  <ShowcaseCard name="demo-p-drawer-08" description="Nested right drawers with inset variant" />

  <ShowcaseCard name="demo-p-drawer-09" description="Bottom drawer with snap points" />

  <ShowcaseCard name="demo-p-drawer-10" description="Edit profile form with default and bare footer variants" />

  <ShowcaseCard name="demo-p-drawer-11" description="Mobile menu drawer from the left" />

  <ShowcaseCard name="demo-p-drawer-12" description="Responsive edit profile: dialog on desktop, drawer on mobile" />

  <ShowcaseCard name="demo-p-drawer-13" description="Responsive actions menu: menu on desktop, drawer on mobile" />

  <ShowcaseCard name="demo-p-drawer-14" description="Left drawer with swipe area" />
</ShowcaseGrid>


# Empty
URL: https://www.spaceui.one/primitives/empty

***

title: Empty
description: Displays helpful placeholder messages, illustrations, and action buttons when there is no data to show, guiding users on what to do next.
preview: demo-p-empty-01
------------------------

## Installation

<ComponentInstallation name="primitives-empty" />

## Usage

```tsx
import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from '@/components/ui/empty'
```

```tsx
<Empty>
  <EmptyHeader>
    <EmptyMedia variant="icon">
      <Icon />
    </EmptyMedia>
    <EmptyTitle>No data</EmptyTitle>
    <EmptyDescription>No data found</EmptyDescription>
  </EmptyHeader>
  <EmptyContent>
    <Button>Add data</Button>
  </EmptyContent>
</Empty>
```

## API Reference

The API design of this component is modeled after [shadcn/ui's empty component](https://ui.shadcn.com/docs/components/empty) to ensure familiarity and consistency for developers already using shadcn. This standardization makes it easier to adopt **space ui** while maintaining API parity with the patterns developers already know and love.

### Empty

The main component of the empty state. Wraps the `EmptyHeader` and `EmptyContent` components.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<Empty>
  <EmptyHeader />
  <EmptyContent />
</Empty>
```

### EmptyHeader

The `EmptyHeader` component wraps the empty media, title, and description.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<EmptyHeader>
  <EmptyMedia />
  <EmptyTitle />
  <EmptyDescription />
</EmptyHeader>
```

### EmptyMedia

Use the `EmptyMedia` component to display the media of the empty state such as an icon or an image. You can also use it to display other components such as an avatar.

| Prop        | Type                  | Default   |
| ----------- | --------------------- | --------- |
| `variant`   | `"default" \| "icon"` | `default` |
| `className` | `string`              |           |

```tsx
<EmptyMedia variant="icon">
  <Icon />
</EmptyMedia>

<EmptyMedia>
  <Avatar>
    <AvatarImage/>
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
</EmptyMedia>
```

### EmptyTitle

Use the `EmptyTitle` component to display the title of the empty state.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<EmptyTitle>No data</EmptyTitle>
```

### EmptyDescription

Use the `EmptyDescription` component to display the description of the empty state.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<EmptyDescription>You do not have any notifications.</EmptyDescription>
```

### EmptyContent

Use the `EmptyContent` component to display the content of the empty state such as a button, input or a link.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<EmptyContent>
  <Button>Add Project</Button>
</EmptyContent>
```


# Field
URL: https://www.spaceui.one/primitives/field

***

title: Field
description: Wraps input fields with clear text labels, helpful hints, and error messages to make filling out forms straightforward and accessible.

links:
doc: [https://base-ui.com/react/components/field#api-reference](https://base-ui.com/react/components/field#api-reference)
preview: demo-p-field-01
------------------------

## Installation

<ComponentInstallation name="primitives-field" />

## Usage

```tsx
import { Field, FieldDescription, FieldError, FieldLabel, FieldValidity } from '@/components/ui/field'
import { Input } from '@/components/ui/input'
```

```tsx
<Field>
  <FieldLabel>Name</FieldLabel>
  <Input type="text" placeholder="Enter your name" />
  <FieldDescription>Visible on your profile</FieldDescription>
  <FieldError>Please enter a valid name</FieldError>
  <FieldValidity>
    {(validity) => (
      {validity.error && <p>{validity.error}</p>}
    )}
  </FieldValidity>
</Field>
```

## Anatomy

```tsx
<Field>
  <FieldLabel />
  <FieldControl />
  <FieldDescription />
  <FieldError />
</Field>
```

## Features

### Disabled State

Field component rendered in a disabled state via the `disabled` prop.

<ComponentPreview name="demo-p-field-03" />

## API Reference

### Field

Root component. Styled wrapper for `Field.Root` from Base UI with flex column layout.

### FieldLabel

Label for the field. Styled wrapper for `Field.Label` from Base UI.

### FieldItem

Container for field items. Styled wrapper for `Field.Item` from Base UI.

### FieldDescription

Description text for the field. Styled wrapper for `Field.Description` from Base UI with muted foreground color.

### FieldError

Error message for the field. Styled wrapper for `Field.Error` from Base UI with destructive foreground color.

### FieldControl

Alias for `Field.Control` from Base UI. Use this to register a custom or third-party control with the field context so it participates in labelling, validation, and error state.

Note that `Textarea` does not require `FieldControl` — it wraps `Field.Control` internally and integrates with `Field` the same way `Input` and other built-in controls do.

### FieldValidity

Alias for `Field.Validity` from Base UI.

### FieldGroup

Container for grouping multiple field components together with vertical spacing. Renders as a styled `div`.

### FieldSeparator

Visual separator between fields or sections within a field group.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-field-02" description="Field with required indicator" />

  <ShowcaseCard name="demo-p-field-04" description="Field showing validation error" />

  <ShowcaseCard name="demo-p-field-05" description="Show field validity state" />

  <ShowcaseCard name="demo-p-field-06" description="Input group with field" />

  <ShowcaseCard name="demo-p-field-07" description="Field with autocomplete" />

  <ShowcaseCard name="demo-p-field-08" description="Field with combobox" />

  <ShowcaseCard name="demo-p-field-09" description="Field with multiple selection combobox" />

  <ShowcaseCard name="demo-p-field-10" description="Field with textarea" />

  <ShowcaseCard name="demo-p-field-11" description="Field with select" />

  <ShowcaseCard name="demo-p-field-12" description="Field with checkbox" />

  <ShowcaseCard name="demo-p-field-13" description="Field with checkbox group" />

  <ShowcaseCard name="demo-p-field-14" description="Field with radio group" />

  <ShowcaseCard name="demo-p-field-15" description="Field with toggle switch" />

  <ShowcaseCard name="demo-p-field-16" description="Field with slider" />

  <ShowcaseCard name="demo-p-field-17" description="Field with number field" />

  <ShowcaseCard name="demo-p-field-18" description="Complete form built with field" />
</ShowcaseGrid>


# Fieldset
URL: https://www.spaceui.one/primitives/fieldset

***

title: Fieldset
description: Groups related form controls together under a descriptive header, making long or complex forms easier to read and understand.

links:
doc: [https://base-ui.com/react/components/fieldset#api-reference](https://base-ui.com/react/components/fieldset#api-reference)
preview: demo-p-fieldset-01
---------------------------

## Installation

<ComponentInstallation name="primitives-fieldset" />

## Usage

```tsx
import { Fieldset, FieldsetLegend } from '@/components/ui/fieldset'
```

```tsx
<Fieldset>
  <FieldsetLegend>Fieldset legend</FieldsetLegend>
</Fieldset>
```

## Anatomy

```tsx
<Fieldset>
  <FieldsetLegend />
  <FieldsetContent />
</Fieldset>
```

## API Reference

### Fieldset

Root component. Styled wrapper for `Fieldset.Root` from Base UI with flex column layout.

### FieldsetLegend

Legend for the fieldset. Styled wrapper for `Fieldset.Legend` from Base UI with semibold font weight.


# Form
URL: https://www.spaceui.one/primitives/form

***

title: Form
description: Manages form inputs, checks for validation errors, and handles form submission to ensure a smooth data entry experience.
links:
doc: [https://base-ui.com/react/components/form#api-reference](https://base-ui.com/react/components/form#api-reference)
preview: demo-p-form-01
-----------------------

## Installation

<ComponentInstallation name="primitives-form" />

## Usage

```tsx
import { Field, FieldError, FieldLabel } from '@/components/ui/field'
import { Form } from '@/components/ui/form'
import { Input } from '@/components/ui/input'
```

```tsx
<Form
  className="flex w-full flex-col gap-4"
  onSubmit={(e) => {
    /* handle submit */
  }}
>
  <Field>
    <FieldLabel>Email</FieldLabel>
    <Input name="email" type="email" required />
    <FieldError>Please enter a valid email.</FieldError>
  </Field>
</Form>
```

## Integrations

### Using with Zod

<ComponentPreview name="demo-p-form-02" />

## Changelog

* [Apr 17, 2026](/docs/changelog#form) — **`Form`** no longer applies default layout classes; pass **`className`** for stacked fields (`flex w-full flex-col gap-4`); for overlays, wrap **panel + footer** in **`Form className="contents"`** with **header** outside.

## API Reference

### Form Props

Thin wrapper around Base UI `Form` with no default layout. Pass **`className`** for spacing and structure (for example `flex w-full flex-col gap-4` for a vertical field stack).

**Dialog, sheet, drawer:** Place **`DialogHeader`** (or sheet/drawer header) **outside** the form. Wrap **`DialogPanel`** and **`DialogFooter`** only in **`<Form className="contents">`** (or **`<form className="contents">`**). The **`contents`** display value keeps panel and footer participating correctly in the popup flex layout without nesting the header inside the `<form>`.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-form-02" description="Form with zod validation" />
</ShowcaseGrid>


# Frame
URL: https://www.spaceui.one/primitives/frame

***

title: Frame
description: Provides a mock browser or device container to showcase components and design previews in context.
preview: demo-p-frame-01
------------------------

## Installation

<ComponentInstallation name="primitives-frame" />

## Usage

```tsx
import { Frame, FrameDescription, FrameFooter, FrameHeader, FramePanel, FrameTitle } from '@/components/ui/frame'
```

```tsx
<Frame>
  <FrameHeader>
    <FrameTitle>Title</FrameTitle>
    <FrameDescription>Description</FrameDescription>
  </FrameHeader>
  <FramePanel>Content</FramePanel>
  <FrameFooter>Footer</FrameFooter>
</Frame>
```

## Features

### Separated Panels

Frame container configured with distinct separated panels and divider styling.

<ComponentPreview name="demo-p-frame-02" />

## API Reference

### Frame

The main container component for grouping related information.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

### FramePanel

A panel container for frame content.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<FramePanel>Content</FramePanel>
```

### FrameHeader

Header section for the frame.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<FrameHeader>
  <FrameTitle>Title</FrameTitle>
  <FrameDescription>Description</FrameDescription>
</FrameHeader>
```

### FrameTitle

Title text for the frame header.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<FrameTitle>Title</FrameTitle>
```

### FrameDescription

Description text for the frame header.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<FrameDescription>Description</FrameDescription>
```

### FrameFooter

Footer section for the frame.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<FrameFooter>Footer</FrameFooter>
```

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-frame-03" description="Frame with multiple separated panels" />

  <ShowcaseCard name="demo-p-frame-04" description="Frame with multiple stacked panels" />
</ShowcaseGrid>

### Separated Panels

By default, multiple panels are separated with spacing between them.

<ComponentPreview name="demo-p-frame-03" />


# Group
URL: https://www.spaceui.one/primitives/group

***

title: Group
description: Combines adjacent interactive elements into a seamless visual segment for a cleaner, unified toolbar layout.
preview: demo-p-group-01
------------------------

## Installation

<ComponentInstallation name="primitives-group" />

## Usage

```tsx
import { Button } from '@/components/ui/button'
import { Group, GroupSeparator } from '@/components/ui/group'
```

```tsx
<Group>
  <Button>Button</Button>
  <GroupSeparator />
  <Button>Button</Button>
</Group>
```

## Features

### Disabled State

Group container with disabled child items.

<ComponentPreview name="demo-p-group-05" />

## Accessibility

* The `Group` component has the `role` attribute set to `group`.
* Use `Tab` to navigate between the controls in the group.
* Use `aria-label` or `aria-labelledby` to label the group.

```tsx showLineNumbers
<Group aria-label="Media controls">
  <Button variant="outline">Play</Button>
  <GroupSeparator />
  <Button variant="outline">Pause</Button>
</Group>
```

### Group vs ToggleGroup

* Use the `Group` component when you want to group controls that perform an action.
* Use the `ToggleGroup` component when you want to group controls that toggle a state.

## API Reference

### Group

The `Group` component is a container that visually groups a series of related controls together with consistent styling.

| Prop          | Type                         | Default        |
| ------------- | ---------------------------- | -------------- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |

```tsx
<Group>
  <Button>Button 1</Button>
  <GroupSeparator />
  <Button>Button 2</Button>
</Group>
```

Nest multiple groups to create complex layouts with spacing. See the [nested groups](#nested-groups) example for more details.

```tsx
<Group>
  <Group>
    <Button>1</Button>
    <GroupSeparator />
    <Button>2</Button>
  </Group>
  <Group>
    <Button>Previous</Button>
    <GroupSeparator />
    <Button>Next</Button>
  </Group>
</Group>
```

### GroupSeparator

The `GroupSeparator` component visually divides controls within a group.

| Prop          | Type                         | Default      |
| ------------- | ---------------------------- | ------------ |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` |

```tsx
<Group>
  <Button>Button 1</Button>
  <GroupSeparator />
  <Button>Button 2</Button>
</Group>
```

**Note:** Unlike shadcn's ButtonGroup, `GroupSeparator` is required between all controls, including outline buttons. This ensures consistent visual hierarchy and focus states.

### GroupText

Use this component to display text within a group, such as labels or prefixes.

| Prop     | Type                      | Default |
| -------- | ------------------------- | ------- |
| `render` | `React.ReactNode \| null` | `null`  |

```tsx
<Group>
  <GroupText>https://</GroupText>
  <GroupSeparator />
  <Input placeholder="example.com" />
</Group>
```

Use the `render` prop to render a custom component as the text, for example a label.

```tsx
<Group>
  <GroupText render={<Label htmlFor="domain" aria-label="Domain" />}>https://</GroupText>
  <GroupSeparator />
  <Input id="domain" placeholder="example.com" />
</Group>
```

### Aliases

`Group`, `GroupText`, and `GroupSeparator` are also exported as `ButtonGroup`, `ButtonGroupText`, and `ButtonGroupSeparator` for compatibility.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-group-02" description="Group with input" />

  <ShowcaseCard name="demo-p-group-03" description="Small group" />

  <ShowcaseCard name="demo-p-group-04" description="Large group" />

  <ShowcaseCard name="demo-p-group-06" description="Group with default button" />

  <ShowcaseCard name="demo-p-group-07" description="Group with start text" />

  <ShowcaseCard name="demo-p-group-08" description="Group with end text" />

  <ShowcaseCard name="demo-p-group-09" description="Vertical group" />

  <ShowcaseCard name="demo-p-group-10" description="Nested groups" />

  <ShowcaseCard name="demo-p-group-11" description="Group with popup" />

  <ShowcaseCard name="demo-p-group-12" description="Group with input group" />

  <ShowcaseCard name="demo-p-group-13" description="Group with menu" />

  <ShowcaseCard name="demo-p-group-14" description="Group with select" />

  <ShowcaseCard name="demo-p-group-15" description="Group with search" contained={false} />

  <ShowcaseCard name="demo-p-group-16" description="Group with add button and input" />

  <ShowcaseCard name="demo-p-group-17" description="Group with input and currency text" />

  <ShowcaseCard name="demo-p-group-18" description="Group with select and input" />

  <ShowcaseCard name="demo-p-group-19" description="Group with input and select" />

  <ShowcaseCard name="demo-p-group-20" description="Group with input and text button" />

  <ShowcaseCard name="demo-p-group-21" description="Group with two number inputs for range" />

  <ShowcaseCard name="demo-p-group-22" description="Group with filter label, combobox multi-select, and remove button" />

  <ShowcaseCard name="demo-p-group-23" description="Group with model selection and tooltips" />

  <ShowcaseCard name="demo-p-group-24" description="Group with status select and search input" />

  <ShowcaseCard name="demo-p-group-25" description="Group for 1-10 rating scale" />

  <ShowcaseCard name="demo-p-group-26" description="Group toolbar example 1" />

  <ShowcaseCard name="demo-p-group-27" description="Group toolbar example 2" />

  <ShowcaseCard name="demo-p-group-28" description="Group with team collaboration actions and avatars" />

  <ShowcaseCard name="demo-p-group-29" description="Group with document actions" />
</ShowcaseGrid>


# Primitives
URL: https://www.spaceui.one/primitives

***

title: Primitives
description: Accessible, unstyled-ready primitives for building Space UI products.
----------------------------------------------------------------------------------


# Input Group
URL: https://www.spaceui.one/primitives/input-group

***

title: Input Group
description: Attaches icons, prefix text, buttons, or dropdowns directly to an input field, creating compact, all-in-one form controls.
preview: demo-p-input-group-01
------------------------------

## Installation

<ComponentInstallation name="primitives-input-group" />

## Usage

```tsx
import { Input } from '@/components/ui/input'
import { InputGroup, InputGroupAddon, InputGroupInput, InputGroupText } from '@/components/ui/input-group'
```

```tsx
<InputGroup>
  <InputGroupInput type="email" placeholder="Email" />
  <InputGroupAddon>
    <MailIcon />
  </InputGroupAddon>
</InputGroup>
```

## Features

### Disabled State

Input group rendered in a disabled state with disabled addons.

<ComponentPreview name="demo-p-input-group-15" />

## API Reference

### InputGroup

The main component that wraps inputs and addons.

| Prop        | Type                          | Description                                      |
| ----------- | ----------------------------- | ------------------------------------------------ |
| `className` | `string`                      | Additional CSS classes to apply to the component |
| `...props`  | `React.ComponentProps<'div'>` | All standard div attributes are supported        |

### InputGroupAddon

A container for addons like icons, text, buttons, and other elements. Can be positioned at the start or end (inline), or top or bottom (block) of the input.

| Prop        | Type                                                             | Default          | Description                                                                                                                                    |
| ----------- | ---------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `align`     | `'inline-start' \| 'inline-end' \| 'block-start' \| 'block-end'` | `'inline-start'` | The position of the addon relative to the input. Use `inline-start` or `inline-end` for inputs, and `block-start` or `block-end` for textareas |
| `className` | `string`                                                         |                  | Additional CSS classes to apply to the component                                                                                               |
| `...props`  | `React.ComponentProps<'div'>`                                    |                  | All standard div attributes are supported                                                                                                      |

<Callout>
  For proper focus navigation, the `InputGroupAddon` component should be placed after the input in the DOM order.
</Callout>

### InputGroupText

A text container component for displaying text content within an `InputGroupAddon`. Automatically styles text with muted foreground color and handles icon sizing.

| Prop        | Type                           | Description                                      |
| ----------- | ------------------------------ | ------------------------------------------------ |
| `className` | `string`                       | Additional CSS classes to apply to the component |
| `...props`  | `React.ComponentProps<'span'>` | All standard span attributes are supported       |

### InputGroupInput

A specialized input component for use within InputGroup. It's essentially an unstyled Input component that inherits styling from the parent InputGroup.

| Prop        | Type         | Description                                                                                         |
| ----------- | ------------ | --------------------------------------------------------------------------------------------------- |
| `className` | `string`     | Additional CSS classes to apply to the component                                                    |
| `...props`  | `InputProps` | All props from the Input component are supported, including `type`, `placeholder`, `disabled`, etc. |

### InputGroupTextarea

A specialized textarea component for use within InputGroup. It's essentially an unstyled Textarea component that inherits styling from the parent InputGroup.

| Prop        | Type            | Description                                                                                            |
| ----------- | --------------- | ------------------------------------------------------------------------------------------------------ |
| `className` | `string`        | Additional CSS classes to apply to the component                                                       |
| `...props`  | `TextareaProps` | All props from the Textarea component are supported, including `placeholder`, `disabled`, `rows`, etc. |

### InputGroupButton

A button styled specifically for embedding within an `InputGroupAddon` or `InputGroup`.

| Prop        | Type          | Description                                                  |
| ----------- | ------------- | ------------------------------------------------------------ |
| `className` | `string`      | Additional CSS classes to apply to the component             |
| `...props`  | `ButtonProps` | All standard props from the `Button` primitive are supported |

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-input-group-02" description="Input group with end icon" />

  <ShowcaseCard name="demo-p-input-group-03" description="Input group with start text" />

  <ShowcaseCard name="demo-p-input-group-04" description="Input group with end text" />

  <ShowcaseCard name="demo-p-input-group-05" description="Input group with start and end text" />

  <ShowcaseCard name="demo-p-input-group-06" description="Input group with number field" />

  <ShowcaseCard name="demo-p-input-group-07" description="Input group with end tooltip" />

  <ShowcaseCard name="demo-p-input-group-08" description="Input group with icon button" />

  <ShowcaseCard name="demo-p-input-group-09" description="Input group with button" />

  <ShowcaseCard name="demo-p-input-group-10" description="Input group with badge" />

  <ShowcaseCard name="demo-p-input-group-11" description="Input group with keyboard shortcut" />

  <ShowcaseCard name="demo-p-input-group-12" description="Input group with inner label" />

  <ShowcaseCard name="demo-p-input-group-13" description="Small input group" />

  <ShowcaseCard name="demo-p-input-group-14" description="Large input group" />

  <ShowcaseCard name="demo-p-input-group-16" description="Input group with loading spinner" />

  <ShowcaseCard name="demo-p-input-group-17" description="Input group with textarea" />

  <ShowcaseCard name="demo-p-input-group-18" description="Input group with badge and menu" />

  <ShowcaseCard name="demo-p-input-group-19" description="Mini editor built with input group and toggle" />

  <ShowcaseCard name="demo-p-input-group-20" description="Input group with search icon" />

  <ShowcaseCard name="demo-p-input-group-21" description="Input group with start tooltip" />

  <ShowcaseCard name="demo-p-input-group-22" description="Input group with clear button" />

  <ShowcaseCard name="demo-p-input-group-23" description="Search input group with loader and voice button" />

  <ShowcaseCard name="demo-p-input-group-24" description="Input group with character counter" />

  <ShowcaseCard name="demo-p-input-group-25" description="Password input with strength indicator" />

  <ShowcaseCard name="demo-p-input-group-26" description="Code snippet input with language selector" />

  <ShowcaseCard name="demo-p-input-group-27" description="Message composer with attachment buttons" />

  <ShowcaseCard name="demo-p-input-group-28" description="Chat input with voice and send buttons" />
</ShowcaseGrid>


# Input
URL: https://www.spaceui.one/primitives/input

***

title: Input
description: Allows users to type single-line text, emails, passwords, or numbers, with clear focus outlines and validation feedback.

links:
doc: [https://base-ui.com/react/components/input#api-reference](https://base-ui.com/react/components/input#api-reference)
preview: demo-p-input-01
------------------------

## Installation

<ComponentInstallation name="primitives-input" />

## Usage

```tsx
import { Input } from '@/components/ui/input'
```

```tsx
<Input />
```

## Features

### Sizes

Input fields in `sm`, `default`, and `lg` sizes.

<ComponentPreview name="demo-p-input-02" />

### Disabled

Input rendered in a disabled state via `disabled`.

<ComponentPreview name="demo-p-input-04" />

### Read Only

Input configured in read-only mode via `readOnly`.

<ComponentPreview name="demo-p-input-16" />

## API Reference

### Input

Styled wrapper for `Input` from Base UI with custom size options.

| Prop          | Type                                  | Default     | Description                                                                          |
| ------------- | ------------------------------------- | ----------- | ------------------------------------------------------------------------------------ |
| `size`        | `"sm" \| "default" \| "lg" \| number` | `"default"` | Controls the input height. Number values are passed to the native `size` attribute   |
| `unstyled`    | `boolean`                             | `false`     | When true, removes the wrapper styling (border, shadow, etc.)                        |
| `nativeInput` | `boolean`                             | `false`     | When true, renders directly as a native input element without field control wrappers |

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-input-05" description="File input" />

  <ShowcaseCard name="demo-p-input-06" description="Input with label" />

  <ShowcaseCard name="demo-p-input-07" description="Input with button using Group" />

  <ShowcaseCard name="demo-p-input-08" description="Input with start text and end tooltip" />

  <ShowcaseCard name="demo-p-input-09" description="Password input with toggle visibility" />

  <ShowcaseCard name="demo-p-input-10" description="Input group with keyboard shortcut" />

  <ShowcaseCard name="demo-p-input-11" description="Input group with start loading spinner" />

  <ShowcaseCard name="demo-p-input-12" description="Input with label and required indicator" />

  <ShowcaseCard name="demo-p-input-13" description="Input with optional label" />

  <ShowcaseCard name="demo-p-input-14" description="Input with custom border and background" />

  <ShowcaseCard name="demo-p-input-15" description="Input group with end loading spinner" />

  <ShowcaseCard name="demo-p-input-17" description="Input with characters remaining counter" />

  <ShowcaseCard name="demo-p-input-18" description="Pill-shaped input" />
</ShowcaseGrid>


# Kbd
URL: https://www.spaceui.one/primitives/kbd

***

title: Kbd
description: Displays keyboard shortcut keys in styled badges, showing users which keys to press to perform actions faster.
preview: demo-p-kbd-01
----------------------

## Installation

<ComponentInstallation name="primitives-kbd" />

## Usage

```tsx
import { Kbd, KbdGroup } from '@/components/ui/kbd'
```

Single key:

```tsx
<Kbd>K</Kbd>
```

Multiple keys (key combination):

```tsx
<KbdGroup>
  <Kbd>⌘</Kbd>
  <Kbd>K</Kbd>
</KbdGroup>
```

## API Reference

### Kbd

Displays a single keyboard key.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

### KbdGroup

Groups multiple keyboard keys for key combinations.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

### Input Group

<ComponentPreview name="demo-p-input-group-11" className="[&_.preview>*]:w-full [&_.preview>*]:max-w-64" />


# Label
URL: https://www.spaceui.one/primitives/label

***

title: Label
description: Provides an accessible text caption for form controls that focuses the corresponding input when clicked.
preview: demo-p-input-06
------------------------

## Installation

<ComponentInstallation name="primitives-label" />

## Usage

```tsx
import { Label } from '@/components/ui/label'
```

```tsx
<Label htmlFor="email">Email</Label>
```

## API Reference

This is a custom component using Base UI's `useRender` hook, not a direct Base UI wrapper.

### Label

A label component that can be rendered as different elements.

| Prop     | Type                 | Default | Description                   |
| -------- | -------------------- | ------- | ----------------------------- |
| `render` | `React.ReactElement` | -       | Render as a different element |

## Examples

For accessible labelling and validation, prefer using the `FieldLabel` component. See some [related examples](/ui-kit/primitives/field).

### With Checkbox

<ComponentPreview name="demo-p-checkbox-01" />


# Link
URL: https://www.spaceui.one/primitives/link

***

title: Link
description: Allows users to navigate to other pages or external websites with clear hover underlines and accessible link styling.
preview: demo-p-link-01
-----------------------

## Installation

<ComponentInstallation name="primitives-link" />

## Usage

```tsx
import { Link } from '@/components/ui/link'
```

```tsx
<Link href="/about">About us</Link>
```

## Features

### Text Link Variants

<ComponentPreview name="demo-p-link-01" />

### Button-style Links

Use `asButton` to render a link styled with our `Button` primitive variants (`default`, `secondary`, `outline`, `ghost`, `destructive`, `destructive-outline`) and sizes.

<ComponentPreview name="demo-p-link-03" />

### External Links

Pass standard HTML anchor attributes such as `target="_blank"` and `rel="noopener noreferrer"`.

<ComponentPreview name="demo-p-link-05" />

### Next.js Client Routing

Pass `NextLink` to the `render` prop to take advantage of Next.js SPA navigation and prefetching.

<ComponentPreview name="demo-p-link-07" />

## Polymorphic Routing (`render`)

Because the `Link` primitive is built on **Base UI**, it renders as a native HTML `<a>` tag by default. This makes it 100% universal across all React setups (Vite, Next.js, Remix, Astro, TanStack Start).

When building a Next.js application, you can pass Next.js `NextLink` to the `render` prop to enable client-side navigation, automatic prefetching, and router cache:

```tsx
import NextLink from 'next/link'
import { Link } from '@/components/ui/link'

export function NavLink() {
  return <Link render={<NextLink href="/dashboard" />}>Dashboard</Link>
}
```

## API Reference

### Link Props

| Prop        | Type                                                                                         | Default     | Description                                              |
| :---------- | :------------------------------------------------------------------------------------------- | :---------- | :------------------------------------------------------- |
| `variant`   | `"default" \| "secondary" \| "ghost" \| "outline" \| "destructive" \| "destructive-outline"` | `"default"` | Controls the visual text styling or button styling       |
| `size`      | `"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg"`         | `"default"` | Controls button size when `asButton` is true             |
| `underline` | `boolean`                                                                                    | `false`     | When true, adds hover underline effect with offset       |
| `asButton`  | `boolean`                                                                                    | `false`     | When true, applies button variant and dimensions styling |
| `render`    | `React.ReactElement`                                                                         | -           | Polymorphic render prop (e.g. Next.js Link)              |

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-link-03" description="Button-like link variants" />

  <ShowcaseCard name="demo-p-link-05" description="External links with icon" />

  <ShowcaseCard name="demo-p-link-07" description="Link with NextLink render prop" />
</ShowcaseGrid>


# Menu
URL: https://www.spaceui.one/primitives/menu

***

title: Menu
description: Displays a floating dropdown menu of actions or options when users click a trigger button, keeping pages clean and organized.

links:
doc: [https://base-ui.com/react/components/menu#api-reference](https://base-ui.com/react/components/menu#api-reference)
preview: demo-p-menu-01
-----------------------

## Installation

<ComponentInstallation name="primitives-menu" />

## Usage

```tsx
import {
  Menu,
  MenuCheckboxItem,
  MenuGroup,
  MenuGroupLabel,
  MenuItem,
  MenuLinkItem,
  MenuPopup,
  MenuRadioGroup,
  MenuRadioItem,
  MenuSeparator,
  MenuSub,
  MenuSubPopup,
  MenuSubTrigger,
  MenuTrigger,
} from '@/components/ui/menu'
```

```tsx
<Menu>
  <MenuTrigger>Open</MenuTrigger>
  <MenuPopup align="start" sideOffset={4}>
    <MenuItem>Profile</MenuItem>
    <MenuSeparator />

    <MenuGroup>
      <MenuGroupLabel>Playback</MenuGroupLabel>
      <MenuItem>Play</MenuItem>
      <MenuItem>Pause</MenuItem>
    </MenuGroup>

    <MenuSeparator />

    <MenuCheckboxItem>Shuffle</MenuCheckboxItem>
    <MenuCheckboxItem>Repeat</MenuCheckboxItem>
    <MenuCheckboxItem variant="switch">Auto save</MenuCheckboxItem>

    <MenuSeparator />

    <MenuGroup>
      <MenuGroupLabel>Sort by</MenuGroupLabel>
      <MenuRadioGroup>
        <MenuRadioItem>Artist</MenuRadioItem>
        <MenuRadioItem>Album</MenuRadioItem>
        <MenuRadioItem>Title</MenuRadioItem>
      </MenuRadioGroup>
    </MenuGroup>

    <MenuSeparator />

    <MenuSub>
      <MenuSubTrigger>Add to playlist</MenuSubTrigger>
      <MenuSubPopup>
        <MenuItem>Jazz</MenuItem>
        <MenuItem>Rock</MenuItem>
      </MenuSubPopup>
    </MenuSub>
  </MenuPopup>
</Menu>
```

## Anatomy

```tsx
<Menu>
  <MenuTrigger />
  <MenuPopup>
    <MenuItem />
    <MenuSeparator />
    <MenuSub>
      <MenuSubTrigger />
      <MenuSubPopup />
    </MenuSub>
  </MenuPopup>
</Menu>
```

## Accessibility

* Follows the [WAI-ARIA Menu Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/).
* Manages submenu traversal and focus restoration automatically.

### Keyboard Interactions

| Key                                       | Action                                        |
| :---------------------------------------- | :-------------------------------------------- |
| <Kbd>Enter</Kbd> / <Kbd>Space</Kbd>       | Opens the menu or activates the focused item. |
| <Kbd>ArrowDown</Kbd> / <Kbd>ArrowUp</Kbd> | Moves focus across menu items.                |
| <Kbd>ArrowRight</Kbd>                     | Opens a submenu.                              |
| <Kbd>ArrowLeft</Kbd>                      | Closes the active submenu.                    |
| <Kbd>Escape</Kbd>                         | Closes the entire menu.                       |

## API Reference

### Menu

Root component. Alias for `Menu.Root` from Base UI. Also exported as `DropdownMenu`.

### MenuCreateHandle

Creates a handle for detached menu triggers. Also exported as `DropdownMenuCreateHandle`.

### MenuPortal

Portal component that renders the menu popup into a portal container. Alias for `Menu.Portal` from Base UI. Also exported as `DropdownMenuPortal`.

### MenuTrigger

Trigger button that opens the menu. Alias for `Menu.Trigger` from Base UI. Also exported as `DropdownMenuTrigger`.

### MenuPopup

Popup container that displays the menu content. Also exported as `DropdownMenuContent`.

| Prop          | Type                                          | Default    | Description                                                                                            |
| ------------- | --------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| `side`        | `"top" \| "bottom" \| "left" \| "right"`      | `"bottom"` | Side of the trigger to position the popup                                                              |
| `align`       | `"start" \| "center" \| "end"`                | `"center"` | Alignment relative to the trigger                                                                      |
| `sideOffset`  | `number`                                      | `4`        | Distance from the trigger in pixels                                                                    |
| `alignOffset` | `number`                                      | -          | Offset along the alignment axis                                                                        |
| `anchor`      | `Element \| null \| React.RefObject<Element>` | -          | Custom anchor element or ref to anchor the popup against                                               |
| `portalProps` | `Menu.Portal.Props`                           | -          | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Menu portal API |

### MenuGroup

Groups related menu items. Alias for `Menu.Group` from Base UI. Also exported as `DropdownMenuGroup`.

### MenuItem

Individual menu item. Also exported as `DropdownMenuItem`.

| Prop      | Type                         | Default     | Description                                           |
| --------- | ---------------------------- | ----------- | ----------------------------------------------------- |
| `inset`   | `boolean`                    | -           | Adds left padding to align with items that have icons |
| `variant` | `"default" \| "destructive"` | `"default"` | Controls the item styling                             |

**Using `inset`:** When mixing items with and without icons, use `inset` on icon-less items to maintain alignment:

```tsx
<MenuItem><PencilIcon /> Edit</MenuItem>
<MenuItem><TrashIcon /> Delete</MenuItem>
<MenuItem inset>Profile</MenuItem>  {/* Aligns with icon items above */}
```

### MenuLinkItem

Link menu item for navigation. **`LinkItem`** renders a native **`<a>`** when you pass **`href`**. Styled like **`MenuItem`**.

| Prop           | Type                         | Default     | Description                                           |
| -------------- | ---------------------------- | ----------- | ----------------------------------------------------- |
| `inset`        | `boolean`                    | -           | Adds left padding to align with items that have icons |
| `variant`      | `"default" \| "destructive"` | `"default"` | Controls the item styling                             |
| `closeOnClick` | `boolean`                    | `true`      | Whether the menu closes when the link is clicked      |

If you were using **`MenuItem render={<Link href="..." />}`**, migrate to **`MenuLinkItem`** but **keep `render`** — do not replace it with **`href`** alone when using a router **`Link`**.

```tsx
<MenuLinkItem render={<Link href="/docs" />}>Docs</MenuLinkItem>
```

Use **`href`** only for plain anchor links:

```tsx
<MenuLinkItem href="/docs">Docs</MenuLinkItem>
```

### MenuCheckboxItem

Checkbox menu item. Also exported as `DropdownMenuCheckboxItem`.

| Prop      | Type                    | Default     | Description                                              |
| --------- | ----------------------- | ----------- | -------------------------------------------------------- |
| `variant` | `"default" \| "switch"` | `"default"` | Display style - `switch` shows a toggle switch indicator |

### MenuRadioGroup

Groups radio menu items. Alias for `Menu.RadioGroup` from Base UI. Also exported as `DropdownMenuRadioGroup`.

### MenuRadioItem

Radio menu item. Styled wrapper for `Menu.RadioItem` from Base UI. Also exported as `DropdownMenuRadioItem`.

### MenuGroupLabel

Label for a menu group. Also exported as `DropdownMenuLabel`.

| Prop    | Type      | Default | Description                                           |
| ------- | --------- | ------- | ----------------------------------------------------- |
| `inset` | `boolean` | -       | Adds left padding to align with items that have icons |

### MenuSeparator

Visual separator between menu items. Styled wrapper for `Menu.Separator` from Base UI. Also exported as `DropdownMenuSeparator`.

### MenuShortcut

Displays keyboard shortcut text. Custom component (not a Base UI wrapper). Also exported as `DropdownMenuShortcut`.

### MenuSub

Submenu container. Alias for `Menu.SubmenuRoot` from Base UI. Also exported as `DropdownMenuSub`.

### MenuSubTrigger

Trigger for opening a submenu. Also exported as `DropdownMenuSubTrigger`.

| Prop    | Type      | Default | Description                                           |
| ------- | --------- | ------- | ----------------------------------------------------- |
| `inset` | `boolean` | -       | Adds left padding to align with items that have icons |

### MenuSubPopup

Popup for submenu content. Also exported as `DropdownMenuSubContent`.

| Prop          | Type                           | Default   | Description                                                                      |
| ------------- | ------------------------------ | --------- | -------------------------------------------------------------------------------- |
| `align`       | `"start" \| "center" \| "end"` | `"start"` | Alignment relative to the trigger                                                |
| `sideOffset`  | `number`                       | `0`       | Distance from the trigger in pixels                                              |
| `alignOffset` | `number`                       | `-5`      | Offset along the alignment axis. Defaults to `-5` when `align` is not `"center"` |

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-menu-02" description="Menu with hover" />

  <ShowcaseCard name="demo-p-menu-03" description="Menu with checkbox" />

  <ShowcaseCard name="demo-p-menu-04" description="Menu with radio group" />

  <ShowcaseCard name="demo-p-menu-05" description="Menu with link" />

  <ShowcaseCard name="demo-p-menu-06" description="Menu with group labels" />

  <ShowcaseCard name="demo-p-menu-07" description="Nested menu" />

  <ShowcaseCard name="demo-p-menu-08" description="Menu close on click" />

  <ShowcaseCard name="demo-p-menu-09" description="Menu with checkbox items as switches" />
</ShowcaseGrid>


# Menubar
URL: https://www.spaceui.one/primitives/menubar

***

title: Menubar
description: Provides a horizontal desktop-style menu bar with nested dropdowns and submenus for organizing complex application commands.

links:
doc: [https://base-ui.com/react/components/menubar](https://base-ui.com/react/components/menubar)
preview: demo-p-menubar-01
--------------------------

## Installation

<ComponentInstallation name="primitives-menubar" />

## Usage

```tsx
import {
  Menubar,
  MenubarMenu,
  MenubarTrigger,
  MenubarContent,
  MenubarItem,
  MenubarSeparator,
  MenubarShortcut,
} from '@/components/ui/menubar'
```

```tsx
<Menubar>
  <MenubarMenu>
    <MenubarTrigger>File</MenubarTrigger>
    <MenubarContent>
      <MenubarItem>
        New Tab <MenubarShortcut>⌘T</MenubarShortcut>
      </MenubarItem>
      <MenubarItem>New Window</MenubarItem>
      <MenubarSeparator />
      <MenubarItem>Print...</MenubarItem>
    </MenubarContent>
  </MenubarMenu>
</Menubar>
```

## Anatomy

```tsx
<Menubar>
  <MenubarMenu>
    <MenubarTrigger />
    <MenubarPopup>
      <MenubarItem />
      <MenubarSeparator />
    </MenubarPopup>
  </MenubarMenu>
</Menubar>
```

## Accessibility

* Follows the [WAI-ARIA Menubar Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/).

### Keyboard Interactions

| Key                                          | Action                                          |
| :------------------------------------------- | :---------------------------------------------- |
| <Kbd>ArrowRight</Kbd> / <Kbd>ArrowLeft</Kbd> | Moves focus between top-level menu triggers.    |
| <Kbd>ArrowDown</Kbd> / <Kbd>ArrowUp</Kbd>    | Moves focus through items within the open menu. |
| <Kbd>Escape</Kbd>                            | Closes the open menu dropdown.                  |

## API Reference

### Menubar

The root container bar for grouping desktop-style menus. Wrapper for `Menubar` from Base UI.

### MenubarMenu

Individual menu dropdown root. Wrapper for `Menu.Root` from Base UI.

### MenubarTrigger

The button inside the menubar that opens the dropdown menu.

### MenubarPortal

Portal component for rendering the menubar content outside the normal DOM tree. Alias for `Menu.Portal` from Base UI.

### MenubarContent

The popup container for menu items, separators, and nested submenus.

| Prop          | Type                                     | Default    | Description                                                         |
| ------------- | ---------------------------------------- | ---------- | ------------------------------------------------------------------- |
| `side`        | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Preferred edge to position the popup relative to the trigger        |
| `sideOffset`  | `number`                                 | `4`        | Distance from the trigger in pixels                                 |
| `align`       | `"start" \| "center" \| "end"`           | `"start"`  | Alignment relative to the trigger along the cross-axis              |
| `alignOffset` | `number`                                 | `-4`       | Distance in pixels to shift the popup along the alignment axis      |
| `portalProps` | `Menu.Portal.Props`                      | -          | Props forwarded to the internal portal (`keepMounted`, `container`) |

### MenubarGroup

Container for grouping related items within a menubar menu.

### MenubarLabel

Label for a group of menubar items.

| Prop    | Type      | Default | Description                                           |
| ------- | --------- | ------- | ----------------------------------------------------- |
| `inset` | `boolean` | `false` | Adds left padding to align with items that have icons |

### MenubarItem

An actionable item within the menu popup.

| Prop      | Type                         | Default     | Description                                           |
| --------- | ---------------------------- | ----------- | ----------------------------------------------------- |
| `variant` | `"default" \| "destructive"` | `"default"` | Controls styling for normal or destructive actions    |
| `inset`   | `boolean`                    | `false`     | Adds left padding to align with items that have icons |

### MenubarCheckboxItem

A menu item with checkbox toggle support.

### MenubarRadioGroup / MenubarRadioItem

Radio selection options within a menu group.

### MenubarSeparator

Visual separator between menu items.

### MenubarShortcut

Displays keyboard shortcut key combinations inside menu items.

### MenubarSub / MenubarSubTrigger / MenubarSubContent

Components for creating multi-level nested submenus within menubar dropdowns.

`MenubarSubTrigger` supports `inset?: boolean`.

`MenubarSubContent` accepts `align`, `alignOffset`, and `sideOffset` (defaulting to `0`).


# Meter
URL: https://www.spaceui.one/primitives/meter

***

title: Meter
description: Displays a visual gauge bar showing a quantity within a known range, such as battery level, disk capacity, or password strength.

links:
doc: [https://base-ui.com/react/components/meter#api-reference](https://base-ui.com/react/components/meter#api-reference)
preview: demo-p-meter-01
------------------------

## Installation

<ComponentInstallation name="primitives-meter" />

## Usage

```tsx
import { Meter, MeterLabel, MeterValue } from '@/components/ui/meter'
```

```tsx
<Meter value={40}>
  <MeterLabel>Progress</MeterLabel>
  <MeterValue />
</Meter>
```

## API Reference

### Meter

Root component. Styled wrapper for `Meter.Root` from Base UI with flex column layout.

### MeterTrack

Track container for the meter indicator. Styled wrapper for `Meter.Track` from Base UI.

### MeterIndicator

Visual indicator showing the current value. Styled wrapper for `Meter.Indicator` from Base UI.

### MeterLabel

Label text for the meter. Styled wrapper for `Meter.Label` from Base UI.

### MeterValue

Displays the current value. Styled wrapper for `Meter.Value` from Base UI.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-meter-02" description="Simple meter" />

  <ShowcaseCard name="demo-p-meter-03" description="Meter with formatted value" />

  <ShowcaseCard name="demo-p-meter-04" description="Meter with range" />
</ShowcaseGrid>


# Navigation Menu
URL: https://www.spaceui.one/primitives/navigation-menu

***

title: Navigation Menu
description: Organizes primary website navigation into top-level links with rich dropdown preview cards for exploring main sections.

links:
doc: [https://base-ui.com/react/components/navigation-menu](https://base-ui.com/react/components/navigation-menu)
preview: demo-p-navigation-menu-01
----------------------------------

## Installation

<ComponentInstallation name="primitives-navigation-menu" />

## Usage

```tsx
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuContent,
  NavigationMenuPortal,
  NavigationMenuPositioner,
  NavigationMenuPopup,
  NavigationMenuViewport,
  NavigationMenuLink,
} from '@/components/ui/navigation-menu'
```

```tsx
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem value="item-1">
      <NavigationMenuTrigger>Item One</NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink href="/docs">Documentation</NavigationMenuLink>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuLink href="/pricing">Pricing</NavigationMenuLink>
    </NavigationMenuItem>
  </NavigationMenuList>

  <NavigationMenuPortal>
    <NavigationMenuPositioner sideOffset={8}>
      <NavigationMenuPopup>
        <NavigationMenuViewport />
      </NavigationMenuPopup>
    </NavigationMenuPositioner>
  </NavigationMenuPortal>
</NavigationMenu>
```

## Anatomy

```tsx
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger />
      <NavigationMenuContent />
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```

## Accessibility

* Follows the [WAI-ARIA Navigation Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/).

### Keyboard Interactions

| Key               | Action                                             |
| :---------------- | :------------------------------------------------- |
| <Kbd>Tab</Kbd>    | Moves focus through navigation triggers and links. |
| <Kbd>Escape</Kbd> | Closes the active flyout content panel.            |

## API Reference

### NavigationMenu

The root container element for navigation items. Wrapper for `NavigationMenu.Root` from Base UI.

### NavigationMenuList

The unordered list containing the navigation menu items. Wrapper for `NavigationMenu.List`.

### NavigationMenuItem

An individual item within the navigation menu list. Accepts a `value` identifier when it has associated dropdown content.

### NavigationMenuTrigger

Interactive trigger button that toggles and switches open submenus on hover/focus.

### NavigationMenuContent

The rich content container rendered inside the shared animated popup.

### NavigationMenuPortal / NavigationMenuPositioner / NavigationMenuPopup

Portal, positioning, and popup wrappers for floating dropdown panels. `NavigationMenuPositioner` accepts `sideOffset?: number` (default `8`) and `align?: "start" | "center" | "end"`.

### NavigationMenuViewport

The clipping viewport that smoothly transitions dimensions between open menus.

### NavigationMenuLink

Navigation link item rendered inside menus or top-level navigation lists.

### NavigationMenuArrow / NavigationMenuBackdrop

Arrow indicator pointing to the active trigger, and optional background backdrop overlay.

### navigationMenuTriggerStyle

Utility helper that generates standard trigger classes for standalone navigation links.


# Number Field
URL: https://www.spaceui.one/primitives/number-field

***

title: Number Field
description: Allows users to enter numeric values or adjust them step-by-step using increment and decrement buttons or keyboard arrow keys.

links:
doc: [https://base-ui.com/react/components/number-field#api-reference](https://base-ui.com/react/components/number-field#api-reference)
preview: demo-p-number-field-01
-------------------------------

## Installation

<ComponentInstallation name="primitives-number-field" />

## Usage

```tsx
import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
  NumberFieldScrubArea,
} from '@/components/ui/number-field'
```

```tsx
<NumberField defaultValue={0}>
  <NumberFieldScrubArea label="Quantity" />
  <NumberFieldGroup>
    <NumberFieldDecrement />
    <NumberFieldInput />
    <NumberFieldIncrement />
  </NumberFieldGroup>
</NumberField>
```

## Anatomy

```tsx
<NumberField>
  <NumberFieldDecrement />
  <NumberFieldInput />
  <NumberFieldIncrement />
</NumberField>
```

## Features

### Stepper Buttons

Number field equipped with increment and decrement stepper controls.

<ComponentPreview name="demo-p-number-field-05" />

### Disabled State

Number field rendered in a disabled state.

<ComponentPreview name="demo-p-number-field-04" />

## Accessibility

* Follows the [WAI-ARIA Spinbutton Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/).

### Keyboard Interactions

| Key                  | Action                                              |
| :------------------- | :-------------------------------------------------- |
| <Kbd>ArrowUp</Kbd>   | Increments the numeric value by the defined step.   |
| <Kbd>ArrowDown</Kbd> | Decrements the numeric value by the defined step.   |
| <Kbd>Home</Kbd>      | Sets the value to the minimum limit (if specified). |
| <Kbd>End</Kbd>       | Sets the value to the maximum limit (if specified). |

## API Reference

### NumberField

Root component. Styled wrapper for `NumberField.Root` from Base UI.

| Prop   | Type                        | Default     | Description                                           |
| ------ | --------------------------- | ----------- | ----------------------------------------------------- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Controls the size of all child components via context |

### NumberFieldGroup

Container for the input and buttons. Styled wrapper for `NumberField.Group` from Base UI.

### NumberFieldInput

Input element for the number value. Styled wrapper for `NumberField.Input` from Base UI.

### NumberFieldIncrement

Button to increment the value. Styled wrapper for `NumberField.Increment` from Base UI with plus icon.

### NumberFieldDecrement

Button to decrement the value. Styled wrapper for `NumberField.Decrement` from Base UI with minus icon.

### NumberFieldScrubArea

Draggable area for scrubbing the value. Styled wrapper for `NumberField.ScrubArea` from Base UI.

| Prop    | Type     | Default | Description                            |
| ------- | -------- | ------- | -------------------------------------- |
| `label` | `string` | -       | Label text displayed in the scrub area |

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-number-field-02" description="Small number field" />

  <ShowcaseCard name="demo-p-number-field-03" description="Large number field" />

  <ShowcaseCard name="demo-p-number-field-06" description="Number field with scrub" />

  <ShowcaseCard name="demo-p-number-field-07" description="Number field with range" />

  <ShowcaseCard name="demo-p-number-field-08" description="Number field with formatted value" />

  <ShowcaseCard name="demo-p-number-field-09" description="Number field with step" />

  <ShowcaseCard name="demo-p-number-field-10" description="Number field in form" />

  <ShowcaseCard name="demo-p-number-field-11" description="Pill-shaped number field" />
</ShowcaseGrid>


# OTP Field
URL: https://www.spaceui.one/primitives/otp-field

***

title: OTP Field
description: Provides individual segmented character boxes for typing verification codes and one-time passwords, with automatic focus progression.

links:
doc: [https://base-ui.com/react/components/otp-field](https://base-ui.com/react/components/otp-field)
preview: demo-p-otp-field-01
----------------------------

This component wraps [Base UI OTP Field](https://base-ui.com/react/components/otp-field).

## Installation

<ComponentInstallation name="primitives-otp-field" />

## Usage

```tsx
import { OTPField, OTPFieldInput, OTPFieldSeparator } from '@/components/ui/otp-field'
```

```tsx
<OTPField aria-label="Verification code" length={6}>
  <OTPFieldInput />
  <OTPFieldInput aria-label="Character 2 of 6" />
  <OTPFieldInput aria-label="Character 3 of 6" />
  <OTPFieldSeparator />
  <OTPFieldInput aria-label="Character 4 of 6" />
  <OTPFieldInput aria-label="Character 5 of 6" />
  <OTPFieldInput aria-label="Character 6 of 6" />
</OTPField>
```

## Anatomy

```tsx
<OtpField>
  <OtpFieldGroup>
    <OtpFieldSlot index={0} />
    <OtpFieldSlot index={1} />
    <OtpFieldSlot index={2} />
    <OtpFieldSlot index={3} />
  </OtpFieldGroup>
</OtpField>
```

## Features

### Masked Input

OTP input with password-style bullet masking.

<ComponentPreview name="demo-p-otp-field-02" />

### With Separator

OTP field divided into separated slot groups using `OtpFieldSeparator`.

<ComponentPreview name="demo-p-otp-field-03" />

## Accessibility

* Manages input focus automatically as characters are typed or deleted.
* Supports pasting multi-digit OTP codes seamlessly across slots.

### Keyboard Interactions

| Key                                          | Action                                                      |
| :------------------------------------------- | :---------------------------------------------------------- |
| <Kbd>Backspace</Kbd>                         | Deletes current digit and moves focus to the previous slot. |
| <Kbd>ArrowLeft</Kbd> / <Kbd>ArrowRight</Kbd> | Moves cursor between OTP slots.                             |

## API Reference

This component is built on [Base UI OTP Field](https://base-ui.com/react/components/otp-field). Each slot is a real `<input>`; order in the tree must match `length` on the root.

### OTPField

Root component. Accepts the same props as `OTPField.Root`; `className` is merged with the default layout styles.

Use **`length`** (required) for the number of characters. The previous `maxLength` prop from the legacy `input-otp` package is not used.

| Prop             | Type                                               | Default     | Description                                                                                            |
| ---------------- | -------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------ |
| `size`           | `"default" \| "lg"`                                | `"default"` | Size applied to all slots in the field                                                                 |
| `validationType` | `"numeric" \| "alpha" \| "alphanumeric" \| "none"` | `numeric`   | Which characters are accepted; see [Base UI OTP Field](https://base-ui.com/react/components/otp-field) |
| `mask`           | `boolean`                                          | `false`     | When `true`, masks entered characters in each slot                                                     |

### OTPFieldInput

Renders one OTP character input (Base UI `OTPField.Input`). Slots are ordered by **DOM order** in the tree (no `index` prop).

| Prop          | Type     | Description                                                                                                 |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `className`   | `string` | Merged with the default slot styles                                                                         |
| `placeholder` | `string` | Native placeholder; pair with `focus-visible:placeholder:text-transparent` if hints should hide when typing |

Label the OTP control on the root (`OTPField`) with `aria-label` or a visible `<label>`/`FieldLabel`. In Base UI 1.6+, the first `OTPFieldInput` should inherit that field label, while subsequent slots can use `aria-label` (for example, `Character 2 of 6`).

### OTPFieldSeparator

Visual separator between slot groups. Uses the design-system `Separator` inside `OTPField.Separator` for layout and accessibility.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-otp-field-04" description="OTP field with label" />

  <ShowcaseCard name="demo-p-otp-field-05" description="OTP field with custom sanitization" />

  <ShowcaseCard name="demo-p-otp-field-06" description="OTP field with auto validation" />

  <ShowcaseCard name="demo-p-otp-field-07" description="Alphanumeric OTP field" />

  <ShowcaseCard name="demo-p-otp-field-08" description="OTP field with placeholder hints" />

  <ShowcaseCard name="demo-p-otp-field-09" description="Masked OTP field" />
</ShowcaseGrid>


# Pagination
URL: https://www.spaceui.one/primitives/pagination

***

title: Pagination
description: Splits long lists or tables across multiple pages, letting users browse content page by page using numbered buttons.
preview: demo-p-pagination-01
-----------------------------

## Installation

<ComponentInstallation name="primitives-pagination" />

## Usage

```tsx
import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from '@/components/ui/pagination'
```

```tsx
<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="#" />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#">1</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis />
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="#" />
    </PaginationItem>
  </PaginationContent>
</Pagination>
```

## Features

### Sibling Count

Pagination controlling the number of page siblings rendered next to the active page.

<ComponentPreview name="demo-p-pagination-02" />

### Compact Layout

Compact icon-only pagination without textual prev/next labels.

<ComponentPreview name="demo-p-pagination-03" />

## API Reference

This is a custom component, not a Base UI wrapper.

### Pagination

Root navigation container with `role="navigation"` and `aria-label="pagination"`.

### PaginationContent

Unordered list container for pagination items.

### PaginationItem

Individual list item container.

### PaginationLink

Link element for page numbers. Supports the `render` prop.

| Prop       | Type                  | Default  | Description                                        |
| ---------- | --------------------- | -------- | -------------------------------------------------- |
| `isActive` | `boolean`             | -        | Highlights the link as the current page            |
| `size`     | `"default" \| "icon"` | `"icon"` | Controls the link size                             |
| `render`   | `React.ReactElement`  | -        | Render as a different element (e.g., Next.js Link) |

### PaginationPrevious

Link to the previous page. Includes a chevron left icon and "Previous" text.

### PaginationNext

Link to the next page. Includes "Next" text and a chevron right icon.

### PaginationEllipsis

Ellipsis indicator for skipped pages. Displays "..." with screen reader text "More pages".


# Popover
URL: https://www.spaceui.one/primitives/popover

***

title: Popover
description: Opens a floating content box anchored to a button or icon, showing interactive settings, tools, or details right next to the trigger.

links:
doc: [https://base-ui.com/react/components/popover#api-reference](https://base-ui.com/react/components/popover#api-reference)
preview: demo-p-popover-01
--------------------------

## Installation

<ComponentInstallation name="primitives-popover" />

## Usage

```tsx
import {
  Popover,
  PopoverClose,
  PopoverDescription,
  PopoverPopup,
  PopoverTitle,
  PopoverTrigger,
} from '@/components/ui/popover'
```

```tsx
<Popover>
  <PopoverTrigger>Open Popover</PopoverTrigger>
  <PopoverPopup>
    <PopoverTitle>Popover Title</PopoverTitle>
    <PopoverDescription>Popover Description</PopoverDescription>
    <PopoverClose>Close</PopoverClose>
  </PopoverPopup>
</Popover>
```

## Anatomy

```tsx
<Popover>
  <PopoverTrigger />
  <PopoverPopup>
    <PopoverHeader>
      <PopoverTitle />
      <PopoverDescription />
    </PopoverHeader>
    <PopoverClose />
  </PopoverPopup>
</Popover>
```

## Accessibility

* Adheres to the [WAI-ARIA Dialog Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/).
* Focus stays contained or accessible within the floating panel.

### Keyboard Interactions

| Key                                 | Action                          |
| :---------------------------------- | :------------------------------ |
| <Kbd>Space</Kbd> / <Kbd>Enter</Kbd> | Toggles the popover open state. |
| <Kbd>Escape</Kbd>                   | Dismisses the popover.          |

## API Reference

### Popover

Root component. Alias for `Popover.Root` from Base UI.

### PopoverTrigger

Trigger button that opens the popover. Alias for `Popover.Trigger` from Base UI.

### PopoverPopup

Popup container that displays the popover content. Also exported as `PopoverContent`.

| Prop           | Type                                          | Default    | Description                                                                                               |
| -------------- | --------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------- |
| `tooltipStyle` | `boolean`                                     | `false`    | When true, applies tooltip-like styling (smaller padding, arrow)                                          |
| `side`         | `"top" \| "bottom" \| "left" \| "right"`      | `"bottom"` | Side of the trigger to position the popup                                                                 |
| `align`        | `"start" \| "center" \| "end"`                | `"center"` | Alignment relative to the trigger                                                                         |
| `sideOffset`   | `number`                                      | `4`        | Distance from the trigger in pixels                                                                       |
| `alignOffset`  | `number`                                      | `0`        | Offset along the alignment axis                                                                           |
| `anchor`       | `Element \| null \| React.RefObject<Element>` | -          | Custom anchor element or ref to anchor the popup against                                                  |
| `portalProps`  | `Popover.Portal.Props`                        | -          | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Popover portal API |

### PopoverTitle

Title text for the popover. Styled wrapper for `Popover.Title` from Base UI.

### PopoverDescription

Description text for the popover. Styled wrapper for `Popover.Description` from Base UI.

### PopoverClose

Close button for the popover. Alias for `Popover.Close` from Base UI.

### PopoverCreateHandle

Creates a handle for detached popover triggers. Returns a handle object to attach to multiple triggers.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-popover-02" description="Popover with close button" />

  <ShowcaseCard name="demo-p-popover-03" description="Animated popovers" />

  <ShowcaseCard name="demo-p-popover-04" description="Split button with popover to confirm multiple occurrences" />
</ShowcaseGrid>


# Preview Card
URL: https://www.spaceui.one/primitives/preview-card

***

title: Preview Card
description: Displays an informative preview card when users hover over a link, giving them a summary of the linked page before clicking.

links:
doc: [https://base-ui.com/react/components/preview-card#api-reference](https://base-ui.com/react/components/preview-card#api-reference)
preview: demo-p-preview-card-01
-------------------------------

## Installation

<ComponentInstallation name="primitives-preview-card" />

## Usage

```tsx
import { Button } from '@/components/ui/button'
import { PreviewCard, PreviewCardPopup, PreviewCardTrigger } from '@/components/ui/preview-card'
```

```tsx
<PreviewCard>
  <PreviewCardTrigger>Open Preview Card</PreviewCardTrigger>
  <PreviewCardPopup>Preview Card Content</PreviewCardPopup>
</PreviewCard>
```

## API Reference

### PreviewCard

Root component. Alias for `PreviewCard.Root` from Base UI.

### PreviewCardTrigger

Trigger element that shows the preview card on hover. Alias for `PreviewCard.Trigger` from Base UI.

### PreviewCardPopup

Popup container that displays the preview content. Also exported as `HoverCardContent`.

| Prop          | Type                                          | Default    | Description                                                                                                    |
| ------------- | --------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
| `align`       | `"start" \| "center" \| "end"`                | `"center"` | Alignment relative to the trigger                                                                              |
| `sideOffset`  | `number`                                      | `4`        | Distance from the trigger in pixels                                                                            |
| `anchor`      | `Element \| null \| React.RefObject<Element>` | -          | Custom anchor element or ref to anchor the popup against                                                       |
| `portalProps` | `PreviewCard.Portal.Props`                    | -          | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Preview Card portal API |

### PreviewCardPortal / PreviewCardPositioner / PreviewCardArrow / PreviewCardBackdrop

Primitive sub-components for custom positioning, arrows, backdrops, and portal rendering.

### Aliases

`PreviewCard`, `PreviewCardTrigger`, and `PreviewCardPopup` are also exported as `HoverCard`, `HoverCardTrigger`, and `HoverCardContent`.


# Preview Link Card
URL: https://www.spaceui.one/primitives/preview-link-card

***

title: Preview Link Card
description: Displays an interactive card preview of a website with its thumbnail, title, and domain name when shared or hovered.
links:
doc: [https://base-ui.com/react/components/preview-card#api-reference](https://base-ui.com/react/components/preview-card#api-reference)
preview: demo-p-preview-link-card-01
------------------------------------

## Installation

<ComponentInstallation name="primitives-preview-link-card" />

## Usage

```tsx
import {
  PreviewLinkCard,
  PreviewLinkCardImage,
  PreviewLinkCardPopup,
  PreviewLinkCardPortal,
  PreviewLinkCardPositioner,
  PreviewLinkCardTrigger,
} from '@/components/ui/preview-link-card'
```

```tsx
<PreviewLinkCard href="https://www.spaceui.one/docs">
  <PreviewLinkCardTrigger>Space UI Docs</PreviewLinkCardTrigger>
  <PreviewLinkCardPortal>
    <PreviewLinkCardPositioner>
      <PreviewLinkCardPopup>
        <PreviewLinkCardImage alt="Preview link card content" />
      </PreviewLinkCardPopup>
    </PreviewLinkCardPositioner>
  </PreviewLinkCardPortal>
</PreviewLinkCard>
```

## Credits

* Built with [@base-ui/react](https://base-ui.com/react/components/preview-card)
* Inspired by [Aceternity UI Link Preview](https://ui.aceternity.com/components/link-preview)

## API Reference

### PreviewLinkCard Props

| Prop                        | Type                    | Default                           | Description                                |
| :-------------------------- | :---------------------- | :-------------------------------- | :----------------------------------------- |
| `href`                      | `string`                | *required*                        | Target URL for the link                    |
| `src`                       | `string`                | -                                 | Preview image source URL                   |
| `width`                     | `number`                | -                                 | Width of the preview image                 |
| `height`                    | `number`                | -                                 | Height of the preview image                |
| `deviceScaleFactor`         | `number`                | `1`                               | Device scale factor for rendering          |
| `colorScheme`               | `"light" \| "dark"`     | `"light"`                         | Color scheme preference                    |
| `followCursor`              | `boolean \| "x" \| "y"` | `false`                           | Makes preview popup follow cursor movement |
| `followCursorSpringOptions` | `SpringOptions`         | `{ stiffness: 200, damping: 17 }` | Physics configuration for cursor following |

### PreviewLinkCardTrigger Props

Triggers the preview link popup when hovered. Renders as native `<a>` tag with standard anchor attributes.

### PreviewLinkCardPopup Props

| Prop         | Type         | Default                                           | Description                               |
| :----------- | :----------- | :------------------------------------------------ | :---------------------------------------- |
| `transition` | `Transition` | `{ type: 'spring', stiffness: 300, damping: 25 }` | Animation spring transition for the popup |

### PreviewLinkCardImage Props

| Prop  | Type     | Default           | Description                  |
| :---- | :------- | :---------------- | :--------------------------- |
| `alt` | `string` | `"preview image"` | Alternative text for preview |


# Progress
URL: https://www.spaceui.one/primitives/progress

***

title: Progress
description: Displays an animated progress bar indicating how much of a task or file upload has completed so users know how long to wait.

links:
doc: [https://base-ui.com/react/components/progress#api-reference](https://base-ui.com/react/components/progress#api-reference)
preview: demo-p-progress-01
---------------------------

## Installation

<ComponentInstallation name="primitives-progress" />

## Usage

```tsx
import { Progress, ProgressLabel, ProgressValue } from '@/components/ui/progress'
```

```tsx
<Progress value={40} />
```

Note: If you render children inside `Progress`, you must also include `ProgressTrack` and `ProgressIndicator` inside it. Without them, the bar will not display. When no children are provided, a default track and indicator are rendered for you.

## Features

### Indeterminate State

Progress indicator displaying an indeterminate animated loading bar (`value={null}`).

<ComponentPreview name="demo-p-progress-03" />

## API Reference

### Progress

Root component. Styled wrapper for `Progress.Root` from Base UI. When no children are provided, automatically renders a track and indicator.

### ProgressTrack

Track container for the progress indicator. Styled wrapper for `Progress.Track` from Base UI.

### ProgressIndicator

Visual indicator showing the current progress. Styled wrapper for `Progress.Indicator` from Base UI.

### ProgressLabel

Label text for the progress bar. Styled wrapper for `Progress.Label` from Base UI.

### ProgressValue

Displays the current value. Styled wrapper for `Progress.Value` from Base UI.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-progress-02" description="Progress with label and value" />
</ShowcaseGrid>

### With Label and Value

<ComponentPreview name="demo-p-progress-02" />

### With Formatted Value

<ComponentPreview name="demo-p-progress-03" />


# Radio Group
URL: https://www.spaceui.one/primitives/radio-group

***

title: Radio Group
description: Presents a list of options where users can select only one choice at a time, making mutually exclusive decisions clear.

links:
doc: [https://base-ui.com/react/components/radio#api-reference](https://base-ui.com/react/components/radio#api-reference)
preview: demo-p-radio-group-01
------------------------------

## Installation

<ComponentInstallation name="primitives-radio-group" />

## Usage

```tsx
import { Label } from '@/components/ui/label'
import { Radio, RadioGroup } from '@/components/ui/radio-group'
```

```tsx
<RadioGroup defaultValue="next">
  <Label>
    <Radio value="next" /> Next.js
  </Label>
  <Label>
    <Radio value="vite" /> Vite
  </Label>
  <Label>
    <Radio value="astro" /> Astro
  </Label>
</RadioGroup>
```

## Anatomy

```tsx
<RadioGroup>
  <Radio value="1">
    <RadioIndicator />
  </Radio>
</RadioGroup>
```

## Features

### Sizes

Radio buttons in `sm`, `default`, and `lg` sizes.

<ComponentPreview name="demo-p-radio-group-02" />

## Accessibility

* Follows the [WAI-ARIA Radio Group Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).

### Keyboard Interactions

| Key                                          | Action                                        |
| :------------------------------------------- | :-------------------------------------------- |
| <Kbd>ArrowDown</Kbd> / <Kbd>ArrowRight</Kbd> | Moves selection to the next radio option.     |
| <Kbd>ArrowUp</Kbd> / <Kbd>ArrowLeft</Kbd>    | Moves selection to the previous radio option. |

## API Reference

### RadioGroup

Root component. Styled wrapper for `RadioGroup.Root` from Base UI with flex column layout.

### Radio

Individual radio button. Styled wrapper for `Radio.Root` from Base UI with built-in indicator. Also exported as `RadioGroupItem`.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-radio-group-03" description="Radio group card" />

  <ShowcaseCard name="demo-p-radio-group-04" description="Radio group in form" />

  <ShowcaseCard name="demo-p-radio-group-05" description="Theme selector with image cards" />
</ShowcaseGrid>


# Scroll Area
URL: https://www.spaceui.one/primitives/scroll-area

***

title: Scroll Area
description: Replaces standard browser scrollbars with custom, theme-styled scrollbars that appear smoothly when scrolling.

links:
doc: [https://base-ui.com/react/components/scroll-area#api-reference](https://base-ui.com/react/components/scroll-area#api-reference)
preview: demo-p-scroll-area-01
------------------------------

## Installation

<ComponentInstallation name="primitives-scroll-area" />

## Usage

```tsx
import { ScrollArea } from '@/components/ui/scroll-area'
```

```tsx
<ScrollArea className="h-64 rounded-md border">
  <div className="p-4">
    Just as suddenly as it had begun, the sensation stopped, leaving Alice feeling slightly disoriented. She looked
    around and realized that the room hadn't changed at all - it was she who had grown smaller, shrinking down to a
    fraction of her previous size. Alice felt herself growing larger and larger, filling up the entire room until she
    feared she might burst. The sensation was both thrilling and terrifying, as if she were expanding beyond the
    confines of her own body. She wondered if this was what it felt like to be a balloon, swelling with air until it
    could hold no more.
  </div>
</ScrollArea>
```

## Anatomy

```tsx
<ScrollArea>
  <ScrollAreaViewport />
  <ScrollAreaScrollbar>
    <ScrollAreaThumb />
  </ScrollAreaScrollbar>
</ScrollArea>
```

## API Reference

### ScrollArea

Root component. Styled wrapper for `ScrollArea.Root` from Base UI with custom scrollbar styling.

| Prop                   | Type      | Default | Description                                                                                                                  |
| ---------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `scrollFade`           | `boolean` | `false` | Masks viewport edges so content fades in/out as you scroll                                                                   |
| `scrollbarGutter`      | `boolean` | `false` | Reserves space for the scrollbar to prevent layout shifts                                                                    |
| `fill`                 | `boolean` | `false` | Applies `size-full` to the scroll area content wrapper so flex layouts (e.g. `mt-auto` footers) can fill the viewport height |
| `clampContentMinWidth` | `boolean` | `true`  | Sets `minWidth: 0` on the content wrapper to avoid spurious horizontal scrollbars in vertical layouts                        |
| `overscrollContain`    | `boolean` | `false` | Prevents scroll chaining into parent scrollers when the viewport overflows                                                   |

### ScrollAreaViewport

Scrollable viewport container. Styled wrapper for `ScrollArea.Viewport` from Base UI.

### ScrollBar

Scrollbar track and thumb wrapper with automatic vertical/horizontal layout. Styled wrapper for `ScrollArea.Scrollbar` from Base UI.

| Prop          | Type                         | Default      | Description                                |
| ------------- | ---------------------------- | ------------ | ------------------------------------------ |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Direction and layout axis of the scrollbar |

### ScrollAreaScrollbar

Scrollbar track. Styled wrapper for `ScrollArea.Scrollbar` from Base UI.

### ScrollAreaThumb

Scrollbar thumb. Styled wrapper for `ScrollArea.Thumb` from Base UI.

### ScrollAreaCorner

Corner element when both scrollbars are visible. Alias for `ScrollArea.Corner` from Base UI.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-scroll-area-02" description="Horizontal scroll area" />

  <ShowcaseCard name="demo-p-scroll-area-03" description="Scroll area with both directions" />

  <ShowcaseCard name="demo-p-scroll-area-04" description="Scroll area with fading edges" />

  <ShowcaseCard name="demo-p-scroll-area-05" description="Horizontal scroll area with scrollbar gutter" />
</ShowcaseGrid>


# Segmented Control
URL: https://www.spaceui.one/primitives/segmented-control

***

title: Segmented Control
description: A visual pattern for presenting related choices, navigation destinations, filters, or content views.
preview: demo-p-radio-group-06
------------------------------

## About

A segmented control is a visual pattern, not a standalone behavior. It uses the same presentation across several components while preserving the semantics, keyboard interactions, and state model of each underlying primitive.

## Choose the right primitive

| Intent                            | Use                                                  | Why                                                                   |
| --------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------- |
| Choose one value in a form        | [Radio Group](/docs/ui-kit/primitives/radio-group)   | Represents a mutually exclusive value and participates in form state. |
| Navigate to another URL or route  | Navigation links                                     | Preserves link behavior, browser history, and `aria-current`.         |
| Apply an exclusive filter or mode | [Toggle Group](/docs/ui-kit/primitives/toggle-group) | Represents the pressed state of an action that may be cleared.        |
| Switch between related panels     | [Tabs](/docs/ui-kit/primitives/tabs)                 | Connects each tab to an associated content panel.                     |

Choose the primitive from the interaction first, then apply the segmented-control styling. Visual similarity alone is not a reason to use Tabs or Toggle Group.

## Shared styling

For a custom composition, use the shared styling library:

```tsx
import {
  segmentedControlItemLayoutClassName,
  segmentedControlItemVariants,
  segmentedControlRootClassName,
} from '@/lib/segmented-control'
```

```tsx
const itemClassName = segmentedControlItemVariants({
  size: 'default',
  state: 'checked',
})
```

| Option  | Values                                | Description                                                 |
| ------- | ------------------------------------- | ----------------------------------------------------------- |
| `size`  | `"sm" \| "default" \| "lg"`           | Controls item height and horizontal padding.                |
| `state` | `"checked" \| "current" \| "pressed"` | Selects the state attribute used by the underlying element. |

Use `checked` with Radio Group, `current` with navigation links, and `pressed` with Toggle Group. Tabs retain their own animated indicator and do not use the shared state recipe. They reuse `segmentedControlItemLayoutClassName` so icons match the other segmented implementations.

## Radio options

Use Radio Group when the selected segment represents a mutually exclusive value, especially in forms.

<ComponentPreview name="demo-p-radio-group-06" />

## Navigation

Use links when each segment points to a different destination. Apply `aria-current="page"` to the active link.

<ComponentPreview name="demo-p-navigation-02" />

## Tabs

Use Tabs when each segment controls an associated content panel. Tabs share the visual language of segmented controls but keep their animated indicator, orientation support, and panel semantics.

<ComponentPreview name="demo-p-tabs-01" />


# Select
URL: https://www.spaceui.one/primitives/select

***

title: Select
description: Allows users to pick one or more options from a collapsible dropdown menu, keeping forms compact and easy to navigate.

links:
doc: [https://base-ui.com/react/components/select#api-reference](https://base-ui.com/react/components/select#api-reference)
preview: demo-p-select-01
-------------------------

## Installation

<ComponentInstallation name="primitives-select" />

## Usage

```tsx
import { Select, SelectItem, SelectPopup, SelectLabel, SelectTrigger, SelectValue } from '@/components/ui/select'

const items = [
  { label: 'Select framework', value: null },
  { label: 'Next.js', value: 'next' },
  { label: 'Vite', value: 'vite' },
  { label: 'Astro', value: 'astro' },
]

export default function SpaceUI() {
  return (
    <Select items={items}>
      <SelectTrigger>
        <SelectValue />
      </SelectTrigger>
      <SelectPopup>
        <SelectLabel>Frameworks</SelectLabel>
        {items.map((item) => (
          <SelectItem key={item.value} value={item}>
            {item.label}
          </SelectItem>
        ))}
      </SelectPopup>
    </Select>
  )
}
```

## Anatomy

```tsx
<Select>
  <SelectTrigger>
    <SelectValue />
  </SelectTrigger>
  <SelectPopup>
    <SelectList>
      <SelectGroup>
        <SelectGroupLabel />
        <SelectItem />
      </SelectGroup>
    </SelectList>
  </SelectPopup>
</Select>
```

## Features

### Sizes

Select triggers in `sm`, `default`, and `lg` sizes.

<ComponentPreview name="demo-p-select-02" />

## Accessibility

* Adheres to the [WAI-ARIA Combobox / Select Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
* Supports quick typeahead navigation to jump directly to options by typing.

### Keyboard Interactions

| Key                                 | Action                                                  |
| :---------------------------------- | :------------------------------------------------------ |
| <Kbd>Space</Kbd> / <Kbd>Enter</Kbd> | Opens the select dropdown or selects the active option. |
| <Kbd>ArrowDown</Kbd>                | Moves highlight to the next item.                       |
| <Kbd>ArrowUp</Kbd>                  | Moves highlight to the previous item.                   |
| <Kbd>Escape</Kbd>                   | Closes the dropdown without making a selection.         |

### Disabled State

Select component rendered in a disabled state via `disabled`.

<ComponentPreview name="demo-p-select-03" />

### Disabled Items

Select containing individual disabled option items.

<ComponentPreview name="demo-p-select-11" />

## API Reference

### Select

Root component. Alias for `Select.Root` from Base UI.

### SelectTrigger

Trigger button that opens the select dropdown. Styled wrapper for `Select.Trigger` from Base UI.

| Prop   | Type                        | Default     | Description                      |
| ------ | --------------------------- | ----------- | -------------------------------- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Controls the size of the trigger |

### SelectValue

Displays the selected value. Styled wrapper for `Select.Value` from Base UI.

### SelectPopup

Popup container for select options. Also exported as `SelectContent`.

| Prop                   | Type                                          | Default    | Description                                                                                              |
| ---------------------- | --------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------- |
| `showIcon`             | `boolean`                                     | `true`     | Controls whether checkmark indicators are displayed next to items                                        |
| `side`                 | `"top" \| "bottom" \| "left" \| "right"`      | `"bottom"` | Preferred edge to position the popup relative to the trigger                                             |
| `sideOffset`           | `number`                                      | `4`        | Distance from the trigger in pixels                                                                      |
| `align`                | `"start" \| "center" \| "end"`                | `"start"`  | Alignment relative to the trigger along the cross-axis                                                   |
| `alignOffset`          | `number`                                      | `0`        | Distance in pixels to shift the popup along the alignment axis                                           |
| `alignItemWithTrigger` | `boolean`                                     | `true`     | Aligns the selected item with the trigger                                                                |
| `anchor`               | `Element \| null \| React.RefObject<Element>` | -          | Custom anchor element or ref to anchor the popup against                                                 |
| `portalProps`          | `Select.Portal.Props`                         | -          | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Select portal API |

### SelectItem

Individual select option. Styled wrapper for `Select.Item` from Base UI with built-in indicator.

| Prop       | Type      | Default | Description                                               |
| ---------- | --------- | ------- | --------------------------------------------------------- |
| `showIcon` | `boolean` | `true`  | Overrides popup showIcon setting for this individual item |

### SelectGroup

Groups related select items. Alias for `Select.Group` from Base UI.

### SelectLabel

Label for all options in the popup. Styled wrapper for `Select.Label` from Base UI. Clicking it focuses the select trigger without opening the popup.

### SelectGroupLabel

Label for a select group. Styled wrapper for `Select.GroupLabel` from Base UI.

### SelectSeparator

Visual separator between items. Styled wrapper for `Select.Separator` from Base UI.

### SelectButton

A standalone button styled like a `SelectTrigger`. Use it as a `render` prop on other trigger components (e.g., `ComboboxTrigger`, `MenuTrigger`) to give them select-like appearance.

| Prop   | Type                        | Default     | Description                     |
| ------ | --------------------------- | ----------- | ------------------------------- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Controls the size of the button |

```tsx
import { SelectButton } from '@/components/ui/select'
```

```tsx
<ComboboxTrigger render={<SelectButton />}>
  <ComboboxValue placeholder="Select a fruit" />
</ComboboxTrigger>
```

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-select-04" description="Select without item alignment" />

  <ShowcaseCard name="demo-p-select-05" description="Select with groups" />

  <ShowcaseCard name="demo-p-select-06" description="Multiple select" />

  <ShowcaseCard name="demo-p-select-07" description="Select with icon" />

  <ShowcaseCard name="demo-p-select-08" description="Select options with icon" />

  <ShowcaseCard name="demo-p-select-09" description="Select with object values" />

  <ShowcaseCard name="demo-p-select-10" description="Select in form" />

  <ShowcaseCard name="demo-p-select-12" description="Timezone select" />

  <ShowcaseCard name="demo-p-select-13" description="Status select with colored dot" />

  <ShowcaseCard name="demo-p-select-14" description="Pill-shaped select trigger" />

  <ShowcaseCard name="demo-p-select-15" description="Select with left text label" />

  <ShowcaseCard name="demo-p-select-16" description="Select with country flags" />

  <ShowcaseCard name="demo-p-select-17" description="Select with description in options only" />

  <ShowcaseCard name="demo-p-select-18" description="Select with avatars" />

  <ShowcaseCard name="demo-p-select-19" description="Rich select with avatars and usernames" />

  <ShowcaseCard name="demo-p-select-20" description="Auto width select" />

  <ShowcaseCard name="demo-p-select-21" description="Select with custom border and background" />

  <ShowcaseCard name="demo-p-select-22" description="Select with label" />
</ShowcaseGrid>


# Separator
URL: https://www.spaceui.one/primitives/separator

***

title: Separator
description: Draws clean horizontal or vertical dividing lines between content blocks or tools to create clear visual separation.

links:
doc: [https://base-ui.com/react/components/separator#api-reference](https://base-ui.com/react/components/separator#api-reference)
preview: demo-p-separator-01
----------------------------

## Installation

<ComponentInstallation name="primitives-separator" />

## Usage

```tsx
import { Separator } from '@/components/ui/separator'
```

```tsx
<Separator />
```

## API Reference

### Separator

Styled wrapper for `Separator` from Base UI. Renders as a horizontal line by default with muted background color.

| Prop          | Type                         | Default        | Description                              |
| ------------- | ---------------------------- | -------------- | ---------------------------------------- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Visual orientation of the separator line |


# Sheet
URL: https://www.spaceui.one/primitives/sheet

***

title: Sheet
description: Opens a slide-out panel from the edge of the screen, giving users space to edit settings or fill out forms without leaving the page.

links:
doc: [https://base-ui.com/react/components/dialog#api-reference](https://base-ui.com/react/components/dialog#api-reference)
preview: demo-p-sheet-01
------------------------

## Installation

<ComponentInstallation name="primitives-sheet" />

## Usage

```tsx
import {
  Sheet,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetPanel,
  SheetPopup,
  SheetTitle,
  SheetTrigger,
} from '@/components/ui/sheet'
```

```tsx
<Sheet>
  <SheetTrigger>Open</SheetTrigger>
  <SheetPopup>
    <SheetHeader>
      <SheetTitle>Are you absolutely sure?</SheetTitle>
      <SheetDescription>
        This action cannot be undone. This will permanently delete your account and remove your data from our servers.
      </SheetDescription>
    </SheetHeader>
    <SheetPanel>Content</SheetPanel>
    <SheetFooter>
      <SheetClose>Close</SheetClose>
    </SheetFooter>
  </SheetPopup>
</Sheet>
```

## Anatomy

```tsx
<Sheet>
  <SheetTrigger />
  <SheetBackdrop />
  <SheetPopup>
    <SheetHeader>
      <SheetTitle />
      <SheetDescription />
    </SheetHeader>
    <SheetPanel />
    <SheetFooter>
      <SheetClose />
    </SheetFooter>
  </SheetPopup>
</Sheet>
```

## Features

### Inset Variant

Sheet sliding with inset border margins (`variant="inset"`).

<ComponentPreview name="demo-p-sheet-02" />

### Positions

Sheet positioned along different screen edges (`side="left" | "right" | "top" | "bottom"`).

<ComponentPreview name="demo-p-sheet-03" />

## Accessibility

* Traps keyboard focus within the slide-out sheet and locks background scrolling.

### Keyboard Interactions

| Key               | Action                                                 |
| :---------------- | :----------------------------------------------------- |
| <Kbd>Tab</Kbd>    | Moves focus through focusable elements in the sheet.   |
| <Kbd>Escape</Kbd> | Dismisses the sheet and restores focus to the trigger. |

## API Reference

### Sheet

Root component. Alias for `Dialog.Root` from Base UI.

### SheetTrigger

Trigger button that opens the sheet. Alias for `Dialog.Trigger` from Base UI.

### SheetPopup

Popup container that displays the sheet content. Also exported as `SheetContent`.

| Prop              | Type                                     | Default     | Description                                                                                              |
| ----------------- | ---------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
| `side`            | `"right" \| "left" \| "top" \| "bottom"` | `"right"`   | Controls which side of the screen the sheet opens from                                                   |
| `variant`         | `"default" \| "inset"`                   | `"default"` | Controls the sheet style. `inset` adds spacing around the sheet on desktop screens                       |
| `showCloseButton` | `boolean`                                | `true`      | When true, displays a close button in the top-right corner                                               |
| `closeProps`      | `Dialog.Close.Props`                     | -           | Props forwarded to the internal close button, useful for overriding `aria-label`                         |
| `portalProps`     | `Dialog.Portal.Props`                    | -           | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Dialog portal API |

**Example:**

```tsx
// Right side sheet (default)
<SheetPopup side="right">
  ...
</SheetPopup>

// Left side sheet
<SheetPopup side="left">
  ...
</SheetPopup>

// Top sheet
<SheetPopup side="top">
  ...
</SheetPopup>

// Bottom sheet
<SheetPopup side="bottom">
  ...
</SheetPopup>

// Sheet with inset variant
<SheetPopup side="right" variant="inset">
  ...
</SheetPopup>
```

### SheetHeader

Container for the sheet title and description. Supports the `render` prop for polymorphic composition (e.g. `render={<Link href="/" />}`).

### SheetFooter

Footer section for action buttons. Supports the `render` prop for polymorphic composition.

| Prop      | Type                  | Default     | Description                                                                                |
| --------- | --------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `variant` | `"default" \| "bare"` | `"default"` | Controls the footer styling. `default` includes border and background, `bare` removes them |

### SheetTitle

Title component. Alias for `Dialog.Title` from Base UI.

### SheetDescription

Description component. Alias for `Dialog.Description` from Base UI.

### SheetPanel

Scrollable content container. Automatically wraps content in a `ScrollArea` component. Supports the `render` prop for polymorphic composition.

| Prop         | Type      | Default | Description                                    |
| ------------ | --------- | ------- | ---------------------------------------------- |
| `scrollFade` | `boolean` | `true`  | When true, shows a fade effect at scroll edges |

**Example:**

```tsx
<SheetPanel>
  {/* Long content that will scroll if it exceeds the sheet height */}
  <div>...</div>
</SheetPanel>
```

### SheetClose

Close button component. Alias for `Dialog.Close` from Base UI.

### SheetPortal

Portal component for rendering outside the DOM hierarchy. Alias for `Dialog.Portal` from Base UI.

### SheetBackdrop

Backdrop/overlay component. Also exported as `SheetOverlay`. Alias for `Dialog.Backdrop` from Base UI.

### SheetViewport

Viewport container that handles screen edge alignment and positioning for the sheet popup. Alias for `Dialog.Viewport` from Base UI.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1} />


# Sidebar
URL: https://www.spaceui.one/primitives/sidebar

***

title: Sidebar
description: Provides a collapsible side navigation bar that organizes app pages into sections, supporting both desktop and mobile layouts.
preview:
name: demo-p-sidebar-01
contained: false
----------------

## Installation

<ComponentInstallation name="primitives-sidebar" />

## Usage

```tsx
import {
  SidebarProvider,
  Sidebar,
  SidebarHeader,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarGroupContent,
  SidebarMenu,
  SidebarMenuItem,
  SidebarMenuButton,
  SidebarTrigger,
  SidebarInset,
} from '@/components/ui/sidebar'
```

```tsx
<SidebarProvider>
  <Sidebar>
    <SidebarHeader>
      <h2>Workspace</h2>
    </SidebarHeader>
    <SidebarContent>
      <SidebarGroup>
        <SidebarGroupLabel>Menu</SidebarGroupLabel>
        <SidebarGroupContent>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton asChild>
                <a href="/home">Home</a>
              </SidebarMenuButton>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarGroupContent>
      </SidebarGroup>
    </SidebarContent>
    <SidebarFooter>
      <p>User account</p>
    </SidebarFooter>
  </Sidebar>
  <SidebarInset>
    <header className="flex h-12 items-center px-4 border-b">
      <SidebarTrigger />
    </header>
    <main className="p-4">
      <h1>Content</h1>
    </main>
  </SidebarInset>
</SidebarProvider>
```

## Anatomy

```tsx
<SidebarProvider>
  <Sidebar>
    <SidebarHeader />
    <SidebarContent>
      <SidebarGroup>
        <SidebarGroupLabel />
        <SidebarGroupContent>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton />
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarGroupContent>
      </SidebarGroup>
    </SidebarContent>
    <SidebarFooter />
  </Sidebar>
</SidebarProvider>
```

## Structure & Architecture

The `Sidebar` component is built using a composable slot-based architecture:

* **`SidebarProvider`**: Manages responsive open/close state, mobile drawer transition, and cookie persistence.
* **`Sidebar`**: The main sidebar container supporting collapsible states (`offcanvas`, `icon`, `none`).
* **`SidebarTrigger`**: Toggle button to collapse or expand the sidebar (with keyboard shortcut `Cmd+B` / `Ctrl+B`).
* **`SidebarHeader` / `SidebarFooter`**: Pinned top and bottom areas.
* **`SidebarContent`**: Scrollable body area for navigation items and groups.
* **`SidebarGroup`**: Groups related links together with optional `SidebarGroupLabel` and `SidebarGroupAction`.
* **`SidebarMenu`**: Unordered list container for `SidebarMenuItem` and `SidebarMenuButton`.
* **`SidebarMenuAction` / `SidebarMenuBadge`**: Secondary quick action buttons and badge counters within menu items.
* **`SidebarMenuSub` / `SidebarMenuSubItem` / `SidebarMenuSubButton`**: Nested sub-level navigation items within menus.
* **`SidebarMenuSkeleton`**: Skeleton loader state for dynamic menu items.
* **`SidebarInput` / `SidebarSeparator`**: Input search fields and separators styled specifically for the sidebar.
* **`SidebarRail`**: Interactive resize/rail edge to toggle collapse on hover/click.
* **`SidebarInset`**: Main content container that adjusts margins alongside the sidebar.

## API Reference

### SidebarProvider

| Prop           | Type                      | Default | Description                            |
| -------------- | ------------------------- | ------- | -------------------------------------- |
| `defaultOpen`  | `boolean`                 | `true`  | Initial open state if no cookie is set |
| `open`         | `boolean`                 | -       | Controlled open state                  |
| `onOpenChange` | `(open: boolean) => void` | -       | Callback invoked on open state change  |

### Sidebar

| Prop          | Type                                 | Default       | Description                           |
| ------------- | ------------------------------------ | ------------- | ------------------------------------- |
| `side`        | `"left" \| "right"`                  | `"left"`      | Side on which the sidebar is rendered |
| `variant`     | `"sidebar" \| "floating" \| "inset"` | `"sidebar"`   | Visual appearance variant             |
| `collapsible` | `"offcanvas" \| "icon" \| "none"`    | `"offcanvas"` | Collapse mode on desktop              |

### SidebarMenuButton

Interactive button within a sidebar menu item.

| Prop       | Type                                             | Default     | Description                                          |
| ---------- | ------------------------------------------------ | ----------- | ---------------------------------------------------- |
| `size`     | `"default" \| "sm" \| "lg"`                      | `"default"` | Size dimension variant of the menu button            |
| `isActive` | `boolean`                                        | `false`     | Visual active/current indicator state                |
| `tooltip`  | `string \| React.ComponentProps<typeof Tooltip>` | -           | Tooltip displayed when sidebar is collapsed to icons |

### SidebarMenuAction

Secondary action button placed inside a sidebar menu item.

| Prop          | Type      | Default | Description                                                      |
| ------------- | --------- | ------- | ---------------------------------------------------------------- |
| `showOnHover` | `boolean` | `false` | When true, only reveals the action button when hovering the item |

### SidebarMenuSkeleton

Loading placeholder for sidebar menu items.

| Prop       | Type      | Default | Description                                            |
| ---------- | --------- | ------- | ------------------------------------------------------ |
| `showIcon` | `boolean` | `false` | When true, renders a square skeleton block for an icon |

### SidebarMenuSubButton

Nested sub-level navigation link button within a sidebar submenu.

| Prop       | Type           | Default | Description                             |
| ---------- | -------------- | ------- | --------------------------------------- |
| `size`     | `"sm" \| "md"` | `"md"`  | Height and text scale of the sub-button |
| `isActive` | `boolean`      | `false` | Visual active/current indicator state   |


# Skeleton
URL: https://www.spaceui.one/primitives/skeleton

***

title: Skeleton
description: Displays animated placeholder shapes while content is loading, giving users immediate visual feedback and making apps feel faster.
preview: demo-p-skeleton-01
---------------------------

## Installation

<ComponentInstallation name="primitives-skeleton" />

## Usage

```tsx
import { Skeleton } from '@/components/ui/skeleton'
```

```tsx
<Skeleton className="size-10 rounded-full" />
```

## API Reference

This is a custom component, not a Base UI wrapper.

### Skeleton

A simple div with animated pulse effect for loading states. Apply sizing and shape via className.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-skeleton-02" description="Skeleton only" />
</ShowcaseGrid>

### Skeleton Only

<ComponentPreview name="demo-p-skeleton-02" />


# Slider
URL: https://www.spaceui.one/primitives/slider

***

title: Slider
description: Allows users to choose a numeric value or range smoothly by sliding a handle along a horizontal track with immediate visual feedback.

links:
doc: [https://base-ui.com/react/components/slider#api-reference](https://base-ui.com/react/components/slider#api-reference)
preview: demo-p-slider-01
-------------------------

## Installation

<ComponentInstallation name="primitives-slider" />

## Usage

```tsx
import { Slider, SliderValue } from '@/components/ui/slider'
```

```tsx
<Slider />
```

## Anatomy

```tsx
<Slider>
  <SliderTrack>
    <SliderRange />
  </SliderTrack>
  <SliderThumb />
</Slider>
```

## Features

### Range Slider

Multi-thumb range slider for selecting value intervals.

<ComponentPreview name="demo-p-slider-07" />

### Vertical Orientation

Vertical slider orientation with `orientation="vertical"`.

<ComponentPreview name="demo-p-slider-17" />

### Disabled State

Slider rendered in a disabled state.

<ComponentPreview name="demo-p-slider-03" />

## Accessibility

* Follows the [WAI-ARIA Slider Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/).

### Keyboard Interactions

| Key                                         | Action                                |
| :------------------------------------------ | :------------------------------------ |
| <Kbd>ArrowRight</Kbd> / <Kbd>ArrowUp</Kbd>  | Increases the slider value.           |
| <Kbd>ArrowLeft</Kbd> / <Kbd>ArrowDown</Kbd> | Decreases the slider value.           |
| <Kbd>Home</Kbd>                             | Sets the slider to the minimum value. |
| <Kbd>End</Kbd>                              | Sets the slider to the maximum value. |

## API Reference

### Slider

Root component. Styled wrapper for `Slider.Root` from Base UI with default min/max values and edge-aligned thumbs.

| Prop           | Type                          | Default | Description                                             |
| -------------- | ----------------------------- | ------- | ------------------------------------------------------- |
| `defaultValue` | `number \| readonly number[]` | -       | The initial uncontrolled value (single number or array) |
| `value`        | `number \| readonly number[]` | -       | The controlled value (single number or array for range) |
| `min`          | `number`                      | `0`     | Minimum value of the slider                             |
| `max`          | `number`                      | `100`   | Maximum value of the slider                             |

Note: The component sets `thumbAlignment="edge"` by default, which aligns thumbs to the edge of the track rather than centering them.

### SliderValue

Displays the current value. Styled wrapper for `Slider.Value` from Base UI.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-slider-02" description="Slider with label and value" />

  <ShowcaseCard name="demo-p-slider-04" description="Slider with reference labels" />

  <ShowcaseCard name="demo-p-slider-05" description="Slider with ticks" />

  <ShowcaseCard name="demo-p-slider-06" description="Slider with labels above" />

  <ShowcaseCard name="demo-p-slider-08" description="Slider with 3 thumbs" />

  <ShowcaseCard name="demo-p-slider-09" description="Range slider with collision behavior none" />

  <ShowcaseCard name="demo-p-slider-10" description="Range slider with collision behavior swap" />

  <ShowcaseCard name="demo-p-slider-11" description="Slider with icons" />

  <ShowcaseCard name="demo-p-slider-12" description="Slider with input" />

  <ShowcaseCard name="demo-p-slider-13" description="Range slider with inputs" />

  <ShowcaseCard name="demo-p-slider-14" description="Slider with increment and decrement buttons" />

  <ShowcaseCard name="demo-p-slider-15" description="Price range slider" />

  <ShowcaseCard name="demo-p-slider-16" description="Emoji rating slider" />

  <ShowcaseCard name="demo-p-slider-18" description="Vertical range slider" />

  <ShowcaseCard name="demo-p-slider-19" description="Vertical slider with input" />

  <ShowcaseCard name="demo-p-slider-20" description="Equalizer with vertical sliders" />

  <ShowcaseCard name="demo-p-slider-21" description="Object position sliders with reset" />

  <ShowcaseCard name="demo-p-slider-22" description="Price slider with histogram" />

  <ShowcaseCard name="demo-p-slider-23" description="Slider in form" />
</ShowcaseGrid>


# Spinner
URL: https://www.spaceui.one/primitives/spinner

***

title: Spinner
description: Displays an animated spinning ring while an action or page is loading, reassuring users that their request is being processed.
preview: demo-p-spinner-01
--------------------------

## Installation

<ComponentInstallation name="primitives-spinner" />

## Usage

```tsx
import { Spinner } from '@/components/ui/spinner'
```

```tsx
<Spinner />
```

## API Reference

### Spinner

Use the `Spinner` component to display a loading indicator.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |


# Switch
URL: https://www.spaceui.one/primitives/switch

***

title: Switch
description: Allows users to toggle a single setting instantly between on and off, behaving just like a physical light switch.

links:
doc: [https://base-ui.com/react/components/switch#api-reference](https://base-ui.com/react/components/switch#api-reference)
preview: demo-p-switch-01
-------------------------

## Installation

<ComponentInstallation name="primitives-switch" />

## Usage

```tsx
import { Switch } from '@/components/ui/switch'
```

```tsx
<Switch />
```

## Anatomy

```tsx
<Switch>
  <SwitchThumb />
</Switch>
```

## Features

### Sizes

Switch toggle controls in `sm`, `default`, and `lg` sizes.

<ComponentPreview name="demo-p-switch-02" />

## Accessibility

* Follows the [WAI-ARIA Switch Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/).

### Keyboard Interactions

| Key                                 | Action                                 |
| :---------------------------------- | :------------------------------------- |
| <Kbd>Space</Kbd> / <Kbd>Enter</Kbd> | Toggles the switch between on and off. |

## API Reference

### Switch

Styled wrapper for `Switch.Root` from Base UI with built-in thumb. Size is controlled via the `--thumb-size` CSS variable.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-switch-03" description="Switch card" />

  <ShowcaseCard name="demo-p-switch-04" description="Switch in form" />

  <ShowcaseCard name="demo-p-switch-05" description="Custom size switch" />

  <ShowcaseCard name="demo-p-switch-06" description="Weekly availability editor with time range combobox pickers" contained={false} />

  <ShowcaseCard name="demo-p-switch-07" description="Weekly availability editor with grouped time range controls" contained={false} />

  <ShowcaseCard name="demo-p-switch-08" description="Weekly availability editor with From/To labeled time groups" contained={false} />
</ShowcaseGrid>


# Table
URL: https://www.spaceui.one/primitives/table

***

title: Table
description: Organizes structured records into clear rows and columns with column headers, hover highlights, and responsive layouts.
preview:
name: demo-p-table-01
contained: false
----------------

## Installation

<ComponentInstallation name="primitives-table" />

## Usage

```tsx
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
  TableRow,
} from '@/components/ui/table'
```

```tsx
<Table>
  <TableCaption>Caption</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead>Header</TableHead>
      <TableHead>Header</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Cell</TableCell>
      <TableCell>Cell</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

## Anatomy

```tsx
<Table>
  <TableCaption />
  <TableHeader>
    <TableRow>
      <TableHead />
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell />
    </TableRow>
  </TableBody>
  <TableFooter />
</Table>
```

## Features

### Card Style Variant

Table styled as card rows with isolated row containers (`variant="card"`).

<ComponentPreview name="demo-p-table-05" contained={false} />

## API Reference

### Table

The main table container component. Set `variant="card"` for a card-style table: separated borders, rounded corners, and row surfaces that read as cards. That pairs well with a [Frame](/ui-kit/primitives/frame) (page chrome) or [Card](/ui-kit/primitives/card) (card shell with optional header actions). The default variant is a simpler row layout with standard borders.

| Prop        | Type                    | Default     |
| ----------- | ----------------------- | ----------- |
| `className` | `string`                |             |
| `variant`   | `"default"` \| `"card"` | `"default"` |

```tsx
<Table>
  <TableHeader>...</TableHeader>
  <TableBody>...</TableBody>
</Table>

<Table variant="card">
  <TableHeader>...</TableHeader>
  <TableBody>...</TableBody>
</Table>
```

### TableHeader

Header section of the table containing column headers.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<TableHeader>
  <TableRow>
    <TableHead>Header</TableHead>
  </TableRow>
</TableHeader>
```

### TableBody

Body section of the table containing table rows and data.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<TableBody>
  <TableRow>
    <TableCell>Cell</TableCell>
  </TableRow>
</TableBody>
```

### TableFooter

Footer section of the table.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<TableFooter>
  <TableRow>
    <TableCell>Footer</TableCell>
  </TableRow>
</TableFooter>
```

### TableRow

A row in the table.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<TableRow>
  <TableCell>Cell</TableCell>
</TableRow>
```

### TableHead

A header cell in the table.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<TableHead>Header</TableHead>
```

### TableCell

A data cell in the table.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<TableCell>Cell</TableCell>
```

### TableCaption

A caption for the table.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<TableCaption>Caption</TableCaption>
```

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-table-02" description="Frame with card-style table" contained={false} />

  <ShowcaseCard name="demo-p-table-03" description="Table with TanStack Table and checkboxes" contained={false} />

  <ShowcaseCard name="demo-p-table-04" description="Table with TanStack Table, sorting, and pagination" contained={false} />

  <ShowcaseCard name="demo-p-table-06" description="CardFrame with TanStack Table and checkboxes" contained={false} />

  <ShowcaseCard name="demo-p-table-07" description="CardFrame with card-style table" contained={false} />

  <ShowcaseCard name="demo-p-table-08" description="CardFrame with TanStack Table, sorting, and pagination" contained={false} />

  <ShowcaseCard name="demo-p-table-09" description="CardFrame with TanStack Table, sorting, and pagination" contained={false} />
</ShowcaseGrid>


# Tabs
URL: https://www.spaceui.one/primitives/tabs

***

title: Tabs
description: Splits content into switchable tabs on a single screen, allowing users to view different sections of related information without reloading the page.

links:
doc: [https://base-ui.com/react/components/tabs#api-reference](https://base-ui.com/react/components/tabs#api-reference)
preview: demo-p-tabs-01
-----------------------

## Installation

<ComponentInstallation name="primitives-tabs" />

## Usage

```tsx
import { Tabs, TabsList, TabsPanel, TabsTab } from '@/components/ui/tabs'
```

```tsx
<Tabs defaultValue="tab-1">
  <TabsList>
    <TabsTab value="tab-1">Tab 1</TabsTab>
    <TabsTab value="tab-2">Tab 2</TabsTab>
    <TabsTab value="tab-3">Tab 3</TabsTab>
  </TabsList>
  <TabsPanel value="tab-1">Tab 1 content</TabsPanel>
  <TabsPanel value="tab-2">Tab 2 content</TabsPanel>
  <TabsPanel value="tab-3">Tab 3 content</TabsPanel>
</Tabs>
```

## Anatomy

```tsx
<Tabs>
  <TabsList>
    <TabsTab />
    <TabsIndicator />
  </TabsList>
  <TabsPanel />
</Tabs>
```

## Features

### Variants

Tabs in rounded button style (`default`) and border line style (`underline`).

<ComponentPreview name="demo-p-tabs-01" />

### Sizes

Tabs triggers in `sm`, `default`, and `lg` sizes.

<ComponentPreview name="demo-p-tabs-02" />

## Accessibility

* Follows the [WAI-ARIA Tabs Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
* Tab triggers and panels are linked via `aria-controls` and `aria-labelledby`.

### Keyboard Interactions

| Key                                          | Action                                                   |
| :------------------------------------------- | :------------------------------------------------------- |
| <Kbd>ArrowRight</Kbd> / <Kbd>ArrowDown</Kbd> | Moves focus to the next tab and activates its panel.     |
| <Kbd>ArrowLeft</Kbd> / <Kbd>ArrowUp</Kbd>    | Moves focus to the previous tab and activates its panel. |
| <Kbd>Home</Kbd>                              | Jumps to and activates the first tab.                    |
| <Kbd>End</Kbd>                               | Jumps to and activates the last tab.                     |

### Vertical Orientation

Tabs navigation arranged vertically using `orientation="vertical"`.

<ComponentPreview name="demo-p-tabs-09" />

## API Reference

### Tabs

Root component. Styled wrapper for `Tabs.Root` from Base UI.

| Prop      | Type                       | Default     | Description               |
| --------- | -------------------------- | ----------- | ------------------------- |
| `variant` | `"default" \| "underline"` | `"default"` | Controls the tabs styling |

### TabsList

Container for tab triggers. Styled wrapper for `Tabs.List` from Base UI.

| Prop      | Type                        | Default     | Description                                           |
| --------- | --------------------------- | ----------- | ----------------------------------------------------- |
| `variant` | `"default" \| "underline"`  | `"default"` | Controls the tabs list variant                        |
| `size`    | `"sm" \| "default" \| "lg"` | `"default"` | Controls the height and padding across all child tabs |

### TabsTab

Individual tab trigger. Styled wrapper for `Tabs.Tab` from Base UI. Also exported as `TabsTrigger`.

| Prop   | Type                        | Default     | Description                                 |
| ------ | --------------------------- | ----------- | ------------------------------------------- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Controls the specific tab trigger dimension |

### TabsPanel

Content panel for each tab. Styled wrapper for `Tabs.Panel` from Base UI. Also exported as `TabsContent`.

### TabsIndicator

Visual indicator for the active tab. Styled wrapper for `Tabs.Indicator` from Base UI.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-tabs-03" description="Tabs with full rounded triggers" />

  <ShowcaseCard name="demo-p-tabs-04" description="Tabs with icon before name" />

  <ShowcaseCard name="demo-p-tabs-05" description="Tabs with icon before name and underline" />

  <ShowcaseCard name="demo-p-tabs-06" description="Tabs with icon only" />

  <ShowcaseCard name="demo-p-tabs-07" description="Tabs with underline and icon on top" />

  <ShowcaseCard name="demo-p-tabs-08" description="Tabs with count badge" />

  <ShowcaseCard name="demo-p-tabs-10" description="Tabs with icon only and count badge" />

  <ShowcaseCard name="demo-p-tabs-11" description="Tabs with icon only and grouped tooltips" />
</ShowcaseGrid>


# Textarea
URL: https://www.spaceui.one/primitives/textarea

***

title: Textarea
description: Allows users to type multi-line text, comments, or long descriptions with support for auto-expanding height as they write.
preview: demo-p-textarea-01
---------------------------

## Installation

<ComponentInstallation name="primitives-textarea" />

## Usage

```tsx
import { Textarea } from '@/components/ui/textarea'
```

```tsx
<Textarea />
```

## Features

### Sizes

Textarea controls in `sm`, `default`, and `lg` sizes.

<ComponentPreview name="demo-p-textarea-02" />

### Disabled

Textarea rendered in a disabled state via the `disabled` prop.

<ComponentPreview name="demo-p-textarea-03" />

### Read Only

Textarea configured in read-only mode via the `readOnly` prop.

<ComponentPreview name="demo-p-textarea-09" />

## Field Integration

Unlike Base UI's built-in form controls, Base UI does not provide a native Textarea primitive. This component wraps the native `<textarea>` element in `Field.Control` internally, so it integrates with `Field` out of the box — no need to wrap it in a `FieldControl` manually.

```tsx
<Field>
  <FieldLabel>Bio</FieldLabel>
  <Textarea placeholder="Tell us about yourself…" />
  <FieldDescription>Write a short bio.</FieldDescription>
  <FieldError>This field is required.</FieldError>
</Field>
```

## API Reference

### Textarea

Styled native textarea element with custom size options.

| Prop       | Type                                  | Default     | Description                                                                            |
| ---------- | ------------------------------------- | ----------- | -------------------------------------------------------------------------------------- |
| `size`     | `"sm" \| "default" \| "lg" \| number` | `"default"` | Controls the textarea padding. Number values are passed to the native `rows` attribute |
| `unstyled` | `boolean`                             | `false`     | When true, removes all default styling                                                 |

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-textarea-04" description="Textarea with label" />

  <ShowcaseCard name="demo-p-textarea-05" description="Textarea in form" />

  <ShowcaseCard name="demo-p-textarea-06" description="Textarea with label and required indicator" />

  <ShowcaseCard name="demo-p-textarea-07" description="Textarea with optional label" />

  <ShowcaseCard name="demo-p-textarea-08" description="Textarea with custom border and background" />

  <ShowcaseCard name="demo-p-textarea-10" description="Textarea with characters remaining counter" />

  <ShowcaseCard name="demo-p-textarea-11" description="Textarea field with required indicator" />

  <ShowcaseCard name="demo-p-textarea-12" description="Shorter textarea with fixed height" />

  <ShowcaseCard name="demo-p-textarea-13" description="Textarea with button aligned right" />

  <ShowcaseCard name="demo-p-textarea-14" description="Textarea with button aligned left" />
</ShowcaseGrid>


# Toast
URL: https://www.spaceui.one/primitives/toast

***

title: Toast
description: Displays temporary popup notifications at the corner of the screen to confirm user actions, show progress, or report background updates.

links:
doc: [https://base-ui.com/react/components/toast#api-reference](https://base-ui.com/react/components/toast#api-reference)
preview: demo-p-toast-01
------------------------

## Installation

<ComponentInstallation name="primitives-toast" />

## Usage

### Stacked Toasts

```tsx
import { toastManager } from '@/components/ui/toast'

toastManager.add({
  title: 'Event has been created',
  description: 'Monday, January 3rd at 6:00pm',
})
```

By default, toasts appear in the **bottom-right** corner. You can change this by setting the `position` prop on the `ToastProvider`.

Allowed values: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`. For example:

```tsx
<ToastProvider position="top-center">{children}</ToastProvider>
```

### Deduplicated toasts (upsert)

Pass a stable `id` when calling `toastManager.add`. If a toast with that `id` already exists, Base UI updates it in place, refreshes the auto-dismiss timer, and increments `updateKey`. The styled toast replays a short re-notify animation on each update.

```tsx
toastManager.add({
  id: 'save-status',
  title: 'Saved',
  description: 'Your draft was updated.',
})
```

<ComponentPreview name="demo-p-toast-06" />

### Anchored Toasts

For toasts positioned relative to a specific element, use `anchoredToastManager`. The `AnchoredToastProvider` is typically added to your app layout (alongside `ToastProvider`), so you can use `anchoredToastManager` directly in your components:

```tsx
anchoredToastManager.add({
  title: 'Copied!',
  positionerProps: {
    anchor: buttonRef.current,
  },
})
```

You can also style anchored toasts like tooltips by passing `data: { tooltipStyle: true }`. When using tooltip style, only the `title` is displayed (description and other content are ignored):

```tsx
anchoredToastManager.add({
  title: 'Copied!',
  positionerProps: {
    anchor: buttonRef.current,
  },
  data: {
    tooltipStyle: true,
  },
})
```

<ComponentPreview name="demo-p-toast-08" />

## API Reference

### ToastProvider

Provider component for stacked toasts. Wraps `Toast.Provider` from Base UI.

| Prop          | Type                                                                                              | Default          | Description                                                                              |
| ------------- | ------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| `position`    | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `"bottom-right"` | Position of the toast viewport                                                           |
| `portalProps` | `Toast.Portal.Props`                                                                              | -                | Props forwarded to the internal portal (`container`, etc.); see Base UI Toast portal API |

### AnchoredToastProvider

Provider component for toasts anchored to specific elements. Use with `anchoredToastManager`.

| Prop          | Type                 | Default | Description                                                                              |
| ------------- | -------------------- | ------- | ---------------------------------------------------------------------------------------- |
| `portalProps` | `Toast.Portal.Props` | -       | Props forwarded to the internal portal (`container`, etc.); see Base UI Toast portal API |

### toastManager

Manager object for creating stacked toasts. Use `toastManager.add()` to show a toast. Pass the same `id` on a later `add` to update that toast in place (dedupe) instead of stacking a duplicate.

### anchoredToastManager

Manager object for creating anchored toasts. Use `anchoredToastManager.add()` with `positionerProps.anchor` to show a toast anchored to an element. Repeated `add` calls with the same `id` update in place, same as stacked toasts.

### ToastViewport

Viewport container for toasts. Styled wrapper for `Toast.Viewport` from Base UI.

### Toast

Individual toast container. Styled wrapper for `Toast.Root` from Base UI.

### ToastTitle

Title text for the toast. Styled wrapper for `Toast.Title` from Base UI.

### ToastDescription

Description text for the toast. Styled wrapper for `Toast.Description` from Base UI.

### ToastAction

Action button for the toast. Styled wrapper for `Toast.Action` from Base UI.

### ToastClose

Close button for the toast. Styled wrapper for `Toast.Close` from Base UI.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-toast-02" description="Stacked toasts with varying content height" />

  <ShowcaseCard name="demo-p-toast-03" description="Anchored tooltip-style toast after copy" />

  <ShowcaseCard name="demo-p-toast-04" description="Anchored error toast after async failure" />

  <ShowcaseCard name="demo-p-toast-05" description="Long-running promise toast with cancel" />

  <ShowcaseCard name="demo-p-toast-06" description="Deduplicated success toast" />

  <ShowcaseCard name="demo-p-toast-07" description="Deduplicated error toast" />

  <ShowcaseCard name="demo-p-toast-08" description="Anchored deduplicated success toast" />

  <ShowcaseCard name="demo-p-toast-09" description="Anchored deduplicated error toast" />
</ShowcaseGrid>


# Toggle Group
URL: https://www.spaceui.one/primitives/toggle-group

***

title: Toggle Group
description: Groups multiple toggleable buttons together so users can select single or multiple options, ideal for text styling toolbars.
preview: demo-p-toggle-group-01
-------------------------------

## Installation

<ComponentInstallation name="primitives-toggle-group" />

## Usage

```tsx
import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group'
```

```tsx
<ToggleGroup>
  <ToggleGroupItem>Bold</ToggleGroupItem>
  <ToggleGroupItem>Italic</ToggleGroupItem>
  <ToggleGroupItem>Underline</ToggleGroupItem>
</ToggleGroup>
```

## Features

### Variants

Toggle groups in `default` and `outline` styles.

<ComponentPreview name="demo-p-toggle-group-01" />

### Sizes

Toggle groups in `sm`, `default`, and `lg` sizes.

<ComponentPreview name="demo-p-toggle-group-02" />

### Vertical Orientation

Toggle group arranged vertically with `orientation="vertical"`.

<ComponentPreview name="demo-p-toggle-group-03" />

### Multiple Selection

Toggle group configured for multiple selection via `multiple`.

<ComponentPreview name="demo-p-toggle-group-06" />

### Disabled State

Toggle group rendered in a disabled state.

<ComponentPreview name="demo-p-toggle-group-04" />

## API Reference

### ToggleGroup

Root component. Styled wrapper for `ToggleGroup.Root` from Base UI. Provides shared variant and size to child toggles via context.

| Prop          | Type                         | Default        | Description                               |
| ------------- | ---------------------------- | -------------- | ----------------------------------------- |
| `variant`     | `"default" \| "outline"`     | `"default"`    | Controls the styling of all child toggles |
| `size`        | `"default" \| "sm" \| "lg"`  | `"default"`    | Controls the size of all child toggles    |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Controls horizontal or vertical layout    |

### ToggleGroupItem

Individual toggle button within the group. Styled wrapper for `Toggle` from Base UI. Inherits variant and size from parent ToggleGroup context.

### ToggleGroupSeparator

Visual separator between toggle buttons.

| Prop          | Type                         | Default      | Description                         |
| ------------- | ---------------------------- | ------------ | ----------------------------------- |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Direction matching the parent group |

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-toggle-group-05" description="Toggle group with disabled item" />

  <ShowcaseCard name="demo-p-toggle-group-07" description="Toggle group with tooltips" />
</ShowcaseGrid>


# Toggle
URL: https://www.spaceui.one/primitives/toggle

***

title: Toggle
description: Provides a two-state button that users can press to turn a specific feature, view, or styling option on and off.

links:
doc: [https://base-ui.com/react/components/toggle#api-reference](https://base-ui.com/react/components/toggle#api-reference)
preview: demo-p-toggle-01
-------------------------

## Installation

<ComponentInstallation name="primitives-toggle" />

## Usage

```tsx
import { Toggle } from '@/components/ui/toggle'
```

```tsx
<Toggle>Toggle</Toggle>
```

## Features

### Variants

Toggle buttons in `default` and `outline` styles.

<ComponentPreview name="demo-p-toggle-01" />

### Sizes

Toggle buttons in `sm`, `default`, and `lg` sizes.

<ComponentPreview name="demo-p-toggle-02" />

### Disabled

Toggle button rendered in a disabled state.

<ComponentPreview name="demo-p-toggle-04" />

## API Reference

### Toggle

Styled wrapper for `Toggle.Root` from Base UI with variant and size options.

| Prop      | Type                        | Default     | Description                 |
| --------- | --------------------------- | ----------- | --------------------------- |
| `variant` | `"default" \| "outline"`    | `"default"` | Controls the toggle styling |
| `size`    | `"default" \| "sm" \| "lg"` | `"default"` | Controls the toggle size    |

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-toggle-03" description="Large toggle" />

  <ShowcaseCard name="demo-p-toggle-05" description="Toggle icon group" />

  <ShowcaseCard name="demo-p-toggle-06" description="Bookmark toggle with tooltip and success toast" />
</ShowcaseGrid>


# Toolbar
URL: https://www.spaceui.one/primitives/toolbar

***

title: Toolbar
description: Arranges formatting tools, action buttons, and dropdown controls into a compact, accessible toolbar for quick editing.

links:
doc: [https://base-ui.com/react/components/toolbar#api-reference](https://base-ui.com/react/components/toolbar#api-reference)
preview: demo-p-toolbar-01
--------------------------

## Installation

<ComponentInstallation name="primitives-toolbar" />

## Usage

```tsx
import { Button } from '@/components/ui/button'
import { Toggle } from '@/components/ui/toggle'
import { Toolbar, ToolbarButton, ToolbarGroup, ToolbarSeparator } from '@/components/ui/toolbar'
```

```tsx
<Toolbar>
  <ToolbarGroup>
    <ToolbarButton render={<Toggle />}>Bold</ToolbarButton>
    <ToolbarButton render={<Toggle />}>Underline</ToolbarButton>
  </ToolbarGroup>
  <ToolbarSeparator />
  <ToolbarButton render={<Button />}>Save</ToolbarButton>
</Toolbar>
```

## API Reference

### Toolbar

Root component. Styled wrapper for `Toolbar.Root` from Base UI with flex layout.

### ToolbarGroup

Groups related toolbar items. Styled wrapper for `Toolbar.Group` from Base UI.

### ToolbarButton

Button within the toolbar. Alias for `Toolbar.Button` from Base UI. Use with `render` prop to render as Toggle or Button.

### ToolbarSeparator

Visual separator between toolbar items. Styled wrapper for `Toolbar.Separator` from Base UI.

### ToolbarLink

Link within the toolbar. Alias for `Toolbar.Link` from Base UI.

### ToolbarInput

Input element styled for inclusion inside the toolbar. Alias for `Toolbar.Input` from Base UI.


# Tooltip
URL: https://www.spaceui.one/primitives/tooltip

***

title: Tooltip
description: Displays a small floating text bubble when users hover over or focus on an element, explaining what that button or icon does.

links:
doc: [https://base-ui.com/react/components/tooltip#api-reference](https://base-ui.com/react/components/tooltip#api-reference)
preview: demo-p-tooltip-01
--------------------------

## Installation

<ComponentInstallation name="primitives-tooltip" />

## Usage

```tsx
import { Tooltip, TooltipCreateHandle, TooltipPopup, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'
```

```tsx
<Tooltip>
  <TooltipTrigger render={<Button variant="outline" />}>Hover me</TooltipTrigger>
  <TooltipPopup>Helpful hint</TooltipPopup>
</Tooltip>
```

## Anatomy

```tsx
<Tooltip>
  <TooltipTrigger />
  <TooltipPopup />
</Tooltip>
```

## Accessibility

* Follows the [WAI-ARIA Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/).
* Appears on hover and focus without stealing focus from the trigger.

### Keyboard Interactions

| Key               | Action                                     |
| :---------------- | :----------------------------------------- |
| <Kbd>Escape</Kbd> | Immediately dismisses the visible tooltip. |

## API Reference

### Tooltip

Root component. Alias for `Tooltip.Root` from Base UI.

### TooltipTrigger

Trigger element that shows the tooltip on hover/focus. Alias for `Tooltip.Trigger` from Base UI.

### TooltipPopup

Popup container that displays the tooltip content. Also exported as `TooltipContent`.

| Prop          | Type                                          | Default    | Description                                                                                               |
| ------------- | --------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------- |
| `side`        | `"top" \| "bottom" \| "left" \| "right"`      | `"top"`    | Side of the trigger to position the tooltip                                                               |
| `align`       | `"start" \| "center" \| "end"`                | `"center"` | Alignment relative to the trigger                                                                         |
| `sideOffset`  | `number`                                      | `4`        | Distance from the trigger in pixels                                                                       |
| `anchor`      | `Element \| null \| React.RefObject<Element>` | -          | Custom anchor element or ref to anchor the tooltip against                                                |
| `portalProps` | `Tooltip.Portal.Props`                        | -          | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Tooltip portal API |

### TooltipProvider

Provider for grouping tooltips. Alias for `Tooltip.Provider` from Base UI.

### TooltipCreateHandle

Creates a handle for detached tooltip triggers. Returns a handle object to attach to multiple triggers for animated transitions.

## Examples

<ShowcaseGrid showLayoutToggle={false} columns={1}>
  <ShowcaseCard name="demo-p-tooltip-02" description="Grouped tooltips" />

  <ShowcaseCard name="demo-p-tooltip-03" description="Toggle group animated tooltip" />

  <ShowcaseCard name="demo-p-tooltip-04" description="Vertical group with animated tooltip" />
</ShowcaseGrid>


# AI Chat Workspace
URL: https://www.spaceui.one/templates/ai-chat-workspace

***

title: AI Chat Workspace
description: Full-featured AI Studio chat workspace template featuring conversational threads, multi-model selection, real-time token tracking, reasoning trace, code execution viewer, and a sleek dark mode interface.
isPro: true
preview:
name: template-ai-chat-workspace
iframe: true
------------

## Installation

<ComponentInstallation name="template-ai-chat-workspace" />

## Overview

The **AI Chat Workspace** template is an end-to-end interface designed for conversational AI and reasoning studio workflows:

* **Sidebar Navigation**: Collapsible left sidebar containing recent threads, project folders, token counters, and account menu.
* **Model Switcher**: Dynamic selector for state-of-the-art LLMs (GPT-4o, Claude 3.5 Sonnet, Gemini 1.5 Pro) with latency, token limits, and capability tags.
* **Message Stream & Reasoning**: Markdown-rendered responses with reasoning steps, code syntax highlighting, copy action, and feedback controls.
* **Multimodal Composer**: Expandable prompt input with web search toggling, prompt attachments, token usage estimators, and keyboard shortcuts.


# Ashura
URL: https://www.spaceui.one/templates/ashura

***

title: 'Ashura'
description: 'Ashura is a conceptual branding and communication agency that uses AI as a strategic vector for sharper brand platforms and campaign systems.'
isPro: true
preview:
name: showcase-ashura
iframe: true
open: true
showcase: true
externalUrl: '[https://ashura-landing.adrielzimbril.com](https://ashura-landing.adrielzimbril.com)'
createdAt: '2026-05-14'
updatedAt: '2026-09-06'
-----------------------


# Aura Robotics
URL: https://www.spaceui.one/templates/aura

***

title: 'Aura Robotics'
description: 'Aura Robotics is a conceptual humanoid AGI robot that bridges the gap between digital cognition and physical actuation.'
preview:
name: showcase-aura
iframe: true
open: true
showcase: true
externalUrl: '[https://aura-landing.adrielzimbril.com](https://aura-landing.adrielzimbril.com)'
createdAt: '2026-05-11'
updatedAt: '2026-09-06'
-----------------------


# CineMax
URL: https://www.spaceui.one/templates/cinemax

***

title: 'CineMax'
description: 'Cinemax is a conceptual premium anime presentation platform that turns legendary titles into widescreen cinematic reels.'
preview:
name: showcase-cinemax
iframe: true
open: true
showcase: true
externalUrl: '[https://cinemax-landing.adrielzimbril.com](https://cinemax-landing.adrielzimbril.com)'
createdAt: '2026-05-21'
updatedAt: '2026-09-06'
-----------------------


# Cosmos AI
URL: https://www.spaceui.one/templates/cosmos-ai

***

title: 'Cosmos AI'
description: 'Cosmos AI is a conceptual cinematic AI image generation platform mockup.'
preview:
name: showcase-cosmos-ai
iframe: true
open: true
showcase: true
externalUrl: '[https://cosmos-ai-landing.adrielzimbril.com](https://cosmos-ai-landing.adrielzimbril.com)'
createdAt: '2026-05-02'
updatedAt: '2026-09-06'
-----------------------


# Somey Amegnibo
URL: https://www.spaceui.one/templates/folio

***

title: 'Somey Amegnibo'
description: 'Folio Landing is a conceptual creative director portfolio that presents public campaigns, art direction, and visual identity work for memorable brands.'
isPro: true
preview:
name: showcase-folio
iframe: true
open: true
showcase: true
externalUrl: '[https://folio-landing.adrielzimbril.com](https://folio-landing.adrielzimbril.com)'
createdAt: '2026-05-13'
updatedAt: '2026-09-06'
-----------------------


# Forger
URL: https://www.spaceui.one/templates/forger

***

title: 'Forger'
description: 'Forger is a conceptual recruitment platform that sources candidates and secures the perfect match with precision.'
preview:
name: showcase-forger
iframe: true
open: true
showcase: true
externalUrl: '[https://forger-landing.adrielzimbril.com](https://forger-landing.adrielzimbril.com)'
createdAt: '2026-05-08'
updatedAt: '2026-09-06'
-----------------------


# Framey
URL: https://www.spaceui.one/templates/framey

***

title: 'Framey'
description: 'Framey is a conceptual AI website builder that turns prompts into production-ready landing pages.'
preview:
name: showcase-framey
iframe: true
open: true
showcase: true
externalUrl: '[https://framey-landing.adrielzimbril.com](https://framey-landing.adrielzimbril.com)'
createdAt: '2026-05-03'
updatedAt: '2026-09-06'
-----------------------


# Haumea
URL: https://www.spaceui.one/templates/haumea

***

title: 'Haumea'
description: "Haumea is a conceptual somatic renewal and circadian intelligence platform that aligns your body's biology with natural rhythms."
isPro: true
preview:
name: showcase-haumea
iframe: true
open: true
showcase: true
externalUrl: '[https://haumea-landing.adrielzimbril.com](https://haumea-landing.adrielzimbril.com)'
createdAt: '2026-05-18'
updatedAt: '2026-09-06'
-----------------------


# Immersive Lens Portfolio
URL: https://www.spaceui.one/templates/immersive-lens

***

title: Immersive Lens Portfolio
description: Full-page immersive photography template with Three.js WebGL distortion shaders, horizontal & vertical gallery views, and animated GSAP lightbox.
preview:
name: template-immersive-lens
iframe: true
------------

## Installation

<ComponentInstallation name="template-immersive-lens" />

## Key Features

* **Next.js App Router Architecture**: Clean separation between Server Component metadata/SSR and interactive Client Islands.
* **Decoupled Hooks**: `useCustomCursor`, `useHorizontalDrag`, and `useLightbox` are standalone and reusable.
* **Full-Screen Immersion**: Locked to split view with full viewport immersion shortcut (`F` / `Esc`).
* **WebGL Shader Layer**: Fluid Three.js distortion on scroll velocity and hover interactions.
* **Curated High-Resolution Imagery**: Preconfigured with curated photography assets and optimal aspect ratios.
* **Glassmorphism HUD**: Translucent blurred floating dock with category switching, layout mode toggling, and progress counters.


# Templates
URL: https://www.spaceui.one/templates

***

title: Templates
description: Full-page immersive starters you install and own.
--------------------------------------------------------------


# Marveen
URL: https://www.spaceui.one/templates/marveen

***

title: 'Marveen'
description: 'Marveen is a conceptual premium holistic wellness sanctuary that connects seekers with high-end, immersive, and transformative zen/mindfulness retreats around the globe.'
isPro: true
preview:
name: showcase-marveen
iframe: true
open: true
showcase: true
externalUrl: '[https://marveen-landing.adrielzimbril.com](https://marveen-landing.adrielzimbril.com)'
createdAt: '2026-05-21'
updatedAt: '2026-09-06'
-----------------------


# Netra
URL: https://www.spaceui.one/templates/netra

***

title: 'Netra'
description: 'Netra is a conceptual bio data center intelligence platform that orchestrates low-carbon compute with living thermal systems and real-time facility autonomy.'
preview:
name: showcase-netra
iframe: true
open: true
showcase: true
externalUrl: '[https://netra-landing.adrielzimbril.com](https://netra-landing.adrielzimbril.com)'
createdAt: '2026-05-09'
updatedAt: '2026-09-06'
-----------------------


# Oleap
URL: https://www.spaceui.one/templates/oleap

***

title: 'Oleap'
description: 'Oleap is a conceptual AI customer support platform that closes the support feedback loop.'
preview:
name: showcase-oleap
iframe: true
open: true
showcase: true
externalUrl: '[https://oleap-landing.adrielzimbril.com](https://oleap-landing.adrielzimbril.com)'
createdAt: '2026-05-16'
updatedAt: '2026-09-06'
-----------------------


# One Piece Landing
URL: https://www.spaceui.one/templates/one-piece

***

title: 'One Piece Landing'
description: "One Piece Landing is a conceptual anime pirate crew showcase that turns the Straw Hat crew, Luffy's gears, bounties, audio, and cinematic motion into an immersive fan landing page."
preview:
name: showcase-one-piece
iframe: true
open: true
showcase: true
externalUrl: '[https://one-piece-landing.adrielzimbril.com](https://one-piece-landing.adrielzimbril.com)'
createdAt: '2026-05-19'
updatedAt: '2026-09-06'
-----------------------


# Rival
URL: https://www.spaceui.one/templates/rival

***

title: 'Rival'
description: 'Rival is a conceptual digital bank that simplifies global wealth management with high-yield savings and instant cross-border transfers.'
preview:
name: showcase-rival
iframe: true
open: true
showcase: true
externalUrl: '[https://rival-landing.adrielzimbril.com](https://rival-landing.adrielzimbril.com)'
createdAt: '2026-05-06'
updatedAt: '2026-09-06'
-----------------------


# Rocoon
URL: https://www.spaceui.one/templates/rocoon

***

title: 'Rocoon'
description: 'Rocoon is a conceptual AI architecture agency that designs modern smart homes with predictive planning, generative concepts, and connected build intelligence.'
preview:
name: showcase-rocoon
iframe: true
open: true
showcase: true
externalUrl: '[https://rocoon-landing.adrielzimbril.com](https://rocoon-landing.adrielzimbril.com)'
createdAt: '2026-05-17'
updatedAt: '2026-09-06'
-----------------------


# Staria
URL: https://www.spaceui.one/templates/staria

***

title: 'Staria'
description: 'Staria is a conceptual AI social media content generator that transforms ideas into viral posts.'
preview:
name: showcase-staria
iframe: true
open: true
showcase: true
externalUrl: '[https://staria-landing.adrielzimbril.com](https://staria-landing.adrielzimbril.com)'
createdAt: '2026-05-07'
updatedAt: '2026-09-06'
-----------------------


# Stats Dashboard
URL: https://www.spaceui.one/templates/stats

***

title: Stats Dashboard
description: Comprehensive portfolio statistics and analytics template featuring KPI cards, GitHub activity heatmap, publication analytics, Lighthouse benchmarks, and reader engagement.
isPro: true
preview:
name: template-stats
iframe: true
------------

## Installation

<ComponentInstallation name="template-stats" />

## Overview

The **Stats Dashboard** template gathers 5 modular statistics blocks into a cohesive portfolio analytics dashboard:

1. **General Metrics (`block-stats-general`)**: High-level KPI overview (Total Views, Coffee Consumed, Site Age).
2. **Reader Engagement (`block-stats-engagement`)**: Audience metrics (Most Viewed & Reacted Content, Emoji Reactions, Topic Tags, Changelog Milestones).
3. **Publication & Content (`block-stats-blog`)**: Authoring analytics (Total Articles, Word Counts, Community Messages, Estimated Reading Time).
4. **GitHub Activity (`block-stats-github`)**: Open-source momentum (Stars, Forks, Commits, 52-Week Contribution Matrix).
5. **Performance Benchmarks (`block-stats-performance`)**: Synthetic Lighthouse audits (Mobile & Desktop Scores with Radar Backgrounds and Progress Bars).


# Sunabase
URL: https://www.spaceui.one/templates/sunabase

***

title: 'Sunabase'
description: 'Sunabase is a conceptual high-performance database backend infrastructure mockup.'
preview:
name: showcase-sunabase
iframe: true
open: true
showcase: true
externalUrl: '[https://sunabase-landing.adrielzimbril.com](https://sunabase-landing.adrielzimbril.com)'
createdAt: '2026-05-16'
updatedAt: '2026-09-06'
-----------------------


# Tera
URL: https://www.spaceui.one/templates/tera

***

title: 'Tera'
description: 'Tera is a conceptual architecture studio that specializes in brutalist, climate-positive structures.'
preview:
name: showcase-tera
iframe: true
open: true
showcase: true
externalUrl: '[https://tera-landing.adrielzimbril.com](https://tera-landing.adrielzimbril.com)'
createdAt: '2026-05-05'
updatedAt: '2026-09-06'
-----------------------


# Twelve AI
URL: https://www.spaceui.one/templates/twelve-ai

***

title: 'Twelve AI'
description: 'Twelve AI is a conceptual AI image generation workspace that turns campaign prompts into coherent brand-safe visual systems.'
preview:
name: showcase-twelve-ai
iframe: true
open: true
showcase: true
externalUrl: '[https://twelve-ai-landing.adrielzimbril.com](https://twelve-ai-landing.adrielzimbril.com)'
createdAt: '2026-05-03'
updatedAt: '2026-09-06'
-----------------------


# ZeusX
URL: https://www.spaceui.one/templates/zeusx

***

title: 'ZeusX'
description: 'ZeusX is a conceptual high-performance web platform that delivers exceptional speed and modern digital experiences.'
preview:
name: showcase-zeusx
iframe: true
open: true
showcase: true
externalUrl: '[https://zeusx-landing.adrielzimbril.com](https://zeusx-landing.adrielzimbril.com)'
createdAt: '2026-05-12'
updatedAt: '2026-09-06'
-----------------------


# Tools
URL: https://www.spaceui.one/tools

***

title: Tools
description: Explore tools, animated icons and design assets.
-------------------------------------------------------------

# Tools

Welcome to Space UI Tools.