How to use

Basic usage

Every Satisium UI component is a standard React component. Import it, pass props, and render it.

Props

Each component documents its props in a table on its doc page. Common props across the library:

See the Components index for full prop tables.

Styling & theming

Override with className

All components accept className. Use it to adjust sizing, spacing, or colors:

Design tokens

Satisium UI uses OKLCH-based CSS variables for perceptual color uniformity. Override them in your globals.css:

Dark mode

Dark mode works automatically with the Satisium UI theme system. Press D from anywhere on the site to toggle between light and dark themes. In your own project, use next-themes or wrap your app in the ThemeProvider component.

Preview before installing

You don't have to install a component to see how it works. Every component has a fullscreen preview:

• /preview/<registryKey> — Fullscreen, isolated render with the playground UI.
• /embed/<registryKey> — Iframe-isolated render for responsive testing.

Use these URLs to test components in a clean environment before adding them to your project.

Browsing components

The easiest way to discover components is the Components index. It lists every available component grouped by category, with a preview image, description, and status badge.

• All components — /docs/components shows every component in the library, organized by category.
• Category pages — Click a category badge on any component doc, or visit /categories to browse by type (Text Reveals, Image Effects, Carousels, Mouse Trails).
• Component cards — Each card shows a preview thumbnail, title, description, and optional badge. Click any card to open its full documentation page with live preview, props table, and install command.

Docs site features

Spatial layout sidebar

The docs site uses an animated spatial layout. Press M to toggle the sidebar open and closed. Click anywhere on the dimmed overlay to close it.

Live playground

Every component doc page includes a resizable playground with a floating toolbox in the bottom-left corner.

Viewport controls: The toolbar shows desktop, tablet, and mobile icons. Click them to resize the preview, or use the keyboard shortcuts below.

Keyboard shortcuts for the previewer:

Resizing: Drag the vertical divider between the preview and the code panel to adjust the width manually. This switches the viewport mode to "custom."

Switching demos: Components with multiple variants (e.g., velocity-strips-image and velocity-strips-video) include a demo selector dropdown in the preview toolbox. Select any variant to instantly switch the live preview and the install command shown in the code panel.

Code panel: When the code panel is open, you can browse the component source files in the sidebar tree and copy individual files. The install command at the top updates automatically when you switch demos.

Code & copy

• CodeBlock — Syntax-highlighted source with a file tree sidebar and line highlighting.
• Copy MDX — Button in the top-right of every doc page copies the entire MDX file content to your clipboard. Paste it directly into your project.

Command menu

Press Cmd+K (or Ctrl+K, or /) to open the global search:

• Search docs, categories, and components.
• Jump to recently visited pages.
• Shift+Enter — Copy the current page URL.
• Cmd+Enter (or **Ctrl+Enter) — Open the selected result in a new tab.
• Select Light Theme or Dark Theme from the Theme section to switch modes.

Component badges

Component cards on the index and category pages may include a small colored dot to indicate status:

Global keyboard shortcuts

These work anywhere on the docs site:

Blocks & templates

Beyond individual components, the library will include:

• Blocks (/docs/blocks) — Reusable patterns built from multiple components.
• Templates (/docs/templates) — Complete page layouts you can drop into your Next.js app.

Both sections are marked as coming soon.

WebGL & performance

Components using Three.js are wrapped in Suspense boundaries. Always provide a fallback prop for the loading state:

This prevents layout shift and keeps your Core Web Vitals healthy.

Removing a component

Since Satisium UI copies source code into your project, uninstalling is simple:

1. Delete the component file(s) from components/satisium-ui/.
2. Delete the demo file if you added it.
3. Remove any registry references if you added them.

There is no runtime package to uninstall and no lock-in.

Next steps

• Browse Components and install your first one.
• Check the Changelog for the latest additions.