` with an accessible name (the person's name), so it is announced and operable independent of hover.
* `aria-expanded` and `aria-controls` let assistive technology track which card is associated with which trigger and whether it is currently open.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the popover appears and disappears with an instant opacity change only — no scale and no slide.
## Props [#props]
# Interactive Image Selector (/docs/components/interactive-image-selector)
## Features [#features]
* Toggle selection with keyboard and pointer
* Animated selection ring and scales
* Custom renderers and captions
* Responsive grid
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| ------------ | -------------------- | ------------------------------------------ |
| `aria-label` | Reset button | Provides accessible name "Reset selection" |
| `aria-label` | Select/Cancel button | Dynamically describes current action |
### Screen Reader [#screen-reader]
* Each gallery image has an `alt` attribute (e.g., "Gallery item 1").
* The selection count is displayed as visible text in the action bar.
* The Share and Delete buttons use icon-only presentation without accessible labels.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, shake and slide-in animations are disabled.
## Props [#props]
# Job Listing Component (/docs/components/job-listing-component)
## Features [#features]
* Animated card entrance and hover
* Filter/tags friendly layout
* Accessible focus states
* Responsive grid/list views
## Accessibility [#accessibility]
### Keyboard Interactions [#keyboard-interactions]
| Key | Description |
| -------- | -------------------------------------- |
| `Escape` | Closes the expanded job detail overlay |
### Screen Reader [#screen-reader]
* Job cards use layout animations via `layoutId` for smooth shared element transitions.
* The expanded detail view uses a click-outside handler to dismiss, and `Escape` key support for keyboard users.
* SVG logo icons (Resend, Turso, Supabase) include `title` elements for screen reader identification.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, layout animations and `layoutId` transitions are disabled, backdrop opacity animations are instant, and tap scale effects are removed.
## Props [#props]
# Kinetic Center Build (/docs/components/kinetic-center-build)
## Features [#features]
* Word-by-word build with right-to-left entry and push reflow
* Layout-animated centering as words are added
* Soft blur entry and clean blur exit per word
* Respects `prefers-reduced-motion`
* Announces updates via `aria-live="polite"`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the full phrase appears at once and swaps instantly. The current phrase is announced via `aria-live="polite"`.
## Props [#props]
# Kinetic Type Scroll (/docs/components/kinetic-type-scroll)
## Features [#features]
* Each word maps its own slice of scroll progress to a scale, lift, opacity, tracking (letter-spacing) and weight curve
* Windows overlap and the wave is centred in the range with head- and tail-room, so the crest travels through the phrase while it is parked in view rather than as it leaves
* Curves are smoothed with `useSpring` so the phrase reads as a continuous wave rather than a snap
* Configurable `scaleRange`, `liftRange`, `dimRange`, `trackingRange`, `weightRange`, `stagger`, and Motion `offset` (defaults to `["start 0.9", "end 0.45"]`)
* Must be driven by a scrollable container, passed via the `container` ref — give that container `position: relative` so Motion can resolve the target's offsets against it
* Respects `prefers-reduced-motion` by rendering the phrase statically at its peak weight
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | --------------- | ---------------------------------------------------- |
| `aria-label` | Wrapper element | Exposes the full phrase once to assistive technology |
| `aria-hidden="true"` | Per-word spans | Hides the animated words from screen readers |
### Screen Reader [#screen-reader]
* The wrapper carries `aria-label={words.join(" ")}`, announcing the full phrase as one string.
* Each word span underneath is `aria-hidden`, so the scroll-driven fragments are never read individually.
* The text remains selectable in the DOM at all times.
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, every word renders statically at the top of `weightRange` with no scale, no lift and no dimming — the phrase simply reads at full strength, with no scroll listeners and no springs.
## Props [#props]
The `container` element needs a **definite height** — `h-[440px]`, `h-dvh`, a
grid track — plus `overflow-y-auto`. A percentage height like `h-full` resolves
to `auto` against a content-sized parent, so the container grows to fit the
phrase and never scrolls, leaving every word parked at the low end of its
range. Give the phrase roughly 2.5–3× the container's height of content to
travel through, and place it high enough to be legible at rest — a phrase
centred inside a very tall spacer starts below the fold, which reads as an
empty box rather than as something waiting to be scrolled.
`weightRange` only produces a visible effect when the active font is a
variable font that exposes the `wght` axis. On static fonts,
`font-variation-settings` is applied but has no effect. The font on this site
(Inter) is variable, so the weight axis is live in the demo above.
# Line-by-Line Slide (/docs/components/line-by-line-slide)
## Features [#features]
* Per-line slide-in from the left with staggered entrance (`cubic-bezier(0.22, 1, 0.36, 1)`)
* Pass lines via `children` string with `\n` separators or the explicit `lines` prop
* Configurable delay and per-line stagger
* Optional scroll-trigger via `triggerOnView`
* Accessible: respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the text renders immediately at full opacity with no sliding motion. The full string is exposed to screen readers via `aria-label`, with the per-line spans `aria-hidden`.
## Props [#props]
# Liquid Metal (/docs/components/liquid-metal)
## Features [#features]
* Real-time WebGL2 fragment shader: fractal Brownian motion → domain warp → fake reflective normals
* Four palettes: `chrome`, `gold`, `mercury` and `oil` (iridescent)
* Pointer pushes the flow field, eased frame by frame so it never snaps
* `maskText` clips the material to your type via `background-clip: text`
* `speed`, `distortion` and `paused` are live — changing them never rebuilds the GL context
* Rendering pauses automatically when the surface scrolls out of view
* Device pixel ratio aware (capped at 2×) with `WEBGL_lose_context` teardown on unmount
* Graceful fallback to a static CSS conic gradient in the same palette when WebGL2 is unavailable
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | ------------------ | -------------------------------------------------------------- |
| `aria-hidden="true"` | Shader canvas | Hides the decorative metal surface from assistive technologies |
| `aria-hidden="true"` | CSS fallback layer | Hides the static gradient stand-in from assistive technologies |
### Screen Reader [#screen-reader]
* The canvas (and its CSS fallback) carry no semantics and are marked `aria-hidden`, so screen readers only announce the `children` you pass.
* In `maskText` mode the text stays real text in the DOM — it is painted through a clipped background, never rasterised — so it remains selectable, searchable and announced normally.
* Make sure content layered over the surface keeps sufficient contrast; the shader is decorative and should never be the only carrier of meaning.
### Reduced Motion [#reduced-motion]
This component respects `prefers-reduced-motion` via `useReducedMotion` from Motion. When reduced motion is preferred, no WebGL context is created at all: the box renders the static CSS conic gradient, `maskText` renders a fixed gradient with no sweep, and no `requestAnimationFrame` loop is started. The same happens when the element leaves the viewport or when `paused` is set.
## Props [#props]
### Variants [#variants]
| Variant | Look |
| --------- | ----------------------------------------------------------- |
| `chrome` | Cool polished steel with hard specular highlights (default) |
| `gold` | Warm brushed gold with deep amber shadows |
| `mercury` | High-contrast silver, closest to a mirror |
| `oil` | Iridescent oil-slick sheen driven by a cosine palette |
# Mac Terminal (/docs/components/mac-terminal)
## Features [#features]
* Scripted session of commands, outputs, errors, successes, and comments
* Realistic character-by-character typing with a blinking caret
* Auto-scrolls to the newest line as the session plays
* Starts only when the terminal scrolls into view (`IntersectionObserver`) and pauses automatically when the browser tab is hidden
* Optional looping playback with a pause between runs
* `dark`, `light`, or `auto` (system-aware) themes
* Traffic-light buttons become real, labelled controls when `onClose` or `onMinimize` are provided
* Selectable output rendered inside a `` element
* Full accessible transcript available to screen readers immediately, independent of the typing animation
* Respects `prefers-reduced-motion` by rendering the full session instantly
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| ---------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------- |
| `aria-label="{title} terminal"` | Root container | Identifies the widget for assistive technology |
| `role="group"` | Root container | Default role when the session plays automatically |
| `role="button"` / `tabIndex={0}` | Root container | Applied only when `autoPlay` is `false`, so the session can be started by keyboard or pointer |
| `aria-hidden="true"` | Visual `` log | Hides the animated, partially-typed transcript from assistive technology while it plays |
| `aria-live="off"` | Screen-reader transcript | Exposes the complete, final transcript at once instead of announcing it character by character |
| `aria-hidden="true"` | Traffic lights | Applied when neither `onClose` nor `onMinimize` are supplied, marking the lights as purely decorative |
| `aria-label="Close terminal"` / `aria-label="Minimize terminal"` | Traffic-light buttons | Present only when the matching handler is supplied, turning the light into a real control |
### Keyboard [#keyboard]
| Key | Action |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `Tab` | Moves focus to the terminal when `autoPlay` is `false` and the session has not started, or to a traffic-light button when handlers are provided |
| `Enter` / `Space` | Starts the scripted session when the terminal itself is focused and `autoPlay` is `false` |
### Screen Reader [#screen-reader]
* While the session animates, the visible `` is marked `aria-hidden` so partially-typed text is never announced mid-keystroke.
* A second, visually hidden block holds the complete transcript with `aria-live="off"`, so screen reader users can read the full session immediately rather than waiting for the typing animation to finish.
* Traffic lights without handlers are `aria-hidden`; when `onClose` or `onMinimize` are supplied they become focusable buttons with descriptive labels.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, every line renders instantly and in full, there is no character-by-character typing, no caret blink animation, and the screen-reader-only duplicate transcript is skipped since the visible log already contains the complete text.
## Props [#props]
# Magnetic Button (/docs/components/magnetic-button)
## Features [#features]
* Cursor-following magnetic effect
* Configurable strength and activation radius
* Spring physics for natural movement
* Respects reduced motion preferences
* Touch device detection (effect disabled on touch)
* Disabled state support
* Polymorphic with `asChild` prop
* GPU-accelerated transforms
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| --------------------- | ----------- | ---------------------------------------------------------------------------- |
| `role="presentation"` | Wrapper div | Indicates the outer mouse-tracking wrapper is decorative and not interactive |
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the magnetic cursor-following effect is completely disabled. The component also detects hover-capable devices and disables the effect on touch devices. When the `disabled` prop is set, the magnetic effect is also disabled.
## Props [#props]
## Usage [#usage]
```tsx
import MagneticButton from "@/components/magnetic-button";
export default function Example() {
return (
Hover near me
);
}
```
## Examples [#examples]
### Default [#default]
```tsx
Click me
```
### Custom Strength [#custom-strength]
Increase the magnetic pull strength (0-1):
```tsx
Strong magnetic effect
```
### Custom Radius [#custom-radius]
Adjust the activation radius in pixels:
```tsx
Large activation area
```
### Custom Spring Config [#custom-spring-config]
Fine-tune the spring animation:
```tsx
Bouncy
```
### As Child (Polymorphic) [#as-child-polymorphic]
Use with any component using `asChild`:
```tsx
Go to Docs
```
# Magnetic Field (/docs/components/magnetic-field)
## Features [#features]
* Attach `data-magnetic` to any children to make them participate, or pass a
data-driven `items` array
* Three modes: `"attract"` (pulls toward the pointer), `"repel"` (pushes
away), and `"orbit"` (adds a tangential pull for circular motion)
* Optional `rotate` — items tilt toward the pointer within a clamped range
* One shared `rAF` loop drives a manual spring integrator (`stiffness` /
`damping`) per item — no React state per frame, no per-item listeners
* Rest positions are measured once via `ResizeObserver` (and on window
resize), not recomputed on every frame
* `paused` freezes the field; pointer/reduced-motion/touch users get items
at rest with zero listeners attached
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| *(none added)* | Container | The wrapper adds no ARIA role — it is purely a visual transform layer, so participating elements keep whatever semantics they already have |
### Screen Reader [#screen-reader]
* Only `transform` (translate + rotate) is applied to participants — layout,
focus order, and hit-testing are untouched, so keyboard and screen reader
navigation behave exactly as if `MagneticField` were a plain wrapper.
* Interactive participants (buttons, links) remain fully focusable and
operable regardless of their current visual offset.
### Reduced Motion [#reduced-motion]
When `prefers-reduced-motion` is set, or on touch/coarse-pointer devices
(detected via `matchMedia("(hover: hover) and (pointer: fine)")`), or while
`paused` is `true`, no pointer listeners are attached, the `rAF` loop never
starts, and every participant sits at its natural rest position.
## Props [#props]
# Mask Reveal Up (/docs/components/mask-reveal-up)
## Features [#features]
* Per-line masked reveal with upward drift and soft blur (`cubic-bezier(0.22, 1, 0.36, 1)`)
* Overflow-hidden mask per line for a clean reveal effect
* Pass lines via `children` string with `\n` separators or the explicit `lines` prop
* Configurable delay and per-line stagger
* Optional scroll-trigger via `triggerOnView`
* Accessible: respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the text renders immediately at full opacity with no movement. The full string is exposed to screen readers via `aria-label`, with the per-line spans `aria-hidden`.
## Props [#props]
# Micro Scale Fade (/docs/components/micro-scale-fade)
## Features [#features]
* Whole-text scale fade from 0.96 to 1 with opacity (`cubic-bezier(0.32, 0.72, 0, 1)`)
* Calm micro-animation — not distracting
* Configurable delay
* Optional scroll-trigger via `triggerOnView`
* Accessible: respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the text renders immediately at full opacity with no scaling. The `aria-label` on the wrapper ensures screen readers get the full text.
## Props [#props]
# Morph Icon (/docs/components/morph-icon)
## Features [#features]
Eight ready-made morphs driven by a single `active` boolean. Geometry attributes animate directly — no path-morph library. Size, stroke, color, and duration are tunable; pass `label` when the icon should be announced.
## Variants [#variants]
Click the icon in the panel to flip `active`.
### Sidebar [#sidebar]
Collapsed and expanded rail.
### List [#list]
Stacked lines that open into a list.
### Grid [#grid]
Cells that rearrange into a grid.
### Compact [#compact]
Dense layout cue.
### Menu [#menu]
Hamburger that opens.
### Search [#search]
Magnifier that settles into place.
### Play [#play]
Play / pause morph.
### Check [#check]
Empty mark that draws a check.
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | ------------- | -------------------------------------------------------------------------------------------- |
| `aria-hidden="true"` | `` | Applied when no `label` is passed, hiding a purely decorative icon from assistive technology |
| `role="img"` | `` | Applied when `label` is passed, exposing the icon as a single accessible image |
| `` | `` child | Provides the accessible name for the icon when `label` is passed |
### Keyboard Interactions [#keyboard-interactions]
This component renders a static graphic with no interactive elements of its own; it has no keyboard interactions. Wrap it in a `` or other interactive element to make it actionable, and drive the `active` prop from that element's state.
### Screen Reader [#screen-reader]
* Without a `label`, the icon is `aria-hidden` and is skipped entirely by screen readers — pair it with visible or accessible text on its container.
* With a `label`, the icon is announced as an image with that label as its accessible name.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, all geometry transitions snap instantly between states with `duration: 0`.
## Props [#props]
# Morph Surface (/docs/components/morph-surface)
## Features [#features]
* A compact dock that expands into a feedback panel in place
* Spring layout transition on width, height and radius together
* Success state before it returns to the dock
* Click-outside and `Escape` both close it
* `Cmd + Enter` submits
## Growing in place [#growing-in-place]
Nothing is torn down and rebuilt: the dock and the panel are the same surface, and
the layout spring interpolates between the two shapes. That is what separates it
from a button that opens a modal — the control the user pressed is the thing that
became the form, so there is no moment of wondering where the dock went.
Because it grows from its own position, keep it out of layouts that would clip the
expanded panel.
## Renamed from `ai-input` [#renamed-from-ai-input]
This component used to be called `ai-input`, which was wrong twice over: it is not
an input, and it has nothing to do with AI. Its default export has always been
`MorphSurface`.
The old name still resolves for one release, so existing installs keep working. If
you are looking for a chat composer, that is
[AI Prompt Input](/docs/components/ai-prompt-input).
```tsx
// Before
import { MorphSurface } from "@/components/smoothui/ai-input";
// Now
import MorphSurface from "@/components/smoothui/morph-surface";
```
## Accessibility [#accessibility]
### Keyboard Interactions [#keyboard-interactions]
| Key | Description |
| ------------- | ---------------------------------------------------- |
| `Escape` | Closes the feedback textarea and returns to the dock |
| `Cmd + Enter` | Submits the feedback form |
### Screen Reader [#screen-reader]
The submit shortcut is shown with `` elements, so the key combination is
readable rather than implied by an icon.
### Reduced Motion [#reduced-motion]
Respects `prefers-reduced-motion` via `useReducedMotion`. When reduced motion is
preferred, the morph, fade and layout animations are all disabled — the panel
simply appears at its final size.
# Morph Toggle (/docs/components/morph-toggle)
## Features [#features]
A toggle switch with spring motion, controlled or uncontrolled, three sizes, and full keyboard access. Pick a variant below — the panel beside this column shows that one alone.
## Variants [#variants]
### Default [#default]
A smooth sliding thumb. The usual on/off control.
### Morph [#morph]
The thumb changes shape while it travels — `borderRadius` animates with the position.
### Icon [#icon]
Crossfades and scales between custom icons. Pass `icons={{ on, off }}`.
## Sizes [#sizes]
`sm`, `md`, and `lg` scale the track and the thumb together.
## Accessibility [#accessibility]
### Keyboard Interactions [#keyboard-interactions]
| Key | Description |
| ------- | ------------------------- |
| `Space` | Toggles the switch on/off |
| `Enter` | Toggles the switch on/off |
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| --------------- | ------- | ------------------------------------------------ |
| `role="switch"` | Button | Identifies the element as a toggle switch |
| `aria-checked` | Button | Reflects the current on/off state |
| `aria-label` | Button | Provides an accessible name via the `label` prop |
| `disabled` | Button | Indicates when the toggle is non-interactive |
### Screen Reader [#screen-reader]
* The `role="switch"` with `aria-checked` communicates the toggle state to assistive technologies.
* Focus is visually indicated with a focus-visible ring style.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, all spring animations, icon transitions, and morph effects are disabled instantly.
## Props [#props]
# Motion Loader (/docs/components/motion-loader)
## Features [#features]
Twelve loaders from a single install, switched with `variant`. Every one animates `transform` and `opacity` only. Colour inherits `currentColor` unless you pass `color`; `speed` tunes the loop; `label` feeds a polite live region.
## Variants [#variants]
### Orbit [#orbit]
A dot circling a faint track ring.
### Newton Cradle [#newton-cradle]
Five hanging balls; the outer ones swing in turn.
### Pendulum [#pendulum]
A single arm swinging with an ease-in-out arc.
### Hourglass [#hourglass]
Hourglass glyph flipping every half cycle.
### Morph Ring [#morph-ring]
Two counter-rotating dashed arcs with a scale pulse.
### Square Snake [#square-snake]
A square travelling the four corners of a 2×2 grid.
### Comet [#comet]
A head dot with a fading four-dot tail sweeping the circle.
### Radar [#radar]
A conic sweep rotating inside a circular mask.
### Cube Flip [#cube-flip]
A square flipping across both axes in perspective.
### Wave Bars [#wave-bars]
Five bars scaling vertically with a stagger.
### Breathing Glow [#breathing-glow]
A blurred halo breathing around a solid core.
### Dot Ring [#dot-ring]
Eight dots fading in sequence around a circle.
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | ------------------ | ------------------------------------------------------------------------ |
| `role="status"` | Loader wrapper | Marks the loader as a status region so assistive technologies observe it |
| `aria-live="polite"` | Loader wrapper | Announces the loading state without interrupting the user |
| `aria-label` | Loader wrapper | Names the region from the `label` prop |
| `sr-only` text node | Inside the wrapper | Gives the live region announceable text content |
### Screen Reader [#screen-reader]
* The loader is a labelled live region: mounting it announces the `label` politely, and unmounting it silences the region.
* Give each loader a specific label (`"Loading results"`, `"Saving changes"`) rather than the generic default when several can appear on the same screen.
* The loader is not focusable and adds nothing to the tab order.
### Reduced Motion [#reduced-motion]
This component respects `prefers-reduced-motion` via `useReducedMotion` from Motion. When reduced motion is preferred, every variant renders a single static frame — no `animate` or `transition` props are passed, so nothing loops. The wrapper still exposes `role="status"`, `aria-live="polite"` and the label, so the loading state remains fully announced.
## Props [#props]
# Music Toggle (/docs/components/music-toggle)
## Features [#features]
Play/pause control shaped like a spinning record with a live waveform and seekable progress ring. Caller-driven or self-contained with an optional `` element.
## Modes [#modes]
### Player [#player]
Full player with title, artist, seek ring, and waveform. Pass `playing`, `onPlayingChange`, `progress`, and `onSeek` — or supply `src` and let the component own playback.
### Caller-driven [#caller-driven]
Purely visual when you drive `playing` yourself — no `` element. Useful for previews and design systems where audio would be hostile.
## Accessibility [#accessibility]
### Keyboard Interactions [#keyboard-interactions]
| Key | Description |
| --------------------------- | ----------------------------------------------- |
| `Space` / `Enter` | Toggles play/pause (native `` behavior) |
| `Arrow Right` / `Arrow Up` | Seeks forward, when `onSeek` is provided |
| `Arrow Left` / `Arrow Down` | Seeks backward, when `onSeek` is provided |
| `Home` / `End` | Jumps to the start / end of the track |
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| --------------------------------------------------- | ------------------- | ---------------------------------------------------- |
| `aria-pressed` | Play/pause button | Reflects the current playing state |
| `aria-label` | Play/pause button | Reads "Play"/"Pause" plus the track title and artist |
| `role="slider"` | Progress ring | Exposes the seek control to assistive technology |
| `aria-valuenow` / `aria-valuemin` / `aria-valuemax` | Progress ring | Exposes playback position as a 0–100 percentage |
| `aria-hidden="true"` | Cover art, waveform | Hides purely decorative visuals |
### Screen Reader [#screen-reader]
* The play/pause button is a real ``, so it is announced with its role, pressed state and label out of the box.
* The waveform bars are `aria-hidden`; they carry no information not already exposed by the play/pause state.
* The seek ring is only focusable (`tabIndex={0}`) when `onSeek` is supplied — otherwise it is skipped by keyboard navigation.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the cover art stops rotating, the waveform bars stop animating, and the play/pause icon swaps instantly instead of morphing.
## Props [#props]
# Number Flow (/docs/components/number-flow)
## Features [#features]
* Smooth counting animations
* Locale-aware formatting
* Easing and duration controls
* Accessible labels
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
This component does not currently support the `prefers-reduced-motion` media query. Digit slide animations will play regardless of user preference.
### ARIA [#aria]
The increment and decrement buttons include descriptive `aria-label` attributes (`"Increase number"` and `"Decrease number"`). Buttons are properly disabled at the `min` and `max` boundaries via the `disabled` attribute.
### Keyboard [#keyboard]
The controls use native `` elements with `type="button"`, so they are focusable and operable via keyboard (Enter and Space) without additional handling.
## Props [#props]
# Orb (/docs/components/orb)
## Features [#features]
Sphere impostor with seamless OkLab colour marbling, nested domain warp, and twenty-two tuning props. Pauses off-screen and respects reduced motion.
## Variants [#variants]
Scroll the presets below — the panel shows one finished orb at a time.
### Bloom [#bloom]
Magenta against white. The lightness gap is what makes the marbling visible at all.
### Glass [#glass]
Four stops and a hard rim. Iridescence rotates the hue toward the edge, the way a bubble does.
### Ember [#ember]
Lit from within rather than from the side, so it reads as a lamp instead of a ball.
### Drop [#drop]
Wobble deforms the silhouette and the halo spills past it. A liquid drop, not a sphere.
## Why it does not look like a gradient circle [#why-it-does-not-look-like-a-gradient-circle]
A radial gradient has no surface, so light cannot behave like light on it: there
is no side turned away, no edge catching the sky, and no highlight that stays
put while the colour moves underneath. Deriving a normal costs one `sqrt` per
pixel and buys all three.
The second half is the loop. Offsetting the whole noise domain by one shared
vector gives you a pulse — everything moves the same way at once. Giving every
point its own circle, with neighbours starting at different angles, is what
reads as swirling.
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | ------------- | ---------------------------------------------- |
| `aria-hidden="true"` | Shader canvas | The orb is decorative and carries no semantics |
### Screen Reader [#screen-reader]
Nothing is announced. Where the orb stands for a state — an assistant
listening, a job running — put that state in text beside it. It should never be
the only carrier of the meaning.
### Reduced Motion [#reduced-motion]
Respects `prefers-reduced-motion`: one frame is drawn and no loop starts. The
preference is watched live, so toggling it at the OS level takes effect without
a reload.
## Props [#props]
### Tuning [#tuning]
| Prop | Low | High |
| ------------ | ---------------------- | -------------------------------------- |
| `blobScale` | many small cells, busy | one slow swell filling the sphere |
| `flow` | nearly still | the field travels a long way each loop |
| `turbulence` | smooth folds | curdled, marbled detail |
| `rim` | matte | glass |
| `specular` | soft | wet, polished |
| `inner` | lit from outside only | lit from within, like a lamp |
| `wobble` | a sphere | a liquid drop |
| `aberration` | clean edge | a lens fringe at the rim |
## Used by [#used-by]
`ai-orb-face` renders its body with this component, so anything you can tune
here you can pass through to the character.
# Orbital Image Wheel (/docs/components/orbital-image-wheel)
## Features [#features]
* Images arranged on a circle, positioned with trigonometry from a single `rotation` value
* Drag to spin with momentum that decays naturally after release
* Optional `snap` to settle on the nearest item after a drag or momentum
* Optional continuous `autoRotate`, paused on hover, focus, and when the tab is hidden
* `faceOutward` tilts each thumbnail to face away from the center
* Fully controlled or uncontrolled `rotation`, plus an `activeId` override for the highlighted item
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| ---------------------------------- | --------------------------- | ---------------------------------------------------------------------------------- |
| `role="application"` | Wheel container | Marks the wheel as a custom interactive widget with its own keyboard/drag behavior |
| `aria-label="Orbital image wheel"` | Wheel container | Gives the widget a descriptive name |
| `aria-label` | Each thumbnail button | Announces the item's `label` or `alt` text |
| `aria-current="true"` | Highlighted thumbnail | Marks the item currently at the top of the circle |
| `aria-live="polite"` | Visually-hidden status text | Announces which item becomes highlighted |
### Keyboard [#keyboard]
| Key | Action |
| ----------------------------------- | ---------------------------------------------------- |
| Arrow Right | Step forward by one item |
| Arrow Left | Step backward by one item |
| Tab | Move focus between thumbnail buttons |
| Enter / Space | Activate a focused thumbnail, bringing it to the top |
### Screen Reader [#screen-reader]
* Every image is rendered inside a real `` with an `aria-label`, so each item is independently focusable and announced.
* The highlighted item is marked with `aria-current="true"`, and a visually-hidden live region announces the current selection as the wheel rotates.
### Reduced Motion [#reduced-motion]
This component respects `prefers-reduced-motion` via `useReducedMotion` from Motion. When reduced motion is preferred, `autoRotate` never starts, drag release never applies momentum (rotation stops immediately), and keyboard/click stepping snaps instantly instead of tweening.
## Props [#props]
# Organic Merge Transition (/docs/components/organic-merge-transition)
## Features [#features]
* Persistent WebGL transition wrapper triggered by a `transitionKey`
* Replicates the “Organic Merge” stage from the Codrops shader progression
* Uses the shared SmoothUI SDF transition engine with reduced-motion fallback
* Accessible: semantic content stays in the DOM and `onRest` still fires
## Usage guidance [#usage-guidance]
Use it for meaningful route/state transitions where this shader grammar fits the product moment.
## Props [#props]
# OTP Slots (/docs/components/otp-slots)
## Features [#features]
* Auto-advance and backspace support
* Animated focus and validation
* Masking options
* Accessible and mobile-friendly
## Accessibility [#accessibility]
### Keyboard Interactions [#keyboard-interactions]
| Key | Description |
| ----------- | -------------------------------------------------------------- |
| `0-9` | Enters a digit and auto-advances to the next slot |
| `Backspace` | Deletes the current digit and moves focus to the previous slot |
| `Tab` | Moves focus to/from the OTP input |
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| ------------------ | --------- | ------------------------------------------------------------------- |
| `aria-label` | OTP input | Provides an accessible name (defaults to "One-time password input") |
| `aria-describedby` | OTP input | References an optional description element for additional context |
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, slot entrance animations, digit flip transitions, and the blinking caret are all disabled.
## Props [#props]
# Page Preloader (/docs/components/page-preloader)
## Features [#features]
* Four built-in variants: `words`, `stairs`, `pixel`, `curtain`
* Controlled (`active`) or uncontrolled (`defaultActive`) usage
* `container` mode renders the overlay `absolute` inside its parent instead of a full-screen `fixed` layer
* Locks page scroll while holding (skipped entirely in `container` mode)
* Deterministic, seeded tile order for the `pixel` variant — no randomness between renders
* Fires `onComplete` once the exit transition has fully finished
* Fully respects `prefers-reduced-motion`
## Variants [#variants]
* **words** — cycles through the `words` array with a vertical roll while holding, then the whole panel slides away.
* **stairs** — exits as `columns` vertical columns leaving the screen in a staggered cascade.
* **pixel** — exits as a `columns` × `columns` grid of tiles fading out in a randomized-but-deterministic, seeded order.
* **curtain** (default) — splits into two halves that part to reveal the page underneath.
## Usage guidance [#usage-guidance]
Mount `PagePreloader` once, near the root of the page it covers, and leave `active`/`defaultActive` uncontrolled for a simple "hold for `duration`, then reveal" splash. Switch to the controlled `active` prop when the reveal should wait on real data (e.g. `active={!isReady}`) — flipping it to `false` plays the same exit transition instead of the timer-driven one. Use `container` when the preloader should only cover a section of the page rather than the whole viewport.
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | -------------------- | --------------------------------------------------------------------------- |
| `role="status"` | Overlay container | Announces the overlay as a status region while it's visible |
| `aria-live="polite"` | Overlay container | Lets assistive tech announce the loading state without interrupting |
| `aria-hidden="true"` | Variant tiles/panels | Hides the decorative curtain/stairs/pixel/words visuals from assistive tech |
### Screen Reader [#screen-reader]
* A visually-hidden "Loading" string is rendered inside the `role="status"` region for the entire time the overlay is mounted.
* All decorative variant visuals (curtain halves, stair columns, pixel tiles, the words panel) are `aria-hidden`, so screen readers only ever hear the single "Loading" announcement.
* The overlay unmounts entirely (renders `null`) once the exit finishes, so it never traps focus or lingers in the accessibility tree.
### Reduced Motion [#reduced-motion]
This component respects `prefers-reduced-motion` via `useReducedMotion` from Motion. When reduced motion is preferred, the hold ends immediately, the staggered cascade is skipped, and every variant performs a single instant opacity fade at `duration: 0` instead of a transform-based exit.
## Props [#props]
# Pagination (/docs/components/pagination)
## Features [#features]
* Previous/next navigation buttons
* Page numbers with smart ellipsis for large ranges
* Spring-animated active page indicator
* Controlled component with `page` and `onPageChange`
* Configurable sibling count
* Respects reduced motion preferences
## Accessibility [#accessibility]
### Keyboard Interactions [#keyboard-interactions]
| Key | Description |
| ----------------- | -------------------------------------- |
| `Tab` | Moves focus between pagination buttons |
| `Enter` / `Space` | Activates the focused page button |
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| --------------------------------------- | ------------------ | --------------------------------- |
| `role="navigation"` | `` | Identifies as navigation landmark |
| `aria-label="Pagination"` | `` | Provides accessible name |
| `aria-current="page"` | Active page button | Indicates the current page |
| `aria-label="Go to page N"` | Page buttons | Descriptive label for each page |
| `aria-label="Go to previous/next page"` | Prev/next buttons | Descriptive label for navigation |
### Reduced Motion [#reduced-motion]
When `prefers-reduced-motion` is enabled, the active page indicator appears instantly without spring animation.
## Props [#props]
# Parallax Layers (/docs/components/parallax-layers)
## Features [#features]
* Any number of layers, each with its own `depth` (0 to 1)
* Vertical, horizontal, or combined scroll-driven movement
* Optional pointer-driven parallax on hover-capable devices, springed independently from scroll
* Works against the window or any scrollable ancestor via the `container` prop
* Only animates `transform` (`x`/`y`) — compositor-friendly
* Full `prefers-reduced-motion` support
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| — | — | The component adds no ARIA attributes of its own; each layer renders your `content` unchanged, so mark purely decorative layers with `aria-hidden="true"` yourself |
### Screen Reader [#screen-reader]
* Layer content is rendered in normal DOM order inside plain `` wrappers — nothing is hidden or reordered for assistive technology.
* Because layers commonly overlap visually, give any layer that conveys real information (headings, copy, controls) a higher depth value and keep decorative background layers marked `aria-hidden="true"` on their own content.
### Reduced Motion [#reduced-motion]
This component respects `prefers-reduced-motion` via `useReducedMotion` from Motion. When reduced motion is preferred, every layer renders statically at its natural position — depth is ignored and pointer-driven movement is disabled entirely.
## Props [#props]
# Per Character Rise (/docs/components/per-character-rise)
## Features [#features]
* Per-character slide-up with zero blur — crisp and sharp
* Apple tvOS / Fitness+ style kinetic reveal (`cubic-bezier(0.2, 0.8, 0.2, 1)`)
* Configurable delay and per-character stagger
* Optional scroll-trigger via `triggerOnView`
* Accessible: respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the text renders immediately at full opacity with no movement. The full string is exposed to screen readers via `aria-label`, with the per-character spans `aria-hidden`.
## Props [#props]
# Per Word Crossfade (/docs/components/per-word-crossfade)
## Features [#features]
* Per-word fade-in with a subtle upward drift (8 px)
* Calm keynote rhythm (`cubic-bezier(0.16, 1, 0.3, 1)`)
* Configurable delay and per-word stagger
* Optional scroll-trigger via `triggerOnView`
* Accessible: respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the text renders immediately at full opacity with no movement. The full string is exposed to screen readers via `aria-label`, with the per-word spans `aria-hidden`.
## Props [#props]
# Perspective Text 3D (/docs/components/perspective-text-3d)
## Features [#features]
* Splits content into `lines` or `words`, each pushed along the Z axis by `depth`
* Three drivers: `scroll` (tied to a container's scroll progress), `pointer` (tracks the cursor), and `static` (a fixed tilt)
* `transform-style: preserve-3d` plane with springed rotation for a smooth, physical feel
* Scroll-driven rotation is smoothed with `useSpring` so it never feels twitchy
* Respects `prefers-reduced-motion` by rendering flat, untransformed text
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | -------------------- | ------------------------------------------------------------ |
| `aria-label` | Wrapper element | Exposes the full, intact string once to assistive technology |
| `aria-hidden="true"` | Per-line/word planes | Hides the depth-separated fragments from screen readers |
### Screen Reader [#screen-reader]
* The wrapper carries `aria-label={content}`, announcing the full string as a single phrase.
* Each line or word plane underneath is `aria-hidden`, so the 3D fragments are never read individually.
* The text remains selectable in the DOM at all times.
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the component renders a flat paragraph with no perspective, no rotation, and no Z-axis separation — line breaks are preserved via `white-space: pre-line`.
## Props [#props]
# Photo Stack (/docs/components/photo-stack)
## Features [#features]
* Draggable top card — drag it in any direction and release to send it to the back
* Tap or keyboard (Enter / Space) to cycle the deck
* Layered stack with per-position offset, scale, and dim
* Optional caption (name + role) over the front card
* Spring transitions with `prefers-reduced-motion` fallback
* Fully typed, headless of any specific image source
## Accessibility [#accessibility]
### Keyboard Interactions [#keyboard-interactions]
| Key | Action |
| ----------------- | -------------------------------- |
| `Tab` | Focus the front card |
| `Enter` / `Space` | Cycle the front card to the back |
### Screen Reader [#screen-reader]
* The front card exposes `role="button"` with an `aria-label` derived from the photo's name (or alt text).
* Back cards are removed from the tab order (`tabIndex={-1}`) and their dim overlay is `aria-hidden`.
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, dragging is disabled and cards snap between positions with no spring animation (tap / keyboard still cycle the deck).
## Props [#props]
## Usage [#usage]
```tsx
import PhotoStack from "@/components/photo-stack";
export default function Example() {
const photos = [
{ id: "1", src: "/people/mara.jpg", alt: "Mara Okonkwo", name: "Mara Okonkwo", role: "Design engineer" },
{ id: "2", src: "/people/noa.jpg", alt: "Noa Bergström", name: "Noa Bergström", role: "Frontend lead" },
{ id: "3", src: "/people/ines.jpg", alt: "Ines Duarte", name: "Ines Duarte", role: "Solo founder" },
];
return
;
}
```
## Examples [#examples]
### Plain photos (no caption) [#plain-photos-no-caption]
```tsx
```
### React to the order changing [#react-to-the-order-changing]
```tsx
console.log("new order", order)}
/>
```
# Phototab (/docs/components/phototab)
## Features [#features]
* Tab and swipe transitions
* Lazy image loading friendly
* Keyboard and ARIA tabs
* Responsive grid
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| ------------ | ---------------- | ------------------------------------------- |
| `aria-label` | Tab list | Provides an accessible name "Phototab Tabs" |
| `aria-label` | Each tab trigger | Describes the tab name |
### Screen Reader [#screen-reader]
* Built on Radix UI's Tabs primitives, which provide built-in `role="tablist"`, `role="tab"`, and `role="tabpanel"` semantics with automatic `aria-selected` state management.
* Each tab trigger includes a visually hidden `` with the tab name.
* Tab images have `alt` attributes matching the tab name.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the hover background pill animation uses instant transitions instead of spring physics.
## Props [#props]
# Pinned List (/docs/components/pinned-list)
## Features [#features]
Four springs, each tuned for its own job, so pinning reads as a physical launch rather than a rigid reflow:
* **The launch** — pinning moves the row into the pinned group through a shared `layoutId` on a spring with real overshoot (`bounce: 0.3`), so the row visibly arrives rather than sliding to a stop
* **The landing pop** — the row compresses to `0.985` and settles back in two decaying steps as it lands in the pinned group, on an inner wrapper so the pop never fights the layout projection. It squashes rather than inflates on purpose: a row that grows past `1` pushes outside the list, and the list almost always sits in a scroller, so an inflating pop gets sliced off exactly when it is biggest
* **The pin** — the icon rotates 45° and fills on its own, snappier spring (`bounce: 0.32`, `0.2s`), ahead of the row it belongs to
* **The gap** — the rows closing the gap underneath each get a small incremental layout delay, so the group settles one row after another instead of moving as one block
Plus:
* Pinned rows are marked structurally rather than with a fill: the surface lifts on a real shadow with a crisper edge, a short accent rail grows on the leading edge, and the pin itself carries the colour — unpinned rows sit flat and transparent underneath
* Every row keeps a 4px halo inside the list, so the landing rebound, the launch overshoot and the focus ring all stay clear of whatever clips the list
* Works controlled (`pinnedIds` / `onPinnedChange`) or uncontrolled
* `maxPinned` caps how many items can be pinned at once
* Optional `renderItem` for fully custom row content
* The row itself is the control: it carries the roving tabindex, so `Arrow`, `Home`, `End` and `P` always reach a row that actually holds focus
* Pinned and unpinned rows live in one list, so pinning reorders a row inside its parent rather than tearing it out of one list and rebuilding it in another — and focus stays on the row that moved
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
| `role="button"` | Row | The whole row is the pin control, so there is one tab stop and one keyboard target per row |
| `aria-pressed` | Row | Reflects whether the row is currently pinned |
| `aria-label="Pin / Unpin {title}"` | Row | Names the action and its target for assistive technology, flipping with the pinned state |
| `aria-disabled` | Row | Indicates the pin action is unavailable once `maxPinned` is reached |
| `aria-label` | List | Names the list, from the `label` prop |
| `aria-hidden="true"` | Divider, pin icon | Hides the purely visual separator and the pin glyph from assistive technology |
### Keyboard Interactions [#keyboard-interactions]
| Key | Description |
| -------------------------- | ------------------------------------------------------------------------------------ |
| `Tab` | Moves focus into the list, landing on the last focused row (the first row initially) |
| `ArrowDown` / `ArrowRight` | Moves focus to the next row, wrapping at the end |
| `ArrowUp` / `ArrowLeft` | Moves focus to the previous row, wrapping at the start |
| `Home` / `End` | Moves focus to the first / last row |
| `P` | Toggles pin on the focused row |
| `Enter` / `Space` | Toggles pin on the focused row |
### Screen Reader [#screen-reader]
* Every row is a labelled, pressable control, so the pinned state is announced without relying on the icon rotation alone.
* Rows render inside one semantic `` named by `label`, and reordering a row keeps its position in the list announcement consistent with what is on screen.
* When there are no pinned items, an `emptyPinnedMessage` row is rendered at the top of the list.
* Focus returns to the acted-on row after it moves between the pinned and unpinned groups, so a keyboard user never loses their place.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, layout animation is switched off entirely so rows cut straight to their final position, and the landing pop, the staggered gap close and the pin rotation all resolve instantly.
## Props [#props]
# Pixel Brush Canvas (/docs/components/pixel-brush-canvas)
## Features [#features]
* Pencil, eraser, iterative flood-fill, line and rectangle brushes
* Pixel state stored in a typed `Uint8Array`; strokes redraw only the dirty region instead of the whole canvas
* Undo stack capped at a fixed depth (`MAX_UNDO_STEPS`), backed by pixel-buffer snapshots
* Fully keyboard-operable: move a focus cursor, paint, switch tools and undo without a pointer
* Imperative `ref` API (`clear`, `undo`, `toDataURL`, `getPixels`) for wiring external toolbars
* Backing store capped at 2x device pixel ratio for crisp but bounded-cost rendering
* No idle animation on the canvas — only the surrounding tool palette animates, and it respects reduced motion
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| --------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------- |
| `role="application"` | Canvas wrapper | Marks the region as a custom keyboard-driven widget with its own key bindings |
| `aria-label="Pixel art drawing canvas"` | Canvas wrapper | Gives the application region an accessible name |
| `aria-live="polite"` | Hidden live region inside the wrapper | Announces the focused cell and paint results without interrupting |
| `aria-label` | Color swatch buttons | Identifies each swatch by position and color value |
| `aria-pressed` | Color swatch buttons | Reflects whether that color is currently selected |
| `aria-label` | Brush tool buttons | Names the tool and its keyboard shortcut, when it has one |
| `aria-pressed` | Brush tool buttons | Reflects whether that brush is currently active |
### Keyboard [#keyboard]
| Key | Action |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Arrow Up / Down / Left / Right` | Move the focus cursor one cell at a time, clamped to the grid bounds |
| `Space` | Paint at the focus cursor with the current brush and color. For Line/Rectangle, the first press sets an anchor and the second press commits the shape |
| `B` | Switch to the pencil brush |
| `E` | Switch to the eraser brush |
| `G` | Switch to the fill (bucket) brush |
| `Cmd/Ctrl + Z` | Undo the last committed stroke, fill, line, rectangle or clear |
### Screen Reader [#screen-reader]
A visually hidden `aria-live="polite"` region inside the canvas wrapper announces the focus cursor's column and row plus the resulting color every time the cursor moves or a paint action completes (for example, "Column 4, row 2. Color: #ef4444." or "Anchor set at column 3, row 5. Move and press space again to finish."). This keeps non-visual users oriented on the grid without needing to see the canvas.
### Reduced Motion [#reduced-motion]
The canvas itself never animates — pixel painting is an immediate, one-frame redraw of only the affected region, with no transitions to disable. The tool palette (color swatch selection ring, hover/focus color transitions) uses `useReducedMotion` from Motion: when reduced motion is preferred, the selection indicator appears instantly with a `duration: 0` transition instead of springing in.
## Props [#props]
# Pixel Flow Field (/docs/components/pixel-flow-field)
## Features [#features]
* **The field carries a word.** `text` is rasterised to an offscreen canvas and read back with `getImageData`, one pixel per cell. Each cell's brightness and size come from the coverage it sampled, so the grid resolves into readable type.
* **Scatter and re-form.** Cells arrive dispersed across the surface and travel home on an ease-out curve with a spatial stagger, so they land in a sweep rather than all at once. Bumping the `scatter` counter blows the field apart again.
* **A wake, not a push.** Pointer impulses accumulate into a per-cell displacement that decays exponentially, so you can see the path the cursor took a moment ago. The trail is walked in sub-steps between frames, so a fast flick leaves a continuous stroke instead of dotted impacts.
* **The word is the calm centre.** Cells the word covers barely drift while the empty field keeps flowing around them — the type reads as stillness inside motion.
* **Cells scale with field magnitude**, so the flow itself is legible even where the word is not.
* **Brightness travels through lightness**, not opacity alone: the three-stop `colors` ramp goes dim field → accent → ink, which is what makes the word actually resolve instead of looking like a slightly darker patch of grey.
* `square`, `circle`, and `cross` cell shapes.
* Optional `src` samples an image instead of the word, falling back to `text` when the pixels cannot be read.
* Colours resolve from CSS custom properties, so the field follows your theme in light and dark.
* `paused` freezes the field on its current frame.
* Automatic dotted-background fallback when Canvas2D is unavailable.
## Usage [#usage]
```tsx
import PixelFlowField from "@/components/smoothui/ui/pixel-flow-field";
const [scatter, setScatter] = useState(0);
setScatter((n) => n + 1)} type="button">
Scatter and re-form
;
```
The wrapper is `position: relative` and the canvas is absolutely positioned inside it, so **the element needs a resolvable height** — an explicit `h-[460px]`, an aspect ratio, or content whose own flow provides it.
## Performance [#performance]
**Sampling happens once, never per frame.** The word is rasterised into a `cols × rows` bitmap — one pixel per cell — and `getImageData` is called exactly once per source change. The result is cached and only re-read when the grid dimensions, `text`, `weight`, the resolved font family, or `src` actually change. Nothing reads pixels inside the render loop.
**The flow field is evaluated coarsely.** Value noise is sampled on a lattice of one point per 4×4 block of cells and bilinear-filtered per cell, with the bilinear indices and weights precomputed at grid build time. Per-frame trigonometry is therefore proportional to the lattice, roughly a sixteenth of the cell count, and the per-cell cost is a handful of multiplies.
**Cells are batched by brightness.** Coverage is quantised into 7 tiers at build time, so a frame issues 7 `fillStyle` assignments and 7 `fill()` calls regardless of how many cells there are — not one per cell, and no DOM node per cell. Cells pushed off-surface during a scatter are culled before any path work.
**The grid adapts at both ends.** Because the word is fitted to a fraction of the column count, too few columns means too few cells per glyph and the type stops reading — so on a narrow surface the grid densifies to at least 44 columns rather than letting the word turn to mush. At the other end, **the cell count is capped at 14,000.** Cell count scales with area / step², so a large panel with small cells is the expensive case; past the cap the grid is coarsened rather than truncated, keeping coverage complete. At the demo's size (roughly 700 × 460 with `cellSize={7}` and `gap={3}`) the field is about 3,200 cells and a frame costs well under a millisecond of scripting on a current laptop — comfortably inside a 120 Hz budget. The backing store honours `devicePixelRatio` capped at 2.
**Nothing routes through React state.** Shape, scatter, colours, and pointer position are pushed into an imperative controller via `setSettings` / `setPointer`; there is no `setState` per frame and no CSS custom property animated on a parent.
**When it pauses.** The render loop is torn down, not merely skipped:
* An `IntersectionObserver` stops the loop as soon as the field leaves the viewport — and the scatter reveal is deferred until the field is first visible, rather than playing to nobody below the fold.
* A `visibilitychange` listener stops the loop when the tab is hidden.
* Setting `paused` stops the loop and leaves the last frame on screen.
* A `ResizeObserver` drives resizing, so no layout is read per frame.
On unmount the animation frame is cancelled, pointer listeners are removed, and both the visible canvas and the offscreen sampler have their backing stores collapsed to free memory.
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `aria-hidden="true"` | Canvas wrapper | Removes the purely decorative field from the accessibility tree. The attribute sits on the wrapper, never on the canvas element itself |
| `aria-hidden="true"` | Dotted fallback | Same treatment when Canvas2D is unavailable |
### Screen Reader [#screen-reader]
The word rendered into the field is decoration, not content — it is pixels on a canvas and is never announced. If the word carries meaning, repeat it in real text inside `children`. The canvas wrapper is `aria-hidden` and has `pointer-events: none`, and pointer tracking is attached to the outer wrapper, so links, buttons, and inputs nested inside keep their own hit targets and focus behaviour.
### Reduced Motion [#reduced-motion]
With `prefers-reduced-motion` active the component draws **one static frame and starts no `requestAnimationFrame` loop at all**. That frame is the fully resolved state: every cell on its grid position, the word at full legibility, no scatter, no flow displacement, no wake. Pointer listeners are not attached either, so moving the cursor changes nothing.
### Contrast [#contrast]
The default ramp runs from `--color-smooth-500` for the empty field to `--color-foreground` for the word's core, which keeps a real lightness gap against the background in both themes rather than relying on saturation. If you pass your own `colors`, keep that lightness gap on the last stop — that is the stop the word is read from.
## Props [#props]
# Power Off Slide (/docs/components/power-off-slide)
## Features [#features]
* Drag to confirm interaction
* Spring physics and rubber-banding
* Accessible labels and states
* Theming options
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| --------------- | ----------- | ----------------------------------------------- |
| `aria-disabled` | Drag handle | Indicates when the slider is disabled |
| `tabIndex={0}` | Drag handle | Makes the handle focusable when not disabled |
| `tabIndex={-1}` | Drag handle | Removes the handle from tab order when disabled |
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the drag interaction is disabled (`drag={false}`), the shimmer text animation stops, and the handle uses instant transitions.
## Props [#props]
# Price Flow (/docs/components/price-flow)
## Features [#features]
* Smooth number swaps for pricing
* Works with monthly/annual toggles
* Locale formatting
* Accessible labeling
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
This component does not currently support the `prefers-reduced-motion` media query. Digit slide animations will play regardless of user preference.
## Props [#props]
# Prism Sweep Transition (/docs/components/prism-sweep-transition)
## Features [#features]
* Route/state transition wrapper triggered by a `transitionKey`
* Custom faceted prism field rendered over the whole component frame with a persistent WebGL shader controller
* Swaps the new content at the shader midpoint so the reveal lands under the crest
* Direction controls for product-specific motion language
* Accessible: honors `prefers-reduced-motion` and keeps semantic content in the DOM
## Why it is different [#why-it-is-different]
Product UI needs control, restraint, and graceful failure. Prism Sweep Transition uses a SmoothUI-specific faceted caustic shader, swaps content under the field crest, and contains the canvas inside the component frame instead of taking over the whole app.
Use it sparingly for meaningful state changes: publishing, checkout completion, presentation mode changes, or section-level navigation. Avoid triggering it on passive interactions like hover, dropdowns, or every internal link.
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
The component uses `useReducedMotion` from Motion. When reduced motion is preferred, content swaps immediately, the sweep is skipped, and `onRest` still fires so application logic stays consistent.
## Props [#props]
# Product Card (/docs/components/product-card)
## Features [#features]
* Animated entrance on viewport entry
* Image zoom on hover (hover-capable devices only)
* Badge overlay for sales/new items
* Star rating display
* Discount pricing with strikethrough
* Add to cart button with feedback animation
* Respects reduced motion preferences
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| ---------------- | ----------- | ---------------------------------- |
| `role="article"` | Card | Semantic card container |
| `aria-label` | Card | Announces title and price |
| `alt` | Image | Descriptive image text |
| `aria-label` | Rating | Announces rating out of 5 |
| `role="status"` | Badge | Announces discount/sale info |
| `aria-label` | Add to cart | Announces action with product name |
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, entrance animations, hover zoom, and scale effects are disabled.
## Props [#props]
# Progressive Blur (/docs/components/progressive-blur)
## Features [#features]
* Stacked layers where every step doubles the blur radius and is masked by a gradient shifted one band further
* Five ramp directions: `top`, `bottom`, `left`, `right` and `radial`
* `layers` between 2 and 12 — more layers means a smoother, more expensive ramp
* `intensity` dials the whole veil down without touching the blur radii
* Pure CSS: `backdrop-filter` plus `mask-image`, with no `requestAnimationFrame` and no scroll listeners
* Optional mount fade-in that turns instant under reduced motion
* Optional `children` layer that stays interactive above the decorative stack
## Component notes [#component-notes]
The blur stack is rendered as an **absolutely positioned overlay**: it needs a
positioned ancestor (`relative`, usually with `overflow-hidden`). The stack is
`pointer-events: none` and `aria-hidden="true"`, so it never intercepts clicks,
never traps focus and never reaches the accessibility tree — content underneath
stays fully scrollable and selectable. Anything passed as `children` is rendered
in a separate sibling layer that re-enables pointer events, so labels or buttons
placed on top of the ramp keep working.
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | ---------------- | ----------------------------------------------------------------- |
| `aria-hidden="true"` | Blur layer stack | Hides the purely decorative blur ramp from assistive technologies |
### Screen Reader [#screen-reader]
* The stack is decorative only: it is `aria-hidden` and `pointer-events: none`, so screen reader users get the underlying content unchanged.
* Because the blur is visual, never let it be the only cue that content continues — pair it with a real scroll container so keyboard and screen reader users can still reach everything.
* Text that sits under the strongest layers becomes unreadable by design; keep anything meaningful outside the ramp or inside `children`.
### Reduced Motion [#reduced-motion]
This component respects `prefers-reduced-motion` via `useReducedMotion` from Motion. The blur itself is static and always safe, but when reduced motion is preferred the optional mount fade-in is skipped entirely: the stack is painted at full opacity on the first frame with no opacity transition.
## Props [#props]
# Radial Circles Transition (/docs/components/radial-circles-transition)
## Features [#features]
* Persistent WebGL transition wrapper triggered by a `transitionKey`
* Replicates the “Radial Circles” stage from the Codrops shader progression
* Uses the shared SmoothUI SDF transition engine with reduced-motion fallback
* Accessible: semantic content stays in the DOM and `onRest` still fires
## Usage guidance [#usage-guidance]
Use it for meaningful route/state transitions where this shader grammar fits the product moment.
## Props [#props]
# Ransom Note (/docs/components/ransom-note)
## Features [#features]
* Every character becomes its own paper "scrap" with a seeded font, size, rotation, skew, and background color
* A deterministic mulberry32-style PRNG (`createSeededRandom`) drives all randomness — no `Math.random()` anywhere, so the same `text` + `seed` + `intensity` always produces the same layout, even during SSR
* Layout is memoised so it stays stable across re-renders and only recomputes when `text`, `seed`, `intensity`, `fonts`, `palette`, or `rotation` actually change
* `intensity` (0..1) scales how wild the per-character variation gets, from barely-there to chaotic
* `animate="assemble"` flies each scrap in from a seeded offset with a per-character stagger; `animate="jitter"` leaves scraps in place and gives each one a tiny idle wobble loop; `animate="none"` renders everything static
* `fonts` and `palette` let you swap in your own font stacks and paper colors
* Whitespace characters are preserved as plain spacing, without a paper scrap box
## Accessibility [#accessibility]
### Keyboard Interactions [#keyboard-interactions]
Not applicable — `RansomNote` is a purely presentational text component with no interactive elements, so it has no keyboard behavior of its own.
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | --------------- | --------------------------------------------------------------------------- |
| `aria-hidden="true"` | Scrap container | Hides the decorative, per-character scrap spans from assistive technologies |
### Screen Reader [#screen-reader]
* The full, intact string is always exposed once as visually-hidden (`sr-only`) text, independent of animation state, so screen readers read the intended sentence rather than individual letters.
* The animated scrap spans live inside an `aria-hidden="true"` container and never become the accessible content.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, every scrap renders directly in its final position and rotation with no transition — there is no assemble fly-in and no idle jitter loop, regardless of the `animate` prop.
## Props [#props]
# Reveal Text (/docs/components/reveal-text)
## Features [#features]
* Enter animations from up, down, left, or right
* Character or word stagger options
* Delay and duration controls
* Built with Framer Motion
* Accessible and performant
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the text is displayed immediately at full opacity without any directional slide animation.
## Props [#props]
# Reviews Carousel (/docs/components/reviews-carousel)
## Features [#features]
* Smooth spring-based animations for card transitions
* Keyboard navigation (Arrow keys)
* Auto-play support with configurable interval
* Customizable indicators and navigation buttons
* Respects `prefers-reduced-motion` for accessibility
* Stack-based card layout with depth effect
* Blur and opacity effects for inactive cards
## Accessibility [#accessibility]
### Keyboard Interactions [#keyboard-interactions]
| Key | Description |
| ------------ | ------------------------------- |
| `ArrowLeft` | Navigate to the previous review |
| `ArrowRight` | Navigate to the next review |
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| --------------- | ------------------ | --------------------------------------------------------------- |
| `aria-label` | Navigation buttons | Labels for "Anterior" (previous) and "Siguiente" (next) buttons |
| `aria-label` | Indicator buttons | Labels each indicator with its position number |
| `type="button"` | All buttons | Prevents implicit form submission |
| `disabled` | Navigation buttons | Disables previous/next when at the bounds |
### Screen Reader [#screen-reader]
* Reviews use semantic `figure` and `figcaption` elements with `blockquote` for proper review structure.
* Navigation state is communicated through disabled button states.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, card scale, vertical offset, blur, and opacity transitions use instant `0ms` durations instead of spring animations.
## Props [#props]
# Rich Popover (/docs/components/rich-popover)
## Features [#features]
* Animated entrance and smart positioning
* Supports media, lists, actions
* Keyboard and screen reader support
* Theming and sizes
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| ------------------- | ---------------- | -------------------------------------------------- |
| `aria-label` | YouTube SVG icon | Provides an accessible name "YouTube" for the icon |
| `role="img"` | YouTube SVG icon | Identifies the SVG as an image |
| `focusable="false"` | YouTube SVG icon | Prevents the decorative icon from receiving focus |
### Screen Reader [#screen-reader]
* The popover is built on Radix UI's Popover primitives, which provide built-in focus management and ARIA dialog semantics.
* External links use `rel="noopener noreferrer"` and include an external link icon for visual indication.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the popover content appears and disappears instantly without scale, slide, or blur animations.
## Props [#props]
# Rolling Text (/docs/components/rolling-text)
## Features [#features]
* Each character is a fixed-height clipping box with a vertical column of glyphs translated into place
* Ramp alphabet defaults to the unique characters found in the target text, or a custom `glyphs` string
* Four trigger modes: `mount`, `inView`, `hover`, and `manual`
* Configurable roll `direction`, `duration`, `stagger`, and ramp length
* Grapheme-aware splitting so emoji never break mid-character
* Respects `prefers-reduced-motion` by showing the final glyph only
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | ------------------------ | ------------------------------------------------------------ |
| `aria-label` | Wrapper element | Exposes the full, intact string once to assistive technology |
| `aria-hidden="true"` | Per-character clip boxes | Hides the rolling glyph columns from screen readers |
### Screen Reader [#screen-reader]
* The wrapper carries `aria-label={text}`, announcing the target string as a single phrase.
* Each rolling character column is `aria-hidden`, so intermediate ramp glyphs are never announced.
* The text remains selectable in the DOM at all times.
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the component renders the plain target string directly — no clipping boxes, no glyph ramp, no roll transition, regardless of `trigger`.
## Props [#props]
# Scale Down Fade (/docs/components/scale-down-fade)
## Features [#features]
* Whole-text scale-down settle-in from scale 1.04 to 1 with opacity and a slight y drift (`cubic-bezier(0.22, 1, 0.36, 1)`)
* Restrained, quiet motion — polished without being distracting
* Configurable delay
* Optional scroll-trigger via `triggerOnView`
* Accessible: respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the text renders immediately at full opacity with no scaling or movement. The `aria-label` on the wrapper ensures screen readers get the full text.
## Props [#props]
# Scramble Hover (/docs/components/scramble-hover)
## Features [#features]
* Character scrambling on hover with duration and speed controls
* Works with headings and inline text
* Smooth and performant
* Built with Framer Motion
* Accessible fallbacks
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query. When enabled, the scramble animation is fully disabled and the original text is always shown.
### Keyboard Support [#keyboard-support]
The component renders as a `` element with `type="button"`, making it natively focusable and keyboard-accessible. The scramble effect triggers on focus and clears on blur.
### Hover Device Detection [#hover-device-detection]
Detects whether the user's device supports hover via the `(hover: hover) and (pointer: fine)` media query. On touch devices, hover-based animations are disabled to avoid stuck states.
## Props [#props]
# Scroll Image Reveal (/docs/components/scroll-image-reveal)
## Features [#features]
* Five mask styles — wipe, curtain, circle, blinds and scale
* Independent counter-parallax travel on the image itself
* The mask is applied to the frame, never the image, so a clip always lines up with the frame's edges
* The image is overscanned by the parallax distance on both edges, so the travel can never drag a strip of background into view
* The `scale` mask settles *down* from a slight overscan instead of growing from smaller than the frame, so no gap ever opens at the sides
* Driven by `motion/react`'s `useScroll` with a spring for organic easing
* Works against the window or any scrollable ancestor via the `container` prop
* Optional `once` mode that never re-hides the image after it has revealed
* Only animates `clip-path`, `mask-image`, `opacity`, `scale` and `transform` — all compositor-friendly
* Full `prefers-reduced-motion` support
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| --------- | ------- | ------------------------------------------------------------------------------ |
| `alt` | `img` | Required accessible description, always rendered regardless of animation state |
### Screen Reader [#screen-reader]
* The image is a standard ` ` with the required `alt` text — screen readers announce it immediately, independent of scroll position or mask progress.
* No content is hidden from assistive technology; only the visual reveal is animated.
### Reduced Motion [#reduced-motion]
This component respects `prefers-reduced-motion` via `useReducedMotion` from Motion. When reduced motion is preferred, the image renders fully visible immediately — no clip-path mask, no mask-image, no scale-in and no parallax travel are applied, and the parallax overscan collapses to zero so the image sits flush in its frame.
## Props [#props]
Two things to get right when you pass `container`:
1. **Give it a definite height** — `h-[440px]`, `h-dvh`, a grid track — plus
`overflow-y-auto`. A percentage height like `h-full` resolves to `auto`
against a content-sized parent, so the container grows to fit every frame
at once and no reveal ever runs.
2. **Do not wrap the frames in a positioned element.** Progress is resolved by
walking `offsetParent` from the frame up to the scroll container, so a
`relative` div between the two — added for a gradient overlay, say — ends
that walk early and the frames report zero progress wherever they actually
are. Position overlays against an ancestor *outside* the scroller instead.
# Scroll Progress (/docs/components/scroll-progress)
## Features [#features]
* Four variants — bar, ring, number and segments — all four can share one scroll container
* Tracks the window's scroll, or any scrollable ancestor via the `container` prop
* Bar variant has a real track and slides a full-width fill with `translateX` (never `width`), so it stays compositor-only and its rounded cap and gradient are never distorted; the leading-edge glow is a stop in the fill's own gradient, so it is flush with the bar and cannot drift off it
* Ring variant uses Motion's normalised `pathLength` for the stroke sweep, over a matching track circle, with the percentage set in its centre (`showLabel`)
* The percentage is one typographic unit — tabular figures with the `%` sized as a fraction of them on a shared baseline — optically centred in the ring rather than merely centred by geometry
* Segments variant gives each pill its own slice of the range and springs it open, so they fill strictly one after another
* `position` uses `sticky`, not `fixed`, so it stays safely contained inside constrained layouts — or `inline` to opt out of stickiness and place the indicator in your own header or footer bar
* Full `prefers-reduced-motion` support
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | ------------ | ------------------------------------------------------- |
| `role="progressbar"` | Root element | Identifies the indicator as a progress meter |
| `aria-valuemin` | Root element | Always `0` |
| `aria-valuemax` | Root element | Always `100` |
| `aria-valuenow` | Root element | Current read percentage, rounded to the nearest integer |
| `aria-label` | Root element | `"Reading progress"` |
### Screen Reader [#screen-reader]
* The root element exposes `role="progressbar"` with live `aria-valuenow`, so assistive technology can announce reading progress independent of the visual variant chosen.
* The `showLabel` prop additionally renders a visible percentage (ring, segments) or an `sr-only` one (bar) for sighted or screen-reader users who want an explicit number.
* The ring's `` is `aria-hidden`; the value is exposed once, on the root `progressbar`, so it is never announced twice.
### Reduced Motion [#reduced-motion]
This component respects `prefers-reduced-motion` via `useReducedMotion` from Motion. When reduced motion is preferred, the value updates directly from scroll with no spring smoothing — the indicator still tracks scroll position exactly, since that is its entire purpose, but never overshoots or eases. The segments variant drops its per-pill spring for the same reason.
## Props [#props]
When you pass `container`, that element needs a **definite height** — `h-[440px]`,
`h-dvh`, a grid track, anything resolvable — plus `overflow-y-auto`. A
percentage height such as `h-full` resolves to `auto` against a parent that
sizes itself to its content, at which point the container grows to fit
everything inside it, never scrolls, and every indicator sits frozen at 0%.
Nothing errors; the progress simply never moves.
# Scroll Reveal Paragraph (/docs/components/scroll-reveal-paragraph)
## Features [#features]
* Reveal on scroll with smooth fade and translate
* Per-paragraph stagger for long-form content
* Configurable thresholds and offsets
* Built with Framer Motion + Intersection Observer
* Accessible and performant
## Accessibility [#accessibility]
### Screen Reader [#screen-reader]
* The component renders as a semantic `p` element, preserving paragraph structure for assistive technologies.
* Each word is wrapped in a `span` for animation purposes, but the text content remains fully readable.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, all words are displayed at full opacity immediately without the scroll-driven reveal effect. The ghost text overlay used for the reveal effect is also hidden.
## Props [#props]
# Scrollable Card Stack (/docs/components/scrollable-card-stack)
## Features [#features]
* Stacked, snap-scrolling layout
* Parallax and reveal motion
* Keyboard and touch friendly
* Theming options
## Accessibility [#accessibility]
### Keyboard Interactions [#keyboard-interactions]
| Key | Description |
| -------------------------- | ------------------------------ |
| `ArrowUp` / `ArrowLeft` | Navigates to the previous card |
| `ArrowDown` / `ArrowRight` | Navigates to the next card |
| `Home` | Jumps to the first card |
| `End` | Jumps to the last card |
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | ---------------- | -------------------------------------------------------------- |
| `aria-label` | Section | Provides an accessible name "Scrollable card stack" |
| `aria-live="polite"` | Section | Announces card changes to screen readers |
| `aria-atomic="true"` | Section | Ensures the full announcement is read together |
| `role="application"` | Container | Indicates custom keyboard interaction model |
| `role="tablist"` | Navigation dots | Groups the dot indicators as a tab list |
| `role="tab"` | Each dot | Identifies each dot as a tab control |
| `aria-selected` | Each dot | Indicates the active card indicator |
| `aria-label` | Each dot | Describes position (e.g., "Go to card 1 of 5") |
| `aria-hidden` | Non-active cards | Hides stacked cards behind the current one from screen readers |
| `aria-label` | Profile link | Describes the link action (e.g., "View John's profile") |
### Screen Reader [#screen-reader]
* A live region announces the current card position (e.g., "Card 1 of 5 selected. Use arrow keys to navigate one card at a time, or click the dots below.").
* Non-active cards are marked `aria-hidden` so only the visible card is announced.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, card scale/translate animations, blur effects, and hover scale transitions are all disabled.
## Props [#props]
# Scrubber (/docs/components/scrubber)
## Features [#features]
* Dark, self-contained slider with built-in label and value display
* Animated thumb that appears on hover and drag with spring physics
* Subtle scrub indicator for position feedback at rest
* Configurable tick marks for visual reference
* Keyboard accessible (arrow keys, Home, End)
* Supports controlled and uncontrolled usage
* Respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### Keyboard Interactions [#keyboard-interactions]
| Key | Description |
| ------------------------- | ------------------------------- |
| `ArrowRight` / `ArrowUp` | Increases the value by one step |
| `ArrowLeft` / `ArrowDown` | Decreases the value by one step |
| `Home` | Sets the value to the minimum |
| `End` | Sets the value to the maximum |
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| --------------- | ------------- | --------------------------------------------------- |
| `role="slider"` | Track element | Identifies the component as a slider |
| `aria-label` | Track element | Provides an accessible name (uses the `label` prop) |
| `aria-valuemin` | Track element | Communicates the minimum value |
| `aria-valuemax` | Track element | Communicates the maximum value |
| `aria-valuenow` | Track element | Communicates the current value |
| `tabIndex={0}` | Track element | Makes the slider focusable |
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the thumb capsule animation uses instant transitions instead of spring physics.
## Props [#props]
# SDF Blob Transition (/docs/components/sdf-blob-transition)
## Features [#features]
* Persistent WebGL transition wrapper triggered by a `transitionKey`
* Soft-merged SDF circles inspired by shader image reveal techniques
* Organic noise on the perimeter so the reveal feels alive without leaving residue
* Accessible: honors `prefers-reduced-motion` and keeps semantic content in the DOM
## Usage guidance [#usage-guidance]
Use it for launch moments, onboarding steps, checkout completion, or presentation state changes where an organic reveal fits the product language.
## Accessibility [#accessibility]
When reduced motion is preferred, content swaps immediately and `onRest` still fires.
## Props [#props]
# SDF Circle Transition (/docs/components/sdf-circle-transition)
## Features [#features]
* Persistent WebGL transition wrapper triggered by a `transitionKey`
* Replicates the “SDF Circle” stage from the Codrops shader progression
* Uses the shared SmoothUI SDF transition engine with reduced-motion fallback
* Accessible: semantic content stays in the DOM and `onRest` still fires
## Usage guidance [#usage-guidance]
Use it for meaningful route/state transitions where this shader grammar fits the product moment.
## Props [#props]
# Circle Reveal Transition (/docs/components/shader-reveal-circle-transition)
## Features [#features]
* Persistent WebGL transition wrapper triggered by a `transitionKey`
* Adapts a shader image-transition technique into a SmoothUI frame transition
* Preserves semantic React content and swaps at the shader midpoint
* Accessible: honors `prefers-reduced-motion` and fires `onRest`
## Usage guidance [#usage-guidance]
Use it for meaningful product state changes where a shader-led transition should feel intentional, not decorative. The component translates image-transition shader techniques into a frame-level overlay that can wrap arbitrary React content.
## Props [#props]
# Luma Ribbons Transition (/docs/components/shader-reveal-luma-transition)
## Features [#features]
* Persistent WebGL transition wrapper triggered by a `transitionKey`
* Adapts a shader image-transition technique into a SmoothUI frame transition
* Preserves semantic React content and swaps at the shader midpoint
* Accessible: honors `prefers-reduced-motion` and fires `onRest`
## Usage guidance [#usage-guidance]
Use it for meaningful product state changes where a shader-led transition should feel intentional, not decorative. The component translates image-transition shader techniques into a frame-level overlay that can wrap arbitrary React content.
## Props [#props]
# Noise Gate Transition (/docs/components/shader-reveal-noise-transition)
## Features [#features]
* Persistent WebGL transition wrapper triggered by a `transitionKey`
* Adapts a shader image-transition technique into a SmoothUI frame transition
* Preserves semantic React content and swaps at the shader midpoint
* Accessible: honors `prefers-reduced-motion` and fires `onRest`
## Usage guidance [#usage-guidance]
Use it for meaningful product state changes where a shader-led transition should feel intentional, not decorative. The component translates image-transition shader techniques into a frame-level overlay that can wrap arbitrary React content.
## Props [#props]
# Planetary Swirl Transition (/docs/components/shader-reveal-planetary-transition)
## Features [#features]
* Persistent WebGL transition wrapper triggered by a `transitionKey`
* Adapts a shader image-transition technique into a SmoothUI frame transition
* Preserves semantic React content and swaps at the shader midpoint
* Accessible: honors `prefers-reduced-motion` and fires `onRest`
## Usage guidance [#usage-guidance]
Use it for meaningful product state changes where a shader-led transition should feel intentional, not decorative. The component translates image-transition shader techniques into a frame-level overlay that can wrap arbitrary React content.
## Props [#props]
# Noise Push Transition (/docs/components/shader-reveal-push-transition)
## Features [#features]
* Persistent WebGL transition wrapper triggered by a `transitionKey`
* Adapts a shader image-transition technique into a SmoothUI frame transition
* Preserves semantic React content and swaps at the shader midpoint
* Accessible: honors `prefers-reduced-motion` and fires `onRest`
## Usage guidance [#usage-guidance]
Use it for meaningful product state changes where a shader-led transition should feel intentional, not decorative. The component translates image-transition shader techniques into a frame-level overlay that can wrap arbitrary React content.
## Props [#props]
# Stripe Shutter Transition (/docs/components/shader-reveal-stripes-transition)
## Features [#features]
* Persistent WebGL transition wrapper triggered by a `transitionKey`
* Adapts a shader image-transition technique into a SmoothUI frame transition
* Preserves semantic React content and swaps at the shader midpoint
* Accessible: honors `prefers-reduced-motion` and fires `onRest`
## Usage guidance [#usage-guidance]
Use it for meaningful product state changes where a shader-led transition should feel intentional, not decorative. The component translates image-transition shader techniques into a frame-level overlay that can wrap arbitrary React content.
## Props [#props]
# Shader Reveal Transition (/docs/components/shader-reveal-transition)
## Features [#features]
* Persistent WebGL transition wrapper triggered by a `transitionKey`
* Eight built-in shader variants: `noise`, `zoom`, `circle`, `wipe`, `luma`, `planetary`, `stripes`, `push`
* Preserves semantic React content and swaps at the shader midpoint
* Accessible: honors `prefers-reduced-motion` and fires `onRest`
## Usage guidance [#usage-guidance]
Use it for meaningful product state changes where a shader-led transition should feel intentional, not decorative. Pick a `variant` that matches the moment — for example `circle` for a focal reveal, or `stripes` for a sharper, more mechanical cut. The eight single-purpose transition components (`ShaderRevealCircleTransition`, `ShaderRevealNoiseTransition`, etc.) wrap this same engine with a fixed variant if you don't need to switch variants at runtime.
## Accessibility [#accessibility]
When reduced motion is preferred, content swaps immediately and `onRest` still fires.
## Props [#props]
# Displacement Wipe Transition (/docs/components/shader-reveal-wipe-transition)
## Features [#features]
* Persistent WebGL transition wrapper triggered by a `transitionKey`
* Adapts a shader image-transition technique into a SmoothUI frame transition
* Preserves semantic React content and swaps at the shader midpoint
* Accessible: honors `prefers-reduced-motion` and fires `onRest`
## Usage guidance [#usage-guidance]
Use it for meaningful product state changes where a shader-led transition should feel intentional, not decorative. The component translates image-transition shader techniques into a frame-level overlay that can wrap arbitrary React content.
## Props [#props]
# Zoom Wash Transition (/docs/components/shader-reveal-zoom-transition)
## Features [#features]
* Persistent WebGL transition wrapper triggered by a `transitionKey`
* Adapts a shader image-transition technique into a SmoothUI frame transition
* Preserves semantic React content and swaps at the shader midpoint
* Accessible: honors `prefers-reduced-motion` and fires `onRest`
## Usage guidance [#usage-guidance]
Use it for meaningful product state changes where a shader-led transition should feel intentional, not decorative. The component translates image-transition shader techniques into a frame-level overlay that can wrap arbitrary React content.
## Props [#props]
# Shared Axis X (/docs/components/shared-axis-x)
## Features [#features]
* Smooth horizontal enter/exit transitions between cycling phrases
* Material-inspired directional continuity
* Respects `prefers-reduced-motion`
* Announces updates via `aria-live="polite"`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, phrases swap instantly with no translation or scale. The current phrase is announced via `aria-live="polite"`.
## Props [#props]
# Word Cut Staircase (/docs/components/shared-axis-y)
## Features [#features]
* Hard-cut per-word opacity flips with staircase stagger timing
* Sharp, editorial feel with no easing curves
* Respects `prefers-reduced-motion`
* Announces updates via `aria-live="polite"`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, phrases swap instantly with no stagger. The current phrase is announced via `aria-live="polite"`.
## Props [#props]
# Shared Axis Z (/docs/components/shared-axis-z)
## Features [#features]
* Scale and blur enter/exit between cycling phrases
* Communicates depth and focus shift through the Z axis
* Respects `prefers-reduced-motion`
* Announces updates via `aria-live="polite"`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, phrases swap instantly with no scale or blur. The current phrase is announced via `aria-live="polite"`.
## Props [#props]
# Shimmer Sweep (/docs/components/shimmer-sweep)
## Features [#features]
* Whole-text fade-in with a left-to-center slide and blur dissolve
* Smooth ease-out curve (`cubic-bezier(0.22, 1, 0.36, 1)`)
* Configurable delay
* Optional scroll-trigger via `triggerOnView`
* Accessible: respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the text renders immediately at full opacity with no slide or blur. The full string is exposed to screen readers via `aria-label`, with the animated span `aria-hidden`.
## Props [#props]
# Shine Text (/docs/components/shine-text)
## Features [#features]
* A bright highlight band sweeps across the text on a continuous loop
* Clipped moving gradient (`background-clip: text`) — works on any string
* Configurable `duration`, `repeatDelay`, `baseColor`, and `shineColor`
* Theme-aware defaults (muted base, foreground shine)
* Accessible: respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the text renders statically in `baseColor` with no sweeping gradient.
## Props [#props]
# Short Slide Down (/docs/components/short-slide-down)
## Features [#features]
* Word-by-word vertical build with top-entry and downward push
* Each word occupies its own centered line
* Layout-animated stacking as words are added
* Soft blur entry and bottom-exit per word
* Respects `prefers-reduced-motion`
* Announces updates via `aria-live="polite"`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the full phrase appears at once and swaps instantly. The current phrase is announced via `aria-live="polite"`.
## Props [#props]
# Short Slide Right (/docs/components/short-slide-right)
## Features [#features]
* Shared horizontal container translation with per-word opacity stagger
* Compact travel distance keeps motion editorial, not swishy
* Clean exit with slight rightward drift and blur
* Respects `prefers-reduced-motion`
* Announces updates via `aria-live="polite"`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, phrases swap instantly with no translation or opacity stagger. The current phrase is announced via `aria-live="polite"`.
## Props [#props]
# Siri Orb (/docs/components/siri-orb)
## Features [#features]
Six layered conic gradients animated through a registered `--angle` property. Reads the shared `AIState` contract and reacts to a live `amplitude` signal.
Scroll the sections below — the panel shows one state at a time with simulated amplitude.
## States [#states]
### Idle [#idle]
Slow rotation, slightly desaturated — the resting assistant.
### Listening [#listening]
Grows and fully reactive to amplitude — the orb focuses when audio is present.
### Thinking [#thinking]
Rotation speeds up 2.2× with **no size change**, so the layout stays calm while work happens.
### Streaming [#streaming]
Gentle pulse in sync with output — a softer, breathing motion.
### Done [#done]
One settle overshoot when a task completes.
### Error [#error]
Desaturates and shakes once, under 200ms.
## Real audio reactivity [#real-audio-reactivity]
`amplitude` accepts a plain number or the `MotionValue` returned by `useAudioAmplitude`.
Prefer the `MotionValue`: it updates outside React, so a 60fps audio signal never triggers
a re-render.
```tsx
"use client";
import { useAudioAmplitude } from "@/components/smoothui/ai-core";
import SiriOrb from "@/components/smoothui/siri-orb";
export const VoiceButton = () => {
const { amplitude, status, start, stop } = useAudioAmplitude();
const isActive = status === "active";
return (
(isActive ? stop() : start())} type="button">
);
};
```
When a permission prompt would be hostile — docs, marketing pages, previews — use
`useSimulatedAmplitude(state)` instead. It produces a speech-like envelope whose energy
follows the current state, so the reactive behaviour is visible without asking for
anything.
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Uses `useReducedMotion` alongside a CSS `@media (prefers-reduced-motion: reduce)` rule.
When enabled, rotation pauses, amplitude reactivity is disabled and state changes apply
instantly. This is a purely decorative component with no interactive or semantic content.
## Props [#props]
# Social Hover Card (/docs/components/social-hover-card)
## Features [#features]
* Opens on hover (with a configurable `openDelay`) on hover-capable pointers, and on focus or click otherwise
* `placement="auto"` measures available viewport space and flips between top and bottom
* The card scales up from a `transform-origin` derived from its resolved placement
* Numeric stats roll up from zero when the card opens
* The follow button morphs its label between "Follow" and "Following" with a width `layout` animation
* Works controlled (`following` / `onFollowChange`) or uncontrolled
* `loading` renders a skeleton card in place of real content
* Fully respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| ------------------------------- | -------------- | --------------------------------------------------------------------------------- |
| `aria-expanded` | Trigger | Reflects whether the preview card is open |
| `aria-haspopup="dialog"` | Trigger | Announces that activating it opens a dialog-like preview |
| `role="dialog"` | Card | Applied only when the card was opened via focus, since it is then focus-reachable |
| `aria-label` | Card | Names the dialog as "`{name}` profile preview" when it has the dialog role |
| `aria-pressed` | Follow button | Reflects the current follow state |
| `aria-label="Verified account"` | Verified badge | Announces the verified badge to assistive technology |
### Keyboard Interactions [#keyboard-interactions]
| Key | Description |
| ----------------- | -------------------------------------------------------------------------- |
| `Tab` | Moves focus to the trigger, then into the card's follow button |
| `Enter` / `Space` | Activates the trigger (on non-hover-capable pointers) or the follow button |
| `Escape` | Closes the card and returns focus to the trigger |
### Screen Reader [#screen-reader]
* The trigger is a real `` with `aria-expanded` and `aria-haspopup`, so its state is announced without relying on visual cues.
* The card only takes the `dialog` role when it was opened through keyboard focus, since a hover-triggered preview is not focus-trapped and should not be announced as a modal.
* Stat values are rendered as plain text nodes, so the animated count-up does not interfere with the final announced value.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the card fades in with opacity only (no scale), and stat numbers render their final value immediately instead of rolling up.
## Props [#props]
# Social Selector (/docs/components/social-selector)
## Features [#features]
* Animated select/deselect
* Icon and label variants
* Keyboard and screen reader support
* Responsive layout
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| ------------ | ---------------- | ------------------------------------------------ |
| `aria-label` | Platform buttons | Describes the action (e.g., "Select X platform") |
### Screen Reader [#screen-reader]
* Each platform icon button contains a visually hidden `` with the platform name.
* SVG icons include `` elements (e.g., "X icon", "Bluesky icon", "Threads icon").
* External links use `rel="noopener noreferrer"` for security.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the background pill sliding animation and the domain text blur/slide transitions are disabled.
## Props [#props]
# Soft Blur In (/docs/components/soft-blur-in)
## Features [#features]
* Per-character fade-in with a soft blur and upward drift
* Apple keynote-style hero reveal (`cubic-bezier(0.22, 1, 0.36, 1)`)
* Configurable delay and per-character stagger
* Optional scroll-trigger via `triggerOnView`
* Accessible: respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the text renders immediately at full opacity with no blur or movement. The full string is exposed to screen readers via `aria-label`, with the per-character spans `aria-hidden`.
## Props [#props]
# Spring Scale In (/docs/components/spring-scale-in)
## Features [#features]
* Per-word scale-in with a soft overshoot (`cubic-bezier(0.34, 1.56, 0.64, 1)`)
* iOS home screen / Dock-inspired bounce pop
* Configurable delay and per-word stagger
* Optional scroll-trigger via `triggerOnView`
* Accessible: respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the text renders immediately at full opacity with no scale animation. The full string is exposed to screen readers via `aria-label`, with the per-word spans `aria-hidden`.
## Props [#props]
# Squircle (/docs/components/squircle)
## Features [#features]
Corners follow a superellipse (squircle) curve instead of a circular arc — the curvature-continuous shape Apple uses for app icons and tiles. `smoothing` maps to the superellipse exponent from `0` (circular) to `1` (maximum spread).
## Variants [#variants]
Scroll the sections below — the panel shows one configuration at a time.
### Tile [#tile]
A single squircle tile at the default smoothing — the simplest use case.
### Smoothing [#smoothing]
Drag the slider to see smoothing change in real time — at `0.00` the corner is exactly a circular arc.
### Comparison [#comparison]
Side-by-side: `border-radius` with a dashed squircle overlay versus the actual clipped squircle at the same radius.
### App Icons [#app-icons]
Six app-icon tiles at a fixed smoothing — shows how squircles scale to small radii.
## Notes [#notes]
The shape is always the generated `clip-path`, never CSS `corner-shape`. `corner-shape: squircle` is a single fixed shape that ignores `smoothing`, so switching to it where supported made identical props render two different corners depending on the browser.
Because the element is clipped, anything drawn at its very edge is clipped too: a 1px CSS `border` renders as a hairline. For a crisp outline, stroke `squirclePath()` in an SVG overlay instead.
The effect is proportional — it is only visible when the radius is a meaningful fraction of the element. On a 24px chip with an 8px radius there is nothing to see; on a 200px tile with a 56px radius the difference against `border-radius` is obvious.
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
No ARIA attributes are added by `Squircle` itself — it is a purely visual wrapper and passes through whatever semantics `as` and `children` already carry.
### Screen Reader [#screen-reader]
* `Squircle` renders a single element with your `children` inside; nothing is hidden, duplicated, or reordered, so screen reader behavior is identical to not using it.
### Reduced Motion [#reduced-motion]
Not applicable. `Squircle` has no animation loop — the corner shape is computed once per size/radius/smoothing change and stays static, so `prefers-reduced-motion` has no effect on it.
## Props [#props]
# Stagger From Center (/docs/components/stagger-from-center)
## Features [#features]
* Per-character center-out reveal with subtle blur and upward drift
* Delay computed by distance from center — not linear index
* Emphasizes the core of the word for product hero use cases
* Configurable delay and per-step stagger
* Optional scroll-trigger via `triggerOnView`
* Accessible: respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the text renders immediately at full opacity with no blur or movement. The full string is exposed to screen readers via `aria-label`, with the per-character spans `aria-hidden`.
## Props [#props]
# Stagger From Edges (/docs/components/stagger-from-edges)
## Features [#features]
* Per-character edges-in reveal with subtle blur and upward drift
* Delay computed by distance from the nearest edge — characters converge to center
* Directional emphasis for modern product hero systems
* Configurable delay and per-step stagger
* Optional scroll-trigger via `triggerOnView`
* Accessible: respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the text renders immediately at full opacity with no blur or movement. The full string is exposed to screen readers via `aria-label`, with the per-character spans `aria-hidden`.
## Props [#props]
# SVG Clip Mask (/docs/components/svg-clip-mask)
## Features [#features]
* Four presets — blob, arch, diamond and wave — plus a fully custom path
* Uses `clipPathUnits="objectBoundingBox"` so the shape always scales with its box
* Three animated modes — a continuous ambient morph loop, a scroll-stepped morph, and a hover morph — plus a static "none"
* Only animates the mask's `d` attribute, which is the mask itself — no layout-affecting properties change
* Full `prefers-reduced-motion` support
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | -------------------------------------- | -------------------------------------------------------------------- |
| `aria-hidden="true"` | Hidden ``/`` definition | Hides the invisible mask-definition markup from assistive technology |
### Screen Reader [#screen-reader]
* The mask machinery lives in a zero-size, `aria-hidden` `` — it is never announced.
* `children` render in a normal, visible `` and remain fully readable and reachable regardless of the current mask shape or animation state.
### Reduced Motion [#reduced-motion]
This component respects `prefers-reduced-motion` via `useReducedMotion` from Motion. When reduced motion is preferred, the mask renders as the first path with no morphing and no scroll coupling — content is always visible through a static shape.
## Props [#props]
`animate="morph"`, `animate="scroll"` and `animate="hover"` all step between
the entries in `morphPaths`, so they need **at least two** paths to do
anything. Given one path — or none, falling back to the `shape` preset — there
is nothing to step to and the mask renders static with no error. If a mode
looks like it is doing nothing, check `morphPaths` first.
Every path must also share the same command structure — the same sequence of
`M`/`L`/`C`/`Z` and the same number of points — because browsers interpolate
matching parameters positionally. Mismatched structures snap between shapes
instead of morphing.
# SVG Draw On Scroll (/docs/components/svg-draw-on-scroll)
## Features [#features]
* Draws one path, or several in sequence, using Motion's normalised `pathLength`
* Optional marker that rides the drawn tip, positioned from the path's own geometry via `getPointAtLength` and the SVG's live transform matrix — so it stays on the stroke at any `viewBox`, not just one that happens to match the rendered box in CSS pixels
* Works against the window or any scrollable ancestor via the `container` prop
* Optional `once` mode that keeps the line drawn instead of undrawing on scroll-up
* Only animates `pathLength` (stroke geometry) and the marker's `transform` — no layout thrashing
* The marker re-syncs on resize, so it stays anchored when the SVG is laid out at a new size
* Full `prefers-reduced-motion` support
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | -------------- | --------------------------------------------------------------------- |
| `aria-hidden="true"` | `
` | Marks the decorative line drawing as hidden from assistive technology |
| `aria-hidden="true"` | Marker wrapper | Marks the decorative tip marker as hidden from assistive technology |
### Screen Reader [#screen-reader]
* The drawing is treated as decorative by default (`aria-hidden="true"` on the ``). If your path conveys real information, wrap the component with your own visible or visually-hidden text description.
* The marker never receives focus and is excluded from the accessibility tree.
### Reduced Motion [#reduced-motion]
This component respects `prefers-reduced-motion` via `useReducedMotion` from Motion. When reduced motion is preferred, every path renders fully drawn immediately and the marker is parked at the end of the path.
## Props [#props]
# Swap Panel (/docs/components/swap-panel)
## Features [#features]
* Flip button that swaps the "you pay" / "you receive" rows with a layout animation
* Output figure rolls in with a spring transition whenever the quote updates
* Shimmer loading state scoped to the output row only, never a full-panel spinner
* Countdown ring that visualizes an expiring quote
* Inline balance, fee, price impact, and slippage readouts formatted with `Intl.NumberFormat`
* Composes [Smooth Button](/docs/primitives/smooth-button) for the token chips, the flip control and the submit action
* Reduced motion support throughout
## Scope [#scope]
This component is presentation only. It performs no network calls, integrates with no wallet or crypto SDK, and never handles real balances, private keys, or signing. Every number shown — balances, rates, fees, quotes — comes directly from props supplied by the consumer, who is responsible for sourcing real data and wiring up the actual swap logic.
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | ------------------------------------------------- | ---------------------------------------------------------- |
| `aria-live="polite"` | Output figure container | Announces the updated receive amount when a quote resolves |
| `role="alert"` | Error message | Announces validation/quote errors immediately |
| `aria-label` | Flip button, token chips | Describes the flip action and the currently selected token |
| `aria-hidden="true"` | Shimmer overlay, countdown ring, decorative icons | Hides purely decorative elements from assistive technology |
### Keyboard [#keyboard]
| Key | Action |
| ----------------- | ---------------------------------------------------------------------------------- |
| `Tab` | Moves focus through the amount input, token chips, flip button, and primary action |
| `Enter` / `Space` | Activates the focused button (flip, token chip, Max, submit) |
### Screen Reader [#screen-reader]
* The amount input has a real `` tied via `htmlFor`/`id`, with `inputMode="decimal"`.
* The receive figure is tied to its heading via `aria-labelledby` and wrapped in an `aria-live="polite"` region so quote changes are announced without moving focus.
* Errors use `role="alert"` so they are announced immediately.
### Reduced Motion [#reduced-motion]
When `prefers-reduced-motion` is enabled (checked via `useReducedMotion` from Motion), the flip rotation, row layout animation, and output roll all switch to `duration: 0`. The shimmer sweep is replaced with a static muted block, and the countdown ring updates without a CSS transition.
## Props [#props]
# Switchboard Card (/docs/components/switchboard-card)
## Features [#features]
* Animated light grid with configurable dimensions
* Three light states: off, medium, high (all use brand color)
* Word pattern support - automatically generates patterns for short words (e.g., "NEXT", "REACT", "VUE")
* Custom pattern support via array of light indices
* Random light generation for dynamic effects
* Next.js-style variant with dark gradient background
* Smooth transitions and animations
* Fully customizable grid layout
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
* When rendered as a link (`href` prop) or button (`onButtonClick` prop), the wrapper includes `aria-label` set to the card's `title` for screen reader context.
* Focus-visible ring styles (`focus-visible:ring-2`) provide clear keyboard focus indication on interactive card variants.
### Reduced Motion [#reduced-motion]
The light grid uses CSS transitions (`opacity` and `transform`) with configurable `transitionDuration`. There is no explicit `prefers-reduced-motion` check at the JavaScript or CSS level. The animations are subtle opacity/scale transitions rather than layout-shifting motion.
## Props [#props]
## Usage [#usage]
### Basic Usage [#basic-usage]
```tsx
import SwitchboardCard from "@repo/smoothui/components/switchboard-card";
```
### With Grid Pattern (Simplest) [#with-grid-pattern-simplest]
The easiest way to customize is to pass a grid pattern directly. You can use either:
* A 2D array `[rows][columns]` where each cell is `0` (off) or `1` (high)
* A flat array of length `columns * rows` where each element is `0` (off) or `1` (high)
```tsx
// Using 2D array [5 rows][18 columns]
const nextPattern = [
[1,1,0,0,0,0,0,1,1,1,0,0,0,1,1,1,1,1], // Row 0
[1,0,1,0,0,0,0,1,0,0,0,0,0,0,0,0,1,0], // Row 1
[1,0,0,1,0,0,0,1,1,1,0,0,0,0,0,0,1,0], // Row 2
[1,0,0,0,1,0,0,1,0,0,0,0,0,0,0,0,1,0], // Row 3
[1,1,1,1,1,0,0,1,1,1,0,0,0,1,1,1,1,1], // Row 4
];
// Or using flat array
const flatPattern = Array(90).fill(0).map((_, i) => {
// Your logic to determine which lights should be on
return i % 10 === 0 ? 1 : 0;
});
```
### With Word Pattern [#with-word-pattern]
The easiest way to display a word is to use the `word` prop. The component will automatically generate the pattern:
```tsx
```
Supported letters: N, E, X, T, R, A, C, V, U (more can be added)
### With Custom Pattern [#with-custom-pattern]
For full control, you can define custom light patterns by passing an array of light indices:
```tsx
const customPattern = [15, 19, 26, 29, 34, 55, 60, 70, 74, 83];
```
### Random Lights [#random-lights]
For a dynamic effect, use `randomLights`:
```tsx
```
### Interactive Card [#interactive-card]
Make the card clickable with `href` or `onButtonClick`:
```tsx
```
# Text Morph (/docs/components/text-morph)
## Features [#features]
* Character or word-level diffing between the previous and current `text`
* Shared tokens keep their identity and slide via layout animation instead of re-animating
* Removed tokens shrink out, added tokens spring in
* The surrounding wrapper width animates smoothly so nearby content never jumps
* Exiting tokens resolve against the component's own box, so they always animate out in place instead of escaping to a corner of the page
* Per-token stagger is capped, so a long sentence morphs as briskly as a short label
* Exits are shorter than entrances, so removed tokens clear out of the way instead of trailing behind
* Respects `prefers-reduced-motion` with an instant swap
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | ------------------------- | ------------------------------------------------------------ |
| `class="sr-only"` | Visually hidden text node | Exposes the full, intact string once to assistive technology |
| `aria-hidden="true"` | Per-token spans | Hides the fragmented, animated tokens from screen readers |
### Screen Reader [#screen-reader]
* The wrapper renders the current string once as visually hidden text, so screen readers announce it as a single, coherent phrase. An `aria-label` would not work here: it is prohibited on the generic roles that the default `as="span"` (and `as="div"`) produce, so assistive technology would drop it and — with every token `aria-hidden` — announce nothing at all.
* The animated character or word spans underneath are `aria-hidden`, so nothing is read out twice or letter-by-letter.
* The text remains selectable in the DOM at all times.
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the component renders the final string directly with no token splitting, no layout animation, and no spring transitions.
## Props [#props]
# Theme Toggle (/docs/components/theme-toggle)
## Features [#features]
Four variants built from different primitives so they never look like the same grey pill. Binary and three-way modes, three sizes, controlled or uncontrolled — and it never writes to `document.documentElement` or `localStorage`. Wire `onThemeChange` to your own theme provider (e.g. `next-themes`).
## Variants [#variants]
Each treatment is a different control. Scroll the sections below — the panel shows one at a time.
### Sun Moon [#sun-moon]
A single filled disc carved by a masking circle that slides across it. The disc radius, the mask radius and the mask position all animate together, so the sun grows into a crescent instead of crossfading two icons. Eight rays retract into the disc with a stagger while the whole ray group rotates.
### Pill [#pill]
A segmented control with icons *and* labels. The active thumb is a `layoutId` element with real elevation (drop shadow plus a hairline ring), so it physically travels between segments, and each icon shifts to its own hue as the thumb lands under it (amber for light, indigo for dark).
### Switch [#switch]
A real track-and-knob switch. The track cross-fades a sky gradient into a night gradient, has an inset shadow for depth, and fades in tiny stars on the dark end. The knob is a gradient sphere with a specular highlight and a layered shadow; it travels on a spring while the icon inside rotates through the transition.
### Orb [#orb]
A lit sphere: radial-gradient body, a specular highlight that travels across the surface as the theme changes, craters that fade in on the dark side, an inset terminator shadow and a soft coloured bloom cast beneath it.
## Modes [#modes]
### Binary [#binary]
`showSystem={false}` — light and dark only. Best for a header chip that should never land on “system”.
### Three-way [#three-way]
`showSystem` (the default) — light, dark and system. On `sun-moon` and `orb` the control cycles; on `pill` and `switch` system is a third segment / stop.
## Accessibility [#accessibility]
`pill` and `switch` expose their options directly as a `role="radiogroup"` of radio buttons (the `switch` places invisible full-height radio hit areas over the track). `sun-moon` and `orb` are single-shape controls, so they render one `` that cycles to the next option and announces the change through a polite live region.
### Keyboard Interactions [#keyboard-interactions]
| Key | Description |
| ---------------------------- | ------------------------------------------------------------------------------- |
| `Space` / `Enter` | Activates the focused control — selects a radio, or advances the cycling button |
| `Arrow Left` / `Arrow Up` | Moves to the previous option |
| `Arrow Right` / `Arrow Down` | Moves to the next option |
| `Home` / `End` | Jumps to the first / last option (`pill` and `switch`) |
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| ------------------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `role="radiogroup"` | Container | Identifies the `pill` / `switch` option set |
| `role="radio"` / `aria-checked` | Each option | Exposes each theme option's selection state |
| `aria-pressed` | Cycling button | Exposes the on/off state of `sun-moon` / `orb` in binary mode |
| `aria-label` | Button(s) | Names the option, or — for the cycling button — the current theme and the one it will switch to |
| `aria-live="polite"` | Status text | Announces the newly selected theme after any change |
### Screen Reader [#screen-reader]
* Every decorative layer (mask, rays, glow, thumb, stars, knob highlight, orb bloom, craters, specular) is `aria-hidden` and non-focusable.
* Every interactive element is a real ``, so pressed/checked state is announced automatically.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the mask morph, ray retraction, thumb travel, knob spring, icon rotation, star fade, specular travel and bloom colour change all resolve instantly with no transition.
## Props [#props]
# Tilt Card (/docs/components/tilt-card)
## Features [#features]
* Pointer position drives `rotateX`/`rotateY` via motion values, smoothed with a spring
* Optional glare highlight that follows the cursor using `useMotionTemplate`
* Optional parallax: any nested element with `data-tilt-depth="0..1"` translates proportionally to its depth
* Responds to keyboard focus on a nested focusable element with a subtle fixed tilt, so the effect is not hover-only
* Touch and non-hover devices, and `prefers-reduced-motion`, render completely flat with no glare and no pointer/focus listeners attached
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------- | ------------- | ---------------------------------------------------------- |
| `aria-hidden="true"` | Glare overlay | Hides the decorative glare layer from assistive technology |
### Screen Reader [#screen-reader]
* `TiltCard` only wraps `children` — it adds no roles or focus traps of its own, so any interactive content you place inside (links, buttons) keeps its native semantics.
* The tilt-on-focus behavior listens for focus bubbling from a nested focusable element rather than adding a redundant tab stop on the card itself.
### Reduced Motion [#reduced-motion]
When `prefers-reduced-motion` is enabled, or the device lacks fine hover/pointer support, `TiltCard` never sets rotation, scale, or glare values and does not attach pointer or focus listeners at all — the card renders completely flat.
## Props [#props]
# Time Machine Stack (/docs/components/time-machine-stack)
## Features [#features]
* Panels recede into a 3D perspective stack through scale, vertical offset and z-translation — never through opacity. Every panel is fully opaque and backed by a solid surface, so it occludes the one behind it, which is what makes a stack read as a stack rather than as overlapping ghosts
* Opacity is spent only where it describes something real: the single panel entering or leaving the visible window. Panels inside the window always resolve to exactly `1`, so an interrupted step can never strand one half-faded
* Fills its container in both axes, so the focused panel can be a full-size card rather than a thumbnail
* Reserves headroom for the receding panels and anchors every panel to the bottom edge, so the depth is always visible behind the front one
* Direction-aware enter/exit: travelling forward the front panel flies past the viewer, travelling back it falls in from the front
* Navigate with trackpad/mouse wheel, Arrow Up / Down, Home / End, or vertical drag
* The wheel is handed back to the page at either end of the stack, so it never traps the document scroll
* Fully controlled or uncontrolled `index`
* Items beyond `visibleCount` are unmounted, not just visually hidden
* Smooth spring transitions as panels enter and leave the visible window, driven by a single `transform` string so the depth animation stays on the compositor
* Accessible listbox semantics with a live region announcing position
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| --------------------------------- | --------------------------- | -------------------------------------------------------- |
| `role="listbox"` | Stack container | Identifies the stack as a single-selection listbox |
| `aria-activedescendant` | Stack container | Points to the id of the front-most (selected) panel |
| `role="option"` | Each panel | Identifies each panel as a selectable option |
| `aria-selected` | Each panel | Marks the front panel as the current selection |
| `aria-label="Time machine stack"` | Stack container | Gives the widget a descriptive name |
| `aria-live="polite"` | Visually-hidden status text | Announces "Item N of M" whenever the front panel changes |
### Keyboard [#keyboard]
| Key | Action |
| --------------------- | -------------------------------------- |
| Arrow Down | Move to the next (deeper) item |
| Arrow Up | Move to the previous item |
| Home | Jump to the newest (first) item |
| End | Jump to the oldest (last) item |
| Tab | Move focus to/from the stack container |
### Screen Reader [#screen-reader]
* The stack container is focusable (`tabIndex={0}`) and exposes `role="listbox"` with `aria-activedescendant` so screen readers announce the currently focused option.
* A visually-hidden `aria-live="polite"` region announces "Item N of M" every time navigation changes the front-most item.
### Reduced Motion [#reduced-motion]
This component respects `prefers-reduced-motion` via `useReducedMotion` from Motion. When reduced motion is preferred, the 3D depth (scale, vertical offset, and z-translation) is removed and panels cross-fade instantly between states instead of animating through the stack.
## Props [#props]
# Top Down Letters (/docs/components/top-down-letters)
## Features [#features]
* Per-character top-down staircase reveal with zero blur
* Pronounced staging at 88ms stagger for deliberate, one-letter-at-a-time rhythm
* Configurable delay and per-character stagger
* Optional scroll-trigger via `triggerOnView`
* Accessible: respects `prefers-reduced-motion`
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, the text renders immediately at full opacity with no movement. The full string is exposed to screen readers via `aria-label`, with the per-character spans `aria-hidden`.
## Props [#props]
# Tweet Card (/docs/components/tweet-card)
## Features [#features]
* Beautiful tweet card design with full-width images
* Hover-activated external link button positioned at bottom-right
* Support for tweets with images, videos, and text
* Server-side and client-side rendering options
* Loading and error states included
* Fully customizable styling
* Configurable user info position (top or bottom)
* Customizable avatar rounded style
* Accessible with proper ARIA labels
* Consistent 24px padding on all sides
## Accessibility [#accessibility]
### Semantic HTML [#semantic-html]
Uses `` as the root element and `` for tweet text, providing meaningful document structure for assistive technologies.
### ARIA Attributes [#aria-attributes]
* The external link button includes `aria-label="Open tweet in new tab"` for screen reader context.
* Decorative SVG icons use `aria-hidden="true"` to hide them from the accessibility tree.
* All external links include `rel="noreferrer"` or `rel="noopener noreferrer"` for security.
### Reduced Motion [#reduced-motion]
The hover-activated link button uses Tailwind's `motion-safe:hover:scale-110` utility, which automatically disables the scale animation when `prefers-reduced-motion` is enabled. There is no additional JavaScript-level `useReducedMotion` check, as animations are CSS-only.
## Props [#props]
## Usage [#usage]
### Client-Side (Recommended) [#client-side-recommended]
Use `ClientTweetCard` for client-side rendering:
```tsx
import { ClientTweetCard, TweetSkeleton } from "@repo/smoothui/components";
export function MyComponent() {
return (
}
/>
);
}
```
### Server-Side [#server-side]
Use `TweetCard` for server-side rendering:
```tsx
import { TweetCard } from "@repo/smoothui/components";
export default async function MyPage() {
return (
);
}
```
## Configuration Options [#configuration-options]
### User Info Position [#user-info-position]
Control where the user information (avatar and name) appears in the card:
```tsx
// User info at bottom (default)
}
/>
// User info at top
}
/>
```
### Avatar Rounded Style [#avatar-rounded-style]
Customize the avatar's border radius:
```tsx
// Rounded corners (default)
}
/>
// Fully rounded (circle)
}
/>
// Large rounded corners
}
/>
// Medium rounded corners
}
/>
```
### Combined Configuration [#combined-configuration]
Use both props together for different layouts:
```tsx
// Top position with circular avatar
}
/>
// Bottom position with large rounded corners
}
/>
```
## Examples [#examples]
### Default Configuration [#default-configuration]
Default layout with user info at bottom and rounded avatar:
```tsx
}
/>
```
### User Info at Top [#user-info-at-top]
Display user information at the top of the card:
```tsx
}
/>
```
### Circular Avatar [#circular-avatar]
Use a fully rounded (circular) avatar:
```tsx
}
/>
```
### Top Position with Circular Avatar [#top-position-with-circular-avatar]
Combine top position with circular avatar:
```tsx
}
/>
```
## Grid Layout [#grid-layout]
Display multiple tweets in a grid with different configurations:
```tsx
import { ClientTweetCard, TweetSkeleton } from "@repo/smoothui/components";
export function TweetGrid() {
return (
}
/>
}
/>
}
/>
);
}
```
# Typewriter Text (/docs/components/typewriter-text)
## Features [#features]
* Progressive character reveal with configurable speed
* Optional looping with pauses
* Works with headings, paragraphs, and inline text
* Built with Framer Motion
* Accessible and performant
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Respects the `prefers-reduced-motion` media query via a custom `useReducedMotion` hook. When enabled, the full text is displayed immediately without the character-by-character reveal animation.
## Props [#props]
# Unlock Face ID (/docs/components/unlock-face-id)
## Scope [#scope]
This is a **visual-only** component. It does not perform any biometric capture,
camera access, or authentication — there is no face detection, no permissions
requested, and no data collected. `status`, `onScan`, and `onComplete` are
plain UI hooks meant to be wired to your own (real) auth logic. Treat it as a
skeuomorphic loading/success/error state machine, not a security feature.
## The glyph [#the-glyph]
The mark follows Apple's Face ID icon rather than a generic smiley:
* A rounded-square frame built from **four corner brackets only** — no full outline — with a clear gap along the middle of every edge
* Inside it, a small centred schematic face with generous padding: two short vertical eye strokes, a nose formed by a vertical stroke that turns right at the bottom, and a shallow smile with small upward ticks at each end
* One uniform stroke width with round caps and joins, monochrome throughout, so the brackets and the face read as a single mark
## Features [#features]
* The four brackets draw in first with a stagger, then the face strokes draw with `pathLength`
* A brand-tinted scan band with a crisp leading line sweeps up and down inside a clipped, rounded frame while `status` is `"scanning"`
* On success the whole glyph springs out and a checkmark springs in, drawing itself with `pathLength`
* Error turns the strokes destructive-red and shakes the glyph once
* Gated content passed as `children` sits blurred and dimmed while locked, then resolves to sharp on unlock
* Controlled (`status` prop) or uncontrolled (internal state driven by `onScan` / `onComplete`) usage
* `role="status"` + `aria-live="polite"` announcing every state in words
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| -------------------------------------- | ------------------ | ------------------------------------------------------------------ |
| `aria-label` | Trigger `` | Names the action for assistive technology |
| `aria-busy` | Trigger `` | Announces the scanning state as busy |
| `aria-describedby` | Trigger `` | Links the button to the live status message |
| `role="status"` + `aria-live="polite"` | Status paragraph | Announces idle/scanning/success/error changes without interrupting |
### Screen Reader [#screen-reader]
* The trigger is a real ``, fully keyboard operable and focusable, and it is disabled while scanning or once unlocked so it cannot be re-fired.
* Every status transition is announced in plain words ("Ready to scan.",
"Scanning face…", "Identity confirmed. Unlocked.", or the custom
`errorMessage`) via the `role="status"` live region.
* The SVG is `aria-hidden`, so the brackets, face strokes, scan band and check are never read out as redundant graphic internals — the button's `aria-label` carries the meaning.
### Reduced Motion [#reduced-motion]
This component respects `prefers-reduced-motion` via `useReducedMotion` from
Motion. When reduced motion is preferred: the bracket and face strokes render
fully drawn with no stagger, the scan band is not rendered at all, the shake on
error is skipped, the face-to-check swap resolves instantly, and the gated
content snaps between blurred and sharp with no transition.
## Props [#props]
# User Account Avatar (/docs/components/user-account-avatar)
## Features [#features]
* Image with fallback support
* Multiple sizes
* Customizable fallback text
* Group avatars support
* Status indicators
* Built on Radix UI Avatar
## Accessibility [#accessibility]
### Keyboard Interactions [#keyboard-interactions]
| Key | Description |
| ----------------- | --------------------------------------------------- |
| `Enter` / `Space` | Toggle the "Edit Profile" or "Last Orders" sections |
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| ------------------------- | ----------------- | ------------------------------------------------- |
| `aria-label="View Order"` | View order button | Labels the order detail button for screen readers |
| `htmlFor` | Form labels | Associates labels with their form inputs |
| `type="button"` | All buttons | Prevents implicit form submission |
| `type="submit"` | Save button | Submits the profile edit form |
### Screen Reader [#screen-reader]
* The popover is built on Radix UI Popover, which manages focus trapping, return focus, and escape-to-close automatically.
* Form inputs include proper `label` elements linked via `htmlFor`/`id` attributes.
* Section toggle buttons include keyboard event handlers (`onKeyDown`) for `Enter` and `Space` keys.
* The avatar image includes an `alt="User Avatar"` attribute.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred, section expand/collapse animations, progress bar animations, and height transitions are all disabled instantly.
## Props [#props]
# Vector Editor Toolbar (/docs/components/vector-editor-toolbar)
## Features [#features]
* Controlled or uncontrolled active tool, matching a top-level tool or a nested flyout item
* A `layoutId` pill travels to the selected tool. It is a sibling of the button inside a fixed 36px cell, not a child of it, so it is always exactly cell-sized no matter which tool is active
* Tools with `items` are marked by a corner triangle and keep the same 36px footprint as every other tool, so adding a flyout never knocks the icon grid out of rhythm
* Three ways into a flyout: long-press the tool, click the corner triangle, or click a tool that is already active. From the keyboard, `ArrowDown` (horizontal) or `ArrowRight` (vertical)
* Flyouts are centred under their trigger, carry a caret pointing back at it, and scale from that edge via `transform-origin` rather than from their own centre
* The active cell adopts the icon and label of the variant last chosen from its flyout
* The contextual properties panel floats below (or beside) the toolbar in its own layer, so revealing and hiding it never moves the tools and nothing is ever clipped
* Single-key shortcuts bound on `document`, automatically ignored while typing in an input, textarea, select, or contenteditable element
* Optional `floating` mode pins the toolbar near the top of its positioned ancestor and makes it draggable. The overlay is click-through, so a canvas underneath stays fully interactive
* Horizontal or vertical orientation
* Full reduced-motion support
## Usage [#usage]
The toolbar reports the active tool and nothing else — the surface it drives owns
its own state. Wire `onToolChange` to whatever the tool is supposed to do, and
pass `properties` for the row that belongs to the current tool.
```tsx
import VectorEditorToolbar from "@/components/smoothui/ui/vector-editor-toolbar";
const [activeTool, setActiveTool] = useState("select");
: undefined}
tools={tools}
/>
;
```
Nested items are selected by their own id, so `activeTool` can be
`"shape-ellipse"` rather than `"shape"` — the pill still resolves to the parent
cell, and that cell borrows the ellipse icon.
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| ---------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `role="toolbar"` | Toolbar container | Identifies the group as a toolbar for assistive technology |
| `aria-orientation` | Toolbar container | Communicates horizontal or vertical layout |
| `aria-label="Vector editor tools"` | Toolbar container | Gives the toolbar an accessible name |
| `aria-label` | Every tool and flyout item button | Announces the tool's name since buttons are icon-only |
| `aria-pressed` | Every tool and flyout item button | Announces whether that tool is the current selection |
| `aria-haspopup="menu"` / `aria-expanded` | Tool buttons with nested items | Announces that the tool reveals a flyout and whether it is open |
| `aria-label` | Corner triangle button | Named after its tool (e.g. "Pen options") rather than hidden, since a control that does something should not be removed from the tree |
| `aria-label` | Flyout panel | Names the flyout after its parent tool (e.g. "Pen options") |
### Keyboard [#keyboard]
| Key | Context | Action |
| -------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------- |
| `ArrowRight` / `ArrowLeft` | Horizontal toolbar | Moves roving focus between tools |
| `ArrowDown` / `ArrowUp` | Vertical toolbar | Moves roving focus between tools |
| `ArrowDown` (horizontal) / `ArrowRight` (vertical) | Focused tool with nested items | Opens the flyout and focuses its first item |
| `ArrowDown` / `ArrowUp` | Open flyout | Moves focus between flyout items |
| `Enter` / `Space` | Focused tool or flyout item | Selects it |
| `Escape` | Open flyout | Closes it and returns focus to the tool that opened it |
| Single letter (e.g. `V`, `P`, `R`) | Anywhere outside editable fields | Selects the matching tool or flyout item, when `shortcutsEnabled` is true |
### Screen Reader [#screen-reader]
* Every tool and flyout item is a real `` with a descriptive `aria-label`, so icon-only controls are still announced by name.
* `aria-pressed` reflects the current selection on both the top-level tool and, when applicable, the nested item that is active.
* The toolbar uses roving `tabIndex` (`0` on the current tool, `-1` on the rest), so a single `Tab` press moves in and out of the whole toolbar instead of stopping on every button.
* The corner triangle is kept out of the tab order but is not `aria-hidden`: it has a name and it acts, and the same flyout is reachable from the tool button itself with an arrow key.
* The toolbar is fully operable from the keyboard. A canvas it drives is a separate concern — pointer-driven drawing surfaces need their own keyboard story, which the example does not attempt.
### Reduced Motion [#reduced-motion]
This component respects the `prefers-reduced-motion` media query via `useReducedMotion` from Motion. When reduced motion is preferred:
* The active-tool pill appears instantly at its new position instead of travelling with a spring.
* Flyouts and the properties panel appear and disappear instantly instead of animating scale, offset, and opacity.
* The press-scale on tool buttons is dropped via `motion-reduce` utilities.
* Dragging the floating toolbar is unaffected, since it is direct user manipulation rather than an automated animation.
## Props [#props]
# Video Ambient (/docs/components/video-ambient)
## Features [#features]
* Two glow passes from one 24×14 grab: an inner glow hugging the player, and a much larger, softer, more saturated bloom behind it
* The glow tracks the scene — cut to a different shot and the whole surrounding surface changes colour
* `gain` composites the sampled frame onto itself with `lighter`, so the glow reads as emitted light instead of a colour wash — this is the difference between a lamp and a tinted filter
* `saturation` pushes the bloom past the source's own colour, the way a real Ambilight does
* No pixel data is ever read back, so the effect keeps working against sources with no CORS headers
* Falls back to a blurred poster, or a theme-coloured gradient, if `drawImage` itself is blocked
* Sampling is a throttled `requestAnimationFrame` loop that stops when the video pauses, scrolls off screen, or the tab is hidden
* `glow` turns the whole effect off, which makes an A/B toggle a one-liner
## Usage notes [#usage-notes]
* **Give it a dark surface, and give it room.** The bloom scales to roughly twice the player's box, so a tight wrapper clips the effect and a light background leaves nothing for it to read against — an ambient light needs somewhere dim to spill into. Treat that dark surface as the component's own canvas, bleeding to the edges of whatever region it occupies, rather than as a card floating inside a lighter one.
* **Playback state is read from the element**, not assumed — a video already playing when the component mounts still drives the loop, and a rejected autoplay leaves the controls to the user.
* `sampleRate` defaults to 12/s. Four `drawImage` calls into a 24×14 canvas is negligible, but the CSS blur behind them is not free — lower it for a background loop.
* **A poster is optional but recommended.** Until the first frame is sampled the glow falls back to a blurred poster, or a theme-coloured radial gradient when there is none. The demo omits it on purpose, so you can see that fallback.
* **Push `saturation`, not `gain`, for more colour.** `gain` adds luminance, so on bright footage it drives the bloom toward white and the surrounding surface washes out. `saturation` adds chroma without that cost. The demo runs `saturation={2.2}` against `gain={1.15}` for exactly this reason — the gain is lower than it would be on flatter footage, because this source already carries its own light.
* **Tune `scale` and `blur` to the space you have, not to taste.** Together they decide how far the bloom reaches: the outer pass renders at `scale × 1.55` with `blur × 1.9`. The demo runs `scale={1.45}` and `blur={46}` because it has a full dark surface to spread across; on a smaller or lighter surface, pull both down until the falloff finishes before it reaches whatever sits next to the player.
* **Colour anything sitting on that surface against the surface, not against the theme.** A dark canvas that stays dark in light mode will turn theme-driven text and controls dark-on-dark. The demo's own controls are painted in white alphas for exactly that reason, and the glow toggle sets `--btn` inline rather than taking `color="neutral"`, which resolves to the theme foreground.
* **It has to be a real `` element.** The glow is sampled with `drawImage(video, …)`, and an `
}
/>
```
## Accessibility [#accessibility]
### ARIA Attributes [#aria-attributes]
| Attribute | Element | Purpose |
| --------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `role="listbox"` | Card stack container | Identifies the stack as a single-select list |
| `role="option"` + `aria-selected` | Each card | Marks the active account for assistive tech |
| `aria-label` | Balance figure | Announces "Balance hidden" or the formatted amount instead of raw dot/character glyphs |
| `aria-hidden="true"` | Chip, contactless glyph, network mark, grain, sheen | Hides the decorative card construction from assistive technology |
| `role="img"` + `aria-label` | Avatar | Gives each member avatar an accessible name |
| `aria-expanded` / `aria-controls` | Overflow "+N" button | Exposes the disclosure state and target list |
| `aria-pressed` | Hide/show balance button | Reflects the current masking state |
### Keyboard [#keyboard]
| Key | Action |
| ---------------------------- | --------------------------------------------------------------------------------------------- |
| `Tab` | Moves focus to the active card (roving tabindex — inactive cards are not tab stops) |
| `Arrow Right` / `Arrow Down` | Moves to and activates the next card |
| `Arrow Left` / `Arrow Up` | Moves to and activates the previous card |
| `Enter` / `Space` | Activates the focused card, toggles the overflow disclosure, or triggers the hide/show button |
### Screen Reader [#screen-reader]
* The balance is exposed as a single accessible string via `aria-label` on its container, while the animated per-character glyphs are marked `aria-hidden`, so screen readers never read out dots or blur-in characters individually.
* The hide/show toggle announces its state through `aria-pressed` and a text label that switches between "Hide balance" and "Show balance".
### Reduced Motion [#reduced-motion]
When `prefers-reduced-motion` is enabled, the stack flattens (no `rotateX` tilt, no `translateZ` lift, no perspective), the pointer-tracked sheen stops following the cursor and rests in its home position, and the balance blur mask and overflow disclosure switch to `duration: 0` — cards and balances update instantly.
## Props [#props]
`network` accepts `"visa" | "mastercard" | "amex" | "generic"`.
# Warped Circle Transition (/docs/components/warped-circle-transition)
## Features [#features]
* Persistent WebGL transition wrapper triggered by a `transitionKey`
* Replicates the “Warped Circle” stage from the Codrops shader progression
* Uses the shared SmoothUI SDF transition engine with reduced-motion fallback
* Accessible: semantic content stays in the DOM and `onRest` still fires
## Usage guidance [#usage-guidance]
Use it for meaningful route/state transitions where this shader grammar fits the product moment.
## Props [#props]
# Wave Text (/docs/components/wave-text)
## Features [#features]
* Smooth continuous wave animation across text
* Customizable amplitude, duration, and stagger delay
* Natural bounce effect with custom easing
* GPU-accelerated for optimal performance
* Lightweight and easy to use
* Built with Motion
## Accessibility [#accessibility]
### Reduced Motion [#reduced-motion]
Uses `useReducedMotion` from `motion/react`. When enabled, the wave animation is fully disabled — characters render statically with no vertical movement and `duration: 0` transitions.
## Props [#props]
## Usage [#usage]
```tsx
import WaveText from "@repo/smoothui/components/wave-text";
// Basic usage
Hello World
// Customized wave
SmoothUI Components
```
## Examples [#examples]
### Large Bold Text [#large-bold-text]
```tsx
SmoothUI Components
```
### Subtle Wave [#subtle-wave]
```tsx
Smooth wave animations for your text!
```
# Accessibility (/docs/guides/accessibility)
## Overview [#overview]
Every SmoothUI component is built with accessibility in mind. Interactive components follow [WAI-ARIA](https://www.w3.org/WAI/ARIA/apg/) design patterns and support keyboard navigation, screen readers, and reduced motion preferences.
This page provides a quick reference for the accessibility features of each interactive component.
***
## Compliance Matrix [#compliance-matrix]
### Overlay & Dialog Components [#overlay--dialog-components]
| Component | Keyboard Support | ARIA Roles | Screen Reader | Reduced Motion |
| ----------------------------------------------- | ---------------------------------------- | ------------------------------------------------ | -------------------------------------------------------- | ----------------------------------------------- |
| [Dialog](/docs/primitives/dialog) | `Escape` closes, `Tab` traps focus | `role="dialog"`, `aria-modal`, `aria-labelledby` | Focus moves to close button on open, announced via title | Scale/slide entrance and backdrop fade disabled |
| [Toast](/docs/primitives/toast) | Auto-dismiss, focusable dismiss button | `role="alert"`, `aria-live="polite"` | Announced automatically via live region | Slide-in animation disabled |
| [Rich Popover](/docs/components/rich-popover) | `Escape` closes, `Tab` navigates content | `aria-expanded`, `aria-haspopup` | Trigger state announced on toggle | Scale/fade transitions disabled |
| [Gooey Popover](/docs/components/gooey-popover) | `Escape` closes | `aria-expanded` | Content announced on open | Gooey morph effect disabled, instant show/hide |
### Button & Action Components [#button--action-components]
| Component | Keyboard Support | ARIA Roles | Screen Reader | Reduced Motion |
| ----------------------------------------------------------- | ---------------------------- | -------------------------------- | ---------------------------- | ------------------------------------ |
| [Smooth Button](/docs/primitives/smooth-button) | `Enter`/`Space` activates | Native `` semantics | Standard button announcement | Hover/press scale animation disabled |
| [Magnetic Button](/docs/components/magnetic-button) | `Enter`/`Space` activates | Native `` semantics | Standard button announcement | Magnetic follow effect disabled |
| [Dot Morph Button](/docs/components/dot-morph-button) | `Enter`/`Space` activates | Native `` semantics | Standard button announcement | Dot morph transition disabled |
| [Clip Corners Button](/docs/components/clip-corners-button) | `Enter`/`Space` activates | Native `` semantics | Standard button announcement | Corner clip animation disabled |
| [Button Copy](/docs/components/button-copy) | `Enter`/`Space` copies | `aria-label` for copy action | Announces copy state change | Icon swap animation disabled |
| [Power Off Slide](/docs/components/power-off-slide) | Keyboard drag via arrow keys | `role="slider"`, `aria-valuenow` | Value announced on change | Slide animation disabled |
### Navigation & Selection Components [#navigation--selection-components]
| Component | Keyboard Support | ARIA Roles | Screen Reader | Reduced Motion |
| --------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------- | -------------------------------------- |
| [Tabs](/docs/primitives/tabs) | `Arrow Left`/`Right` switches tabs | `role="tablist"`, `role="tab"`, `role="tabpanel"` | Active tab announced | Indicator slide animation disabled |
| [Accordion](/docs/components/accordion) | `Enter`/`Space` toggles, arrow keys navigate | `aria-expanded`, `aria-controls` | Expanded/collapsed state announced | Expand/collapse animation disabled |
| [Dropdown Menu](/docs/primitives/dropdown-menu) | `Enter`/`Space` opens, arrows navigate, `Escape` closes | `role="menu"`, `role="menuitem"`, `aria-expanded` | Menu items announced with position | Open/close animation disabled |
| [Combobox](/docs/primitives/combobox) | Type to filter, arrows navigate, `Enter` selects, `Escape` closes | `role="combobox"`, `role="listbox"`, `aria-expanded` | Filtered results count announced | Dropdown animation disabled |
| [Social Selector](/docs/components/social-selector) | Arrow keys navigate options | `role="radiogroup"`, `role="radio"` | Selection announced on change | Selection indicator animation disabled |
| [Phototab](/docs/components/phototab) | Arrow keys switch, `Enter` selects | `role="tablist"` | Active tab announced | Tab transition disabled |
### Input & Form Components [#input--form-components]
| Component | Keyboard Support | ARIA Roles | Screen Reader | Reduced Motion |
| ------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------ | ---------------------------------------- | ------------------------------------ |
| [Animated Input](/docs/components/float-input) | Standard input keyboard behavior | `aria-label` or `aria-labelledby` | Label announced on focus | Float label animation disabled |
| [Animated OTP Input](/docs/components/otp-slots) | Tab between digits, backspace clears | `aria-label` per digit input | Each digit field announced | Digit entrance animation disabled |
| [Animated Tags](/docs/components/animated-tags) | `Enter` adds tag, `Backspace` removes last | `aria-label` for tag list | Tag add/remove announced via live region | Tag entrance/exit animation disabled |
| [Animated Toggle](/docs/components/morph-toggle) | `Enter`/`Space` toggles | `role="switch"`, `aria-checked` | On/off state announced | Toggle slide animation disabled |
| [Exposure Slider](/docs/components/exposure-slider) | Arrow keys adjust value | `role="slider"`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax` | Current value announced | Slider animation disabled |
| [Animated File Upload](/docs/components/animated-file-upload) | `Enter`/`Space` opens file picker | `aria-label` for upload zone | File selection announced | Upload progress animation disabled |
### Card & Content Components [#card--content-components]
| Component | Keyboard Support | ARIA Roles | Screen Reader | Reduced Motion |
| ----------------------------------------------------- | ------------------------------------------- | ------------------------ | ----------------------------------------------- | ----------------------------------------- |
| [Expandable Cards](/docs/components/expandable-cards) | `Enter`/`Space` expands, `Escape` collapses | `aria-expanded` | Card title announced, expanded content readable | Expand/collapse spring animation disabled |
| [Glow Hover Card](/docs/components/glow-hover-card) | Focusable via `Tab` | Standard card semantics | Card content announced | Glow effect disabled |
| [Switchboard Card](/docs/components/switchboard-card) | `Tab` focuses, `Enter` activates | Button or link semantics | Card content announced | Flip/switch animation disabled |
| [Product Card](/docs/components/product-card) | `Tab` focuses interactive elements | Semantic HTML structure | Product details announced | Hover animations disabled |
### Visual & Decorative Components [#visual--decorative-components]
| Component | Keyboard Support | ARIA Roles | Screen Reader | Reduced Motion |
| ----------------------------------------------------- | -------------------------- | ------------------------------------- | -------------------------- | ---------------------------------- |
| [Siri Orb](/docs/components/siri-orb) | N/A (decorative) | `aria-hidden="true"` | Hidden from screen readers | Animation paused |
| [Progress](/docs/primitives/progress) | N/A (display only) | `role="progressbar"`, `aria-valuenow` | Progress value announced | Fill animation disabled |
| [Skeleton Loader](/docs/components/content-skeleton) | N/A (display only) | `aria-busy="true"`, `aria-label` | Loading state announced | Shimmer animation disabled |
| [Grid Loader](/docs/components/grid-loader) | N/A (display only) | `aria-busy="true"` | Loading state announced | Grid animation disabled |
| [Notification Badge](/docs/components/count-badge) | N/A (decorative indicator) | `aria-label` with count | Badge count announced | Entrance animation disabled |
| [Animated Stepper](/docs/components/animated-stepper) | N/A (display only) | `aria-current="step"` | Current step announced | Step transition animation disabled |
***
## Reduced Motion Support [#reduced-motion-support]
All SmoothUI animated components use the `useReducedMotion` hook from [Motion](https://motion.dev). When a user has `prefers-reduced-motion: reduce` enabled in their operating system:
* **Spring animations** are replaced with instant transitions (`duration: 0`)
* **Decorative animations** (orbs, loaders, shimmer) are paused or hidden
* **Functional transitions** (expand/collapse, tab switches) complete instantly while preserving the state change
* **No content is lost** — all information remains accessible
### Testing Reduced Motion [#testing-reduced-motion]
To test reduced motion behavior during development:
1. **macOS**: System Settings → Accessibility → Display → Reduce motion
2. **Windows**: Settings → Accessibility → Visual effects → Animation effects (off)
3. **Chrome DevTools**: Open Rendering tab → Emulate CSS media feature `prefers-reduced-motion`
***
## General Accessibility Practices [#general-accessibility-practices]
SmoothUI components follow these principles:
1. **Semantic HTML** — Native elements (``, ``, ``) are preferred over divs with ARIA roles
2. **Focus management** — Modal components trap focus; focus is restored on dismiss
3. **Keyboard navigation** — All interactive components are fully operable via keyboard
4. **Color contrast** — Components use theme tokens that should meet WCAG 2.1 AA contrast ratios
5. **Screen reader compatibility** — Tested with VoiceOver (macOS) and NVDA (Windows)
If you find an accessibility issue with any SmoothUI component, please [open an issue on GitHub](https://github.com/educlopez/smoothui/issues) with the "accessibility" label. We take a11y seriously and aim to fix issues promptly.
# How to Add Animations to shadcn/ui (/docs/guides/add-animations-to-shadcn)
Your shadcn/ui app works. Forms validate, dialogs open, the dark mode is fine — and the whole thing feels inert next to Linear or Vercel. That gap is motion, and shadcn/ui deliberately leaves it to you: it ships accessible primitives, not an opinion about how they should move.
This guide covers the three ways to close that gap, when each is the right call, and the rules that separate motion that feels expensive from motion that feels cheap.
## Which route is yours [#which-route-is-yours]
| Route | Best for | Cost |
| --------------------------- | ------------------------------------------------------------ | --------------------------------------------------- |
| **CSS transitions** | Hover states, colour changes, simple fades | Minutes. No dependency. |
| **Hand-rolled Motion** | One or two signature interactions you want full control over | Hours per interaction, plus learning spring physics |
| **Pre-animated components** | Breadth — you want the whole app to feel considered | One command per component |
Most projects end up using all three. Reach for CSS first: if a transition on `opacity` and `transform` does the job, a JavaScript animation library is weight you do not need.
## Route 1 — CSS transitions [#route-1--css-transitions]
For interaction states, a plain Tailwind transition is usually the right answer and needs nothing installed:
```tsx
Hover me
```
```tsx
// Scale and fade on hover — both compositor-friendly properties
Card
```
If your project has `tw-animate-css` — shadcn's init adds it for Tailwind v4 projects, and it is what powers the `data-[state=open]:animate-in` classes on shadcn's own dialogs — you also get enter and exit keyframes for free:
```tsx
Appears on mount
```
**Where CSS runs out:** it cannot do real spring physics, it cannot animate an element that has already unmounted, and it cannot animate layout changes (`flex-direction`, `justify-content`, an element moving from one list to another). Those are the cases that justify a library.
## Route 2 — Hand-rolled Motion [#route-2--hand-rolled-motion]
Install [Motion](https://motion.dev) (formerly Framer Motion):
```bash
npm install motion
```
The mechanics are easy. The decisions are the hard part, and they are what make motion feel professional rather than bolted on.
### Duration: shorter than you think [#duration-shorter-than-you-think]
Aim for **0.2–0.25s** for standard UI. Up to 0.3s for something complex, 0.4s at the absolute most. Anything slower reads as sluggish because the user is waiting on your animation to finish before they can act.
### Easing: never use a string [#easing-never-use-a-string]
```tsx
// Wrong — vague, and usually too slow at the start
transition={{ ease: "easeInOut" }}
// Right — entering elements decelerate into place
transition={{ duration: 0.25, ease: [0.23, 1, 0.32, 1] }}
```
Use `ease-out` curves for elements arriving, `ease-in-out` for elements moving between two positions, and avoid `ease-in` for anything the user is waiting on — it feels like lag.
### Springs: keep the bounce low [#springs-keep-the-bounce-low]
```tsx
transition={{ type: "spring", duration: 0.25, bounce: 0.1 }}
```
Bounce at or below `0.1` for interface elements. Save `0.2–0.3` for playful or drag interactions, where overshoot is the point. A dialog that wobbles open looks broken, not lively.
### Animate only `transform` and `opacity` [#animate-only-transform-and-opacity]
These two are the only properties the browser can animate on the compositor, off the main thread. Animating `width`, `height`, `top` or `margin` forces layout on every frame and drops you below 60fps. Move things with `transform`, not `left`.
### Handle `prefers-reduced-motion` — this is not optional [#handle-prefers-reduced-motion--this-is-not-optional]
Roughly one in three people who enable this setting do so because motion makes them physically unwell. Ignoring it turns your polish into an accessibility failure:
```tsx
import { motion, useReducedMotion } from "motion/react";
export function Card() {
const shouldReduceMotion = useReducedMotion();
return (
Content
);
}
```
Reduced motion means **gentler, not none**. Keep opacity and colour changes; drop the movement.
Reduced motion is the rule that gets skipped most often, and it is the one with
real consequences. If you write your own animated components, make this the
first thing you add, not the last.
## Route 3 — Pre-animated components [#route-3--pre-animated-components]
SmoothUI is {COMPONENT_COUNT} components that already follow every rule above, installed through the shadcn registry you already use:
```bash
npx shadcn@latest add @smoothui/magnetic-button
```
The code is copied into your project, exactly like a shadcn component — same `cn()` utility, same tokens, same full ownership. It is not a dependency and there is no wrapper to fight.
This route makes sense when you want breadth. Getting one interaction right by hand is a good use of an afternoon; getting forty right is a project.
## What not to do [#what-not-to-do]
* **Animating layout properties.** `width`, `height` and `top` cause layout thrash. Use `transform`.
* **String easings.** `"easeInOut"` is imprecise and usually too slow. Use `cubic-bezier` values.
* **Durations over 0.4s** on anything interactive. It reads as lag, not elegance.
* **Hover animations without checking for hover.** On touch devices a hover effect fires on tap and sticks. Gate it behind `matchMedia("(hover: hover) and (pointer: fine)")`.
* **Skipping `prefers-reduced-motion`.** See above.
* **Animating everything.** Motion should direct attention. If it is everywhere, it directs nothing.
## Where to go next [#where-to-go-next]
# AI Integration (/docs/guides/ai-integration)
SmoothUI is designed from the ground up for AI-assisted development. Whether you are an AI agent selecting components programmatically, or a developer using AI coding tools, SmoothUI provides first-class integration paths.
## Quick Start [#quick-start]
Choose the integration that fits your workflow:
| You are... | What to use | Setup |
| --------------------------------------------- | ------------------------ | ------------------------------------------ |
| **AI coding agent** (Claude, Cursor, Copilot) | MCP Server | `npx shadcn@latest mcp init` |
| **Building custom tooling** | REST API | Call `https://smoothui.dev/api/v1/...` |
| **LLM / RAG pipeline** | Machine-readable catalog | Fetch `https://smoothui.dev/llms-full.txt` |
## For AI Agents [#for-ai-agents]
AI agents can discover, search, and install SmoothUI components through multiple channels.
### MCP Server (Recommended) [#mcp-server-recommended]
The fastest way to give an AI assistant full access to SmoothUI. The shadcn MCP server works out of the box with SmoothUI's registry.
```shell title="Terminal"
npx shadcn@latest mcp init --client claude
```
```shell title="Terminal"
npx shadcn@latest mcp init --client cursor
```
```shell title="Terminal"
npx shadcn@latest mcp init --client vscode
```
Once configured, your AI assistant can discover, search, and install any SmoothUI component. See the full [MCP Server guide](/docs/guides/mcp) for detailed setup and example prompts.
### REST API [#rest-api]
For agents that need structured JSON data, SmoothUI provides a public REST API with no authentication required.
```bash title="Discover components"
curl "https://smoothui.dev/api/v1/suggest?need=animated+tab+navigation"
```
```bash title="Get component source"
curl "https://smoothui.dev/api/v1/components/morph-toggle?include=source"
```
**Key endpoints:**
| Endpoint | Purpose |
| ------------------------------------- | -------------------------------------- |
| `GET /api/v1/components` | List all components with filtering |
| `GET /api/v1/components/{name}` | Get component details and source |
| `GET /api/v1/components/search?q=...` | Keyword search |
| `GET /api/v1/suggest?need=...` | Natural-language component suggestions |
| `GET /api/v1/blocks` | List pre-built page sections |
| `GET /openapi.json` | Full OpenAPI 3.1 specification |
See the full [REST API reference](/docs/guides/api) for query parameters, response schemas, and error handling.
### Machine-Readable Catalog [#machine-readable-catalog]
For LLM context windows and RAG pipelines, SmoothUI provides machine-readable component catalogs following the `llms.txt` convention:
| URL | Description |
| -------------------------------------------------------------------- | -------------------------------------------------- |
| [`/llms.txt`](https://smoothui.dev/llms.txt) | Compact overview of all components |
| [`/llms-full.txt`](https://smoothui.dev/llms-full.txt) | Full catalog with metadata, props, and usage hints |
| [`/llms-components.json`](https://smoothui.dev/llms-components.json) | Structured JSON catalog for programmatic use |
## Agent Workflow [#agent-workflow]
Here is the recommended workflow for AI agents integrating SmoothUI components:
1. **Discover** — Use `/api/v1/suggest?need=...` or the MCP server to find relevant components based on what the user needs.
2. **Inspect** — Fetch full metadata and source with `/api/v1/components/{name}?include=source` to understand props and usage.
3. **Install** — Use the `installCommand` from the metadata: `npx shadcn@latest add @smoothui/{name}`.
4. **Integrate** — Use `compositionHints` and the source code to wire the component into the project correctly.
## Learn More [#learn-more]
Full MCP setup guide with example prompts for Claude, Cursor, and VS Code.
Complete API reference with endpoints, parameters, and response schemas.
Get started with SmoothUI in your project.
# Animated React Components (/docs/guides/animated-components)
## Motion & GSAP-Powered React Components [#motion--gsap-powered-react-components]
SmoothUI provides a comprehensive collection of **animated React components** powered by [Motion](https://motion.dev) (formerly Framer Motion) and [GSAP](https://gsap.com). Every component is designed with smooth, performant animations that enhance user experience without sacrificing accessibility.
## Animation Categories [#animation-categories]
### Text Animations [#text-animations]
Create engaging text effects that capture attention:
| Component | Animation Type | Use Case |
| --------------------------------------------------- | --------------------- | ---------------------------- |
| [Typewriter Text](/docs/components/typewriter-text) | Character reveal | Hero sections, AI interfaces |
| [Scramble Hover](/docs/components/scramble-hover) | Matrix-style scramble | Navigation, headings |
| [Wave Text](/docs/components/wave-text) | Wave motion | Decorative headings |
| [Reveal Text](/docs/components/reveal-text) | Directional reveal | Page transitions |
### Interactive Cards [#interactive-cards]
Cards with smooth expand, hover, and transition animations:
| Component | Animation Type | Use Case |
| --------------------------------------------------------------- | --------------------- | ---------------------- |
| [Expandable Cards](/docs/components/expandable-cards) | Layout animation | Portfolios, galleries |
| [Glow Hover Card](/docs/components/glow-hover-card) | Cursor-following glow | Feature highlights |
| [Scrollable Card Stack](/docs/components/scrollable-card-stack) | Parallax reveal | Testimonials, profiles |
### Button Animations [#button-animations]
Buttons with satisfying micro-interactions:
| Component | Animation Type | Use Case |
| ----------------------------------------------------------- | ----------------- | ---------------- |
| [Magnetic Button](/docs/components/magnetic-button) | Cursor attraction | CTAs, navigation |
| [Button Copy](/docs/components/button-copy) | Success feedback | Code snippets |
| [Clip Corners Button](/docs/components/clip-corners-button) | Corner animation | Unique CTAs |
### Form Inputs [#form-inputs]
Inputs with smooth focus and validation animations:
| Component | Animation Type | Use Case |
| ------------------------------------------------ | --------------- | ------------------ |
| [Animated Input](/docs/components/float-input) | Floating label | Forms, search |
| [Animated OTP Input](/docs/components/otp-slots) | Digit animation | Verification flows |
### Notification Components [#notification-components]
Animated feedback and notification elements:
| Component | Animation Type | Use Case |
| ------------------------------------------------- | --------------- | --------------------- |
| [Dynamic Island](/docs/components/dynamic-island) | Expand/collapse | Notifications, status |
| [Toast](/docs/primitives/toast) | Slide animation | Alerts, confirmations |
## Why Motion & GSAP? [#why-motion--gsap]
### Performance Optimized [#performance-optimized]
All animations use GPU-accelerated transforms (`transform` and `opacity`) for smooth 60fps performance. No layout thrashing or paint operations.
### Accessibility First [#accessibility-first]
Every component respects the `prefers-reduced-motion` media query. Users who are sensitive to motion see instant transitions instead of animations.
```tsx
// Built into every component
const shouldReduceMotion = useReducedMotion();
```
### Natural Feel [#natural-feel]
Animations use spring physics with carefully tuned parameters for natural, fluid motion that feels right:
```tsx
transition={{
type: "spring",
duration: 0.25,
bounce: 0.1
}}
```
## Getting Started [#getting-started]
Install any animated component using the shadcn CLI:
```bash
npx shadcn@latest add @smoothui/expandable-cards
```
Or browse all components:
Explore the complete collection of {COMPONENT_COUNT} animated components.
Set up SmoothUI in your React or Next.js project.
## Frequently asked questions [#frequently-asked-questions]
No! All animations are built-in and work out of the box. You can use components without writing any animation code. For customization, basic Motion or GSAP knowledge helps but isn't required.
Motion and GSAP are the animation dependencies. Components are tree-shakeable, so you only ship the code you use. Most components use Motion, while some use GSAP for advanced effects like the Gooey Popover.
Yes! All components are designed for Next.js App Router and work with Server Components. Client-side animations hydrate smoothly without layout shift.
Absolutely. Since you own the code (copied into your project), you can modify any animation parameters - duration, easing, spring physics, and more.
# Animation Best Practices (/docs/guides/animation-best-practices)
## Why Animation Matters [#why-animation-matters]
Animation isn't just decoration—it's a fundamental part of user experience. Well-crafted animations:
* **Guide attention** to important elements and changes
* **Provide feedback** that actions were registered
* **Create continuity** between UI states
* **Reduce cognitive load** by showing relationships between elements
* **Delight users** with polished, professional interactions
Studies show that appropriate animation can increase user engagement by up to 400% and significantly improve perceived performance, even when actual load times remain the same.
Every SmoothUI component follows these principles. Animations are fast (200-300ms), purposeful, and always respect user preferences for reduced motion.
***
## Core Animation Principles [#core-animation-principles]
### Duration & Timing [#duration--timing]
The most common mistake is making animations too slow. Users perceive interfaces as sluggish when animations exceed 300-400ms.
| Animation Type | Recommended Duration |
| ------------------------------------- | -------------------- |
| Micro-interactions (hover, focus) | 100-200ms |
| Standard transitions (show/hide) | 200-300ms |
| Complex animations (page transitions) | 300-400ms |
| Decorative/ambient | Up to 1000ms |
```tsx
// Good: Fast, snappy interaction
transition={{ duration: 0.2 }}
// Bad: Feels sluggish
transition={{ duration: 0.8 }}
```
### Easing Functions [#easing-functions]
Easing determines how an animation accelerates and decelerates. The right easing makes motion feel natural.
| Easing | Use Case | CSS/Motion Value |
| --------------- | ---------------------- | -------------------------------------- |
| **ease-out** | Elements entering | `cubic-bezier(0.23, 1, 0.32, 1)` |
| **ease-in-out** | Elements moving | `cubic-bezier(0.645, 0.045, 0.355, 1)` |
| **ease** | Hover/color changes | `ease` (built-in) |
| **spring** | Natural, bouncy motion | `type: "spring"` |
```tsx
// Natural spring animation (recommended for most cases)
transition={{
type: "spring",
duration: 0.25,
bounce: 0.1 // Keep low for UI (0.1-0.2)
}}
// Cubic bezier for precise control
transition={{
duration: 0.2,
ease: [0.23, 1, 0.32, 1] // ease-out
}}
```
Never use `ease-in` for UI animations—it starts slow and feels unresponsive. Users expect immediate feedback when they interact.
### Transform vs Layout Properties [#transform-vs-layout-properties]
This is critical for performance. Only animate **transform** and **opacity**—these are GPU-accelerated and don't trigger layout recalculations.
```tsx
// GOOD: GPU-accelerated, smooth 60fps
animate={{ opacity: 1, scale: 1, x: 0, y: 0 }}
// BAD: Triggers layout, causes jank
animate={{ width: 200, height: 100, marginLeft: 20 }}
```
| Property | Performance | Use Instead |
| -------------------------------- | ----------- | ------------------------------ |
| `width`, `height` | Poor | `scale` or `scaleX`/`scaleY` |
| `top`, `left`, `right`, `bottom` | Poor | `x`, `y` (transform) |
| `margin`, `padding` | Poor | `x`, `y` with fixed dimensions |
| `opacity` | Excellent | Use freely |
| `transform` | Excellent | Use freely |
***
## Motion Library Essentials [#motion-library-essentials]
SmoothUI uses [Motion](https://motion.dev) (formerly Framer Motion) for animations. Here are the key concepts.
### Spring Physics [#spring-physics]
Spring animations feel more natural than duration-based animations because they simulate real-world physics.
```tsx
import { motion } from "motion/react";
```
**Simplified spring syntax** (recommended):
```tsx
transition={{
type: "spring",
duration: 0.25, // Approximate duration
bounce: 0.1 // 0 = no bounce, 1 = very bouncy
}}
```
### Variants [#variants]
Variants let you define animation states and orchestrate complex animations:
```tsx
const containerVariants = {
hidden: { opacity: 0 },
visible: {
opacity: 1,
transition: {
staggerChildren: 0.1 // Animate children sequentially
}
}
};
const itemVariants = {
hidden: { opacity: 0, y: 20 },
visible: { opacity: 1, y: 0 }
};
{items.map(item => (
{item.name}
))}
```
### Layout Animations [#layout-animations]
Motion's `layout` prop automatically animates layout changes:
```tsx
// Automatically animates position/size changes
{isExpanded ? : }
// Smooth shared element transitions
{/* This element animates between positions */}
```
### AnimatePresence [#animatepresence]
For enter/exit animations, wrap components in `AnimatePresence`:
```tsx
import { AnimatePresence, motion } from "motion/react";
{isVisible && (
Content that animates in and out
)}
```
***
## Performance Optimization [#performance-optimization]
### GPU-Accelerated Properties [#gpu-accelerated-properties]
Always prefer these properties for smooth 60fps animations:
```tsx
// These run on the GPU (compositor thread)
transform: translateX(), translateY(), scale(), rotate()
opacity
// These trigger layout/paint (main thread) - AVOID
width, height, top, left, margin, padding, border
```
### Avoiding Layout Thrash [#avoiding-layout-thrash]
Layout thrash occurs when you read and write to the DOM in quick succession:
```tsx
// BAD: Forces synchronous layout
elements.forEach(el => {
const height = el.offsetHeight; // READ
el.style.height = height + 10; // WRITE
});
// GOOD: Batch reads, then writes
const heights = elements.map(el => el.offsetHeight); // All READs
elements.forEach((el, i) => {
el.style.height = heights[i] + 10; // All WRITEs
});
```
### will-change Hint [#will-change-hint]
Use sparingly to hint browser optimization:
```css
.animated-element {
will-change: transform, opacity;
}
```
Only apply `will-change` to elements that will actually animate. Overuse consumes memory and can hurt performance.
### When to Use CSS vs JavaScript Animations [#when-to-use-css-vs-javascript-animations]
| Use CSS | Use JavaScript (Motion) |
| -------------------------- | -------------------------------- |
| Simple hover effects | Complex choreographed animations |
| State transitions | Physics-based motion |
| Keyframe animations | Gesture-driven animations |
| Performance-critical loops | Dynamic, data-driven animations |
***
## Accessibility Guidelines [#accessibility-guidelines]
### Respecting Reduced Motion [#respecting-reduced-motion]
Always check `prefers-reduced-motion`. Users enable this for medical reasons (vestibular disorders, motion sickness) or personal preference.
```tsx
import { useReducedMotion } from "motion/react";
function AnimatedComponent() {
const shouldReduceMotion = useReducedMotion();
return (
);
}
```
Every SmoothUI component includes `useReducedMotion` support. Animations are automatically disabled or minimized for users who prefer reduced motion.
### Motion Sensitivity Guidelines [#motion-sensitivity-guidelines]
Even for users without reduced motion enabled:
* **Avoid large-scale motion** (full-screen transitions, parallax)
* **Limit simultaneous animations** (no more than 2-3 elements animating at once)
* **Keep animations brief** (under 300ms for most interactions)
* **Avoid infinite loops** (or provide controls to pause)
### Focus Management [#focus-management]
When animating elements that affect focus:
```tsx
// Ensure focus moves appropriately after animation
{
if (isOpen) {
firstFocusableElement.current?.focus();
}
}}
>
```
***
## Common Patterns [#common-patterns]
### Enter/Exit Animations [#enterexit-animations]
```tsx
// Fade + slide up (most common)
const fadeSlideUp = {
initial: { opacity: 0, y: 10 },
animate: { opacity: 1, y: 0 },
exit: { opacity: 0, y: -10 },
transition: { duration: 0.2 }
};
// Scale + fade (for modals, popovers)
const scaleFade = {
initial: { opacity: 0, scale: 0.95 },
animate: { opacity: 1, scale: 1 },
exit: { opacity: 0, scale: 0.95 },
transition: { type: "spring", duration: 0.25, bounce: 0.1 }
};
```
### Hover Effects [#hover-effects]
```tsx
Click me
```
### Staggered Lists [#staggered-lists]
```tsx
{items.map(item => (
{item.name}
))}
```
### Scroll-Triggered Animations [#scroll-triggered-animations]
```tsx
import { useInView, motion } from "motion/react";
function ScrollReveal({ children }) {
const ref = useRef(null);
const isInView = useInView(ref, { once: true, margin: "-100px" });
return (
{children}
);
}
```
***
## Anti-Patterns to Avoid [#anti-patterns-to-avoid]
### Overanimating [#1-overanimating]
Not everything needs to animate. Too much motion is distracting and exhausting.
```tsx
// BAD: Everything bounces and wiggles
// GOOD: Purposeful, minimal animation
```
### Slow Animations [#2-slow-animations]
Animations over 300ms feel sluggish. Users shouldn't wait for your UI.
```tsx
// BAD: Too slow
transition={{ duration: 0.8 }}
// GOOD: Snappy
transition={{ duration: 0.2 }}
```
### Competing Animations [#3-competing-animations]
Multiple elements animating simultaneously creates visual chaos.
```tsx
// BAD: Everything animates at once
{items.map(item => (
))}
// GOOD: Stagger or animate one at a time
variants={{ visible: { transition: { staggerChildren: 0.05 } } }}
```
### Animation Without Purpose [#4-animation-without-purpose]
Every animation should serve a function: feedback, guidance, or continuity.
```tsx
// BAD: Spinning logo for no reason
// GOOD: Spinner indicates loading state
{isLoading && }
```
### Ignoring Reduced Motion [#5-ignoring-reduced-motion]
Always implement reduced motion support. It's an accessibility requirement.
```tsx
// BAD: No reduced motion check
animate={{ x: 100, rotate: 360 }}
// GOOD: Respects user preference
animate={shouldReduceMotion ? { opacity: 1 } : { x: 100, rotate: 360 }}
```
***
## Quick Reference [#quick-reference]
### Recommended Defaults [#recommended-defaults]
```tsx
// Standard UI animation
transition={{
type: "spring",
duration: 0.25,
bounce: 0.1
}}
// Hover/tap feedback
transition={{
type: "spring",
stiffness: 400,
damping: 17
}}
// Enter/exit
transition={{ duration: 0.2, ease: [0.23, 1, 0.32, 1] }}
```
### Checklist for New Animations [#checklist-for-new-animations]
* [ ] Duration under 300ms for interactions
* [ ] Only animating transform/opacity
* [ ] `useReducedMotion` implemented
* [ ] Purposeful (not decorative)
* [ ] Tested on low-end devices
***
## Further Reading [#further-reading]
Browse all {COMPONENT_COUNT} animated components in SmoothUI.
Learn about SmoothUI's design philosophy and patterns.
Official Motion (Framer Motion) documentation.
# REST API (/docs/guides/api)
SmoothUI exposes a public REST API that lets you discover, search, and retrieve component metadata and source code programmatically. The API is designed for both human developers building tooling and AI agents that need structured component data.
## Overview [#overview]
**Base URL:** `https://smoothui.dev/api/v1`
**Authentication:** None required. The API is fully public.
**CORS:** All endpoints include `Access-Control-Allow-Origin: *` headers, so you can call them from any origin.
**Format:** All responses are JSON. Errors follow a consistent `{"error": "...", "status": 400}` envelope.
**OpenAPI Spec:** A full OpenAPI 3.1 specification is available at [`/openapi.json`](https://smoothui.dev/openapi.json).
## Endpoints [#endpoints]
### List Components [#list-components]
Returns a paginated list of all SmoothUI components. Supports filtering by category, complexity, animation type, and tag.
```bash title="Request"
curl "https://smoothui.dev/api/v1/components?category=navigation&pageSize=10"
```
**Query parameters:**
| Parameter | Type | Default | Description |
| --------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `category` | string | - | Filter by category: `basic-ui`, `button`, `text`, `ai`, `layout`, `feedback`, `data-display`, `navigation`, `other` |
| `complexity` | string | - | Filter by complexity: `simple`, `moderate`, `complex` |
| `animationType` | string | - | Filter by animation: `spring`, `tween`, `gesture`, `scroll`, `none` |
| `tag` | string | - | Filter by tag (case-insensitive exact match) |
| `page` | integer | `1` | Page number (1-based) |
| `pageSize` | integer | `50` | Items per page (max 100) |
```json title="Response"
{
"data": [
{
"name": "morph-toggle",
"displayName": "MorphToggle",
"description": "Tab navigation with smooth spring-based transitions.",
"category": "navigation",
"tags": ["animation", "tabs", "navigation"],
"useCases": ["Tab navigation with smooth transitions"],
"compositionHints": ["Combine with tooltip for rich tab headers"],
"complexity": "moderate",
"animationType": "spring",
"dependencies": ["motion"],
"registryDependencies": [],
"hasReducedMotion": true,
"propsCount": 5,
"installCommand": "npx shadcn@latest add @smoothui/morph-toggle",
"docUrl": "https://smoothui.dev/docs/components/morph-toggle",
"registryUrl": "https://smoothui.dev/r/morph-toggle.json"
}
],
"total": 84,
"page": 1,
"pageSize": 10,
"totalPages": 9
}
```
### Get Component Details [#get-component-details]
Returns full metadata for a single component. Add `?include=source` to also retrieve the raw source code.
```bash title="Request"
curl "https://smoothui.dev/api/v1/components/morph-toggle"
```
```bash title="Request (with source code)"
curl "https://smoothui.dev/api/v1/components/morph-toggle?include=source"
```
```json title="Response"
{
"component": {
"name": "morph-toggle",
"displayName": "MorphToggle",
"description": "Tab navigation with smooth spring-based transitions.",
"category": "navigation",
"tags": ["animation", "tabs", "navigation"],
"complexity": "moderate",
"animationType": "spring",
"installCommand": "npx shadcn@latest add @smoothui/morph-toggle",
"docUrl": "https://smoothui.dev/docs/components/morph-toggle",
"registryUrl": "https://smoothui.dev/r/morph-toggle.json"
},
"source": "// --- index.tsx ---\n\"use client\";\nimport { motion } from ..."
}
```
Returns `404` if the component name does not exist.
### Search Components [#search-components]
Keyword-based relevance search across component names, descriptions, tags, use cases, and categories. At least one of `q`, `category`, or `tags` is required.
```bash title="Request"
curl "https://smoothui.dev/api/v1/components/search?q=modal+dialog"
```
**Query parameters:**
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ---------------------------------------------- |
| `q` | string | No\* | Search query |
| `category` | string | No\* | Pre-filter by category |
| `tags` | string | No\* | Comma-separated required tags (all must match) |
\*At least one parameter is required.
```json title="Response"
{
"data": [
{
"name": "dialog",
"displayName": "Dialog",
"description": "Accessible modal dialog with smooth enter/exit animations.",
"category": "feedback",
"tags": ["modal", "dialog", "overlay"],
"relevanceScore": 12
}
],
"total": 3,
"query": "modal dialog",
"filters": {}
}
```
Results are ranked by relevance score (higher is better). Exact name matches score highest, followed by tag matches, use case matches, description matches, and category matches.
### List Blocks [#list-blocks]
Returns a paginated list of pre-built page sections (blocks). Supports filtering by block type and tag.
```bash title="Request"
curl "https://smoothui.dev/api/v1/blocks?blockType=hero"
```
**Query parameters:**
| Parameter | Type | Default | Description |
| ----------- | ------- | ------- | ------------------------------------------------------------------------------------------------- |
| `blockType` | string | - | Filter by type: `hero`, `features`, `pricing`, `testimonials`, `cta`, `footer`, `header`, `other` |
| `tag` | string | - | Filter by tag (case-insensitive exact match) |
| `page` | integer | `1` | Page number |
| `pageSize` | integer | `50` | Items per page (max 100) |
```json title="Response"
{
"data": [
{
"name": "header-1",
"displayName": "Header1",
"description": "Modern header block with navigation and mobile menu",
"blockType": "header",
"components": [],
"category": "layout",
"tags": ["header", "hero", "navigation", "grid", "interactive", "animated"],
"complexity": "complex",
"animationType": "tween",
"installCommand": "npx shadcn@latest add @smoothui/header-1"
}
],
"total": 5,
"page": 1,
"pageSize": 50,
"totalPages": 1
}
```
### Get Block Details [#get-block-details]
Returns full metadata for a single block. Add `?include=source` for raw source code.
```bash title="Request"
curl "https://smoothui.dev/api/v1/blocks/header-1?include=source"
```
Returns `404` if the block name does not exist.
### Suggest Components [#suggest-components]
Given a natural-language description of what you need, returns the top 10 most relevant components and blocks. This endpoint is particularly useful for AI agents selecting components based on a user's request.
```bash title="Request"
curl "https://smoothui.dev/api/v1/suggest?need=animated+tab+navigation"
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------------------------- |
| `need` | string | Yes | Natural-language description of what you need |
```json title="Response"
{
"need": "animated tab navigation",
"suggestions": [
{
"type": "component",
"name": "morph-toggle",
"displayName": "MorphToggle",
"description": "Tab navigation with smooth spring-based transitions.",
"category": "navigation",
"relevanceScore": 21,
"installCommand": "npx shadcn@latest add @smoothui/morph-toggle",
"docUrl": "https://smoothui.dev/docs/components/morph-toggle",
"registryUrl": "https://smoothui.dev/r/morph-toggle.json"
}
],
"total": 1
}
```
Suggestions include both components and blocks, distinguished by the `type` field. Results are ranked by keyword relevance.
## Error Handling [#error-handling]
All error responses use a consistent JSON envelope:
```json title="Error response"
{
"error": "Component \"unknown\" not found",
"status": 404
}
```
Common status codes:
| Status | Meaning |
| ------ | ------------------------------------------- |
| `200` | Success |
| `400` | Bad request (missing or invalid parameters) |
| `404` | Resource not found |
## For AI Agents [#for-ai-agents]
If you are building an AI agent or coding assistant that works with SmoothUI, here is the recommended workflow:
1. **Discovery** -- Use `/api/v1/suggest?need=...` with the user's natural-language request to find relevant components.
2. **Detail** -- Fetch full metadata and source with `/api/v1/components/{name}?include=source`.
3. **Install** -- Use the `installCommand` field from the metadata to install the component.
4. **Integrate** -- Use the source code and `compositionHints` to wire the component into the user's project.
You can also fetch the full [OpenAPI specification](https://smoothui.dev/openapi.json) for automated client generation or tool registration.
For MCP-based integration with AI coding assistants, see the [MCP Server](/docs/guides/mcp) guide.
# Astro Integration (/docs/guides/astro)
## Overview [#overview]
Astro's [islands architecture](https://docs.astro.build/en/concepts/islands/) lets you use SmoothUI React components as interactive islands within your static Astro pages. Each SmoothUI component hydrates independently, giving you smooth animations with minimal JavaScript overhead.
SmoothUI components are standard React components. Astro renders them server-side and hydrates them on the client using directives like `client:load` and `client:visible`. No modifications to the components are needed.
## Prerequisites [#prerequisites]
Before getting started, make sure you have the following:
| Requirement | Minimum Version | Purpose |
| ------------------------------------------------------------------------------ | --------------- | --------------------------- |
| [Node.js](https://nodejs.org/en) | 18+ | Runtime |
| [Astro](https://astro.build) | 4.0+ | Framework |
| [@astrojs/react](https://docs.astro.build/en/guides/integrations-guide/react/) | 4.0+ | React integration for Astro |
| [Tailwind CSS](https://tailwindcss.com) | 4.0+ | Styling |
| [Motion](https://motion.dev) | 12.0+ | Animations (Framer Motion) |
## Project Setup [#project-setup]
### Create a New Astro Project [#1-create-a-new-astro-project]
If you're starting from scratch, create a new Astro project:
### Add the React Integration [#2-add-the-react-integration]
SmoothUI components are React components, so you need `@astrojs/react`:
This automatically updates your `astro.config.mjs{:js}` to include the React integration:
```js title="astro.config.mjs"
import { defineConfig } from "astro/config";
import react from "@astrojs/react";
export default defineConfig({
integrations: [react()],
});
```
### Set Up Tailwind CSS 4 [#3-set-up-tailwind-css-4]
Install Tailwind CSS and the Astro integration:
Add the Tailwind CSS Vite plugin to your Astro config:
```js title="astro.config.mjs"
import { defineConfig } from "astro/config";
import react from "@astrojs/react";
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({
integrations: [react()],
vite: {
plugins: [tailwindcss()],
},
});
```
Create your main CSS file and import Tailwind:
```css title="src/styles/global.css"
@import "tailwindcss";
```
Import the stylesheet in your layout:
```astro title="src/layouts/Layout.astro"
---
interface Props {
title: string;
}
const { title } = Astro.props;
---
{title}
```
### Install Motion [#4-install-motion]
SmoothUI animations are powered by Motion (Framer Motion). Install it as a dependency:
### Configure Path Aliases [#5-configure-path-aliases]
SmoothUI components use the `@/{:js}` path alias. Add it to your `tsconfig.json{:js}`:
```json title="tsconfig.json"
{
"extends": "astro/tsconfigs/strict",
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"]
}
}
}
```
## Installing SmoothUI Components [#installing-smoothui-components]
### Using the SmoothUI CLI [#using-the-smoothui-cli]
### Using the shadcn CLI [#using-the-shadcn-cli]
If this is your first time using the shadcn CLI in an Astro project, it will prompt you to create a `components.json{:js}` file. Accept the defaults — the CLI auto-detects Astro projects and configures paths accordingly.
## Client Directives [#client-directives]
Astro components are static by default. To make SmoothUI components interactive, you need to add a [client directive](https://docs.astro.build/en/reference/directives-reference/#client-directives) that tells Astro when to hydrate the component.
| Directive | When It Hydrates | Best For |
| ----------------------------- | ------------------------------------ | ------------------------------------------------ |
| `client:load{:astro}` | Immediately on page load | Above-the-fold components, critical interactions |
| `client:visible{:astro}` | When the component scrolls into view | Below-the-fold components, cards, animations |
| `client:idle{:astro}` | When the browser is idle | Non-critical UI, background animations |
| `client:only="react"{:astro}` | Client-only, no SSR | Components that use browser APIs on mount |
Use `client:visible{:astro}` for most SmoothUI components — it gives the best performance since components only hydrate when the user can see them. Use `client:load{:astro}` for hero sections or components that must be interactive immediately.
## Using Components in Astro Pages [#using-components-in-astro-pages]
Here is a complete example of using a SmoothUI component in an Astro page:
```astro title="src/pages/index.astro"
---
import Layout from "../layouts/Layout.astro";
import { SiriOrb } from "@/components/smoothui/ui/SiriOrb";
---
SmoothUI in Astro
```
### Using Multiple Components [#using-multiple-components]
```astro title="src/pages/demo.astro"
---
import Layout from "../layouts/Layout.astro";
import { MagneticButton } from "@/components/smoothui/ui/MagneticButton";
import { ExpandableCards } from "@/components/smoothui/ui/ExpandableCards";
import { TypewriterText } from "@/components/smoothui/ui/TypewriterText";
---
Get Started
```
## Motion in Astro Islands [#motion-in-astro-islands]
Motion (Framer Motion) works seamlessly inside Astro islands. Since each island is a fully hydrated React component, all animation features are available — spring physics, layout animations, gestures, and `AnimatePresence{:tsx}`.
If you create custom animated components alongside SmoothUI, follow the same pattern:
```tsx title="src/components/FadeIn.tsx"
"use client";
import { motion, useReducedMotion } from "motion/react";
import type { ReactNode } from "react";
export type FadeInProps = {
children: ReactNode;
};
const FadeIn = ({ children }: FadeInProps) => {
const shouldReduceMotion = useReducedMotion();
return (
{children}
);
};
export default FadeIn;
```
```astro title="src/pages/index.astro"
---
import FadeIn from "../components/FadeIn";
---
This content fades in when scrolled into view.
```
The `"use client"{:tsx}` directive at the top of React component files is a Next.js convention. Astro ignores it, so it does no harm — and it keeps your components compatible with both frameworks.
## Troubleshooting [#troubleshooting]
Make sure you added a client directive (`client:load{:astro}`, `client:visible{:astro}`, etc.) to the component. Without a client directive, Astro renders the component as static HTML with no JavaScript, so animations won't run.
Verify that your `global.css{:css}` includes `@import "tailwindcss"{:css}` and that it's imported in your layout. Also check that the Tailwind Vite plugin is configured in `astro.config.mjs{:js}`.
If a component relies on browser-only APIs (like `window{:js}` or `localStorage{:js}`) during initial render, use `client:only="react"{:astro}` instead of `client:load{:astro}`. This skips server-side rendering entirely for that component.
Motion works well with SSR by default. If you see warnings about `useLayoutEffect{:tsx}`, it's usually harmless. For components that heavily depend on browser measurements, use `client:only="react"{:astro}`.
## Next Steps [#next-steps]
Learn about all available installation methods including the SmoothUI CLI and shadcn registry.
Explore the complete collection of {COMPONENT_COUNT} animated React components.
Master animation performance, accessibility, and timing guidelines.
The simplest setup for using SmoothUI in a client-side React app.
Full-stack SSR setup with Remix and React Router v7.
Type-safe full-stack React with streaming SSR.
# Changelog (/docs/guides/changelog)
> This page and the changelog bell are maintained manually. The entry below
> describes the SmoothUI 4.0.0 product release. Package release
> notes are maintained separately by release-please in
> [GitHub Releases](https://github.com/educlopez/smoothui/releases),
> [the component changelog](https://github.com/educlopez/smoothui/blob/main/packages/smoothui/CHANGELOG.md)
> and [the CLI changelog](https://github.com/educlopez/smoothui/blob/main/packages/cli/CHANGELOG.md).
## 4.0.0 [#400]
Owned primitives moved to `/docs/primitives`, and several pattern packages were renamed. Old documentation URLs redirect in one hop. Old registry URLs (`/r/{old}.json`) still return the new item.
| Old name | New name | Install |
| ----------------------- | ------------------ | -------------------------------------------------------------------- |
| `animated-input` | `float-input` | `npx shadcn@latest add https://smoothui.dev/r/float-input.json` |
| `animated-number-input` | `digit-roll` | `npx shadcn@latest add https://smoothui.dev/r/digit-roll.json` |
| `animated-o-t-p-input` | `otp-slots` | `npx shadcn@latest add https://smoothui.dev/r/otp-slots.json` |
| `animated-progress-bar` | `progress` | `npx shadcn@latest add https://smoothui.dev/r/progress.json` |
| `animated-tabs` | `tabs` | `npx shadcn@latest add https://smoothui.dev/r/tabs.json` |
| `animated-toggle` | `morph-toggle` | `npx shadcn@latest add https://smoothui.dev/r/morph-toggle.json` |
| `animated-tooltip` | `tooltip` | `npx shadcn@latest add https://smoothui.dev/r/tooltip.json` |
| `basic-accordion` | `accordion` | `npx shadcn@latest add https://smoothui.dev/r/accordion.json` |
| `basic-dropdown` | `dropdown-menu` | `npx shadcn@latest add https://smoothui.dev/r/dropdown-menu.json` |
| `basic-modal` | `dialog` | `npx shadcn@latest add https://smoothui.dev/r/dialog.json` |
| `basic-toast` | `toast` | `npx shadcn@latest add https://smoothui.dev/r/toast.json` |
| `country-dialog` | `country-picker` | `npx shadcn@latest add https://smoothui.dev/r/country-picker.json` |
| `notification-badge` | `count-badge` | `npx shadcn@latest add https://smoothui.dev/r/count-badge.json` |
| `searchable-dropdown` | `combobox` | `npx shadcn@latest add https://smoothui.dev/r/combobox.json` |
| `skeleton-loader` | `content-skeleton` | `npx shadcn@latest add https://smoothui.dev/r/content-skeleton.json` |
The CLI package is unchanged.
## 3.8.0 [#380]
These notes cover the August–September changes integrated for SmoothUI 3.8.0.
The separate CLI 1.1.3 release updates development test tooling only; it does not add CLI runtime features.
### Components, docs and quality [#components-docs-and-quality]
* Added 67 components with registry entries, documentation and examples, plus self-sizing preview frames.
* Expanded component accessibility coverage with axe tests and fixes, alongside reduced-motion and keyboard interaction checks.
* Updated Next.js to 16.3.3 and Sharp to 0.35.4, with patched same-major dependency floors for the production security audit; refined CI validation and release-flow checks.
* Completed the shared media dictionary migration across components, blocks and templates.
### Landing and Playground [#landing-and-playground]
* Added a draggable component canvas and refined the live component showcase, navigation, responsive layouts and documentation links.
* Consolidated theme exploration in the Playground, preserving shared preset URLs and the legacy themes route.
* Refined the hero, feature panels, AI workflow and UI Craft installation section with generated backgrounds and interactive UI previews.
* Added optional, non-interactive square and contour textures to selected artwork; other backgrounds remain clean.
* Separated readable feature captions from vivid artwork instead of dimming the entire image.
* Hardened inline clipboard feedback: failed writes allow retry without false success, command changes invalidate pending feedback, and timers are cleaned up on unmount.
* Kept the footer mascot interaction, while replacing the large installer mascot copy prompt with the compact shared copy control. The copy gutter now matches the command background in both themes.
### Original media library [#original-media-library]
* Added a searchable media gallery with 95 unique active assets: 12 abstract backgrounds, 8 landscapes, 4 event images, 50 people, 18 animals, 2 products and 1 fantasy card.
* Replaced legacy demo portraits with the generated Troupe cast, keeping source-provided identity and gender metadata; retained compatibility aliases without duplicating gallery entries.
* Replaced product imagery with ivory sneaker and headphones artwork, and the old tarot card with Nymara while preserving its complete card composition.
* Added meaningful mountain, sea, forest and event imagery for Photo Tabs, Apple Invites and Expandable Cards, plus distinct landscapes for Scrollable Card Stack and Image Metadata Preview.
* Centralized landing and demo image selection, updated misleading image labels and metadata, and documented asset provenance and rollback references.
### Blog and interaction fixes [#blog-and-interaction-fixes]
* Added topic-specific editorial cover compositions for all 15 blog posts: generated backgrounds, optional textures, frosted panels and neutral UI illustrations across landing cards, the blog index and article heroes.
* Kept valid canonical background images for social metadata and structured data; composed social images are not included in this update.
* Fixed Number Flow animation lifecycle cleanup and reduced-motion behavior, and matched homepage control proportions to the documentation example without changing its initial value.
* Fixed reduced-motion Scrollable Card Stack pagination: cards retain static centering and navigation stays above the card layers, preserving pointer and keyboard access.
* Improved event-card text contrast, responsive metadata layouts, image alternative text and demo identity consistency.
* Added targeted media, artwork, clipboard, geometry and responsive browser regression coverage.
For source history behind this release, see the
[August component expansion](https://github.com/educlopez/smoothui/commit/d4cf30e),
[accessibility audit](https://github.com/educlopez/smoothui/commit/6ea6727),
[component canvas and media dictionary](https://github.com/educlopez/smoothui/commit/c85e7ff),
[media migration fixes](https://github.com/educlopez/smoothui/commit/d7cf194)
and [September landing consolidation](https://github.com/educlopez/smoothui/commit/e66ddc5).
## 3.6.0 [#360]
### AI components [#ai-components]
* Twenty new components for agent surfaces: `ai-message`, `ai-response`, `ai-reasoning`, `ai-tool-call`, `ai-task-list`, `ai-diff`, `ai-artifact`, `ai-approval`, `ai-sources`, `ai-suggestions`, `ai-context-meter`, `ai-loader`, `ai-prompt-input`, `ai-conversation` and `ai-core`
* A shared **`AIState` contract** (`idle` -> `listening` -> `thinking` -> `streaming` -> `done` -> `error`) that every one of them reads, so a whole surface can be driven from one piece of state
* **`siri-orb`**: layered conic gradients animated through a registered `--angle` property, reacting to real microphone loudness
### Templates [#templates]
* New **[Templates](/docs/templates)** section: a whole product surface installed in one command, with every component it composes pulled in as a registry dependency
* **[Chat Template](/docs/templates/chat)** - sidebar, transcript and composer, with a scripted agent that exercises every AI component. No model, no network call, no API key
* Template pages lead with a live preview and screenshots rather than source, and list what installing gives you, read from the registry so it cannot drift
### Docs, rebuilt [#docs-rebuilt]
* **Component pages** split: the documentation scrolls, the component stays pinned beside it in an iframe, so the viewport switcher shows what a phone would actually show
* **Block pages** keep every control on the block it belongs to (Preview/Code, viewport, install command, add to bundle, Open in v0) because a page documenting five heroes cannot answer "the code of which one?"
* **Masonry indexes** for components and blocks, each card as tall as its own demo
* A **file tree** beside the source on block pages, keyed by the path each file lands at after installing
### Fixes worth knowing about [#fixes-worth-knowing-about]
* `text-primary` was invisible ink in both themes: `primary` is a surface here, not an accent. It affected an icon chip, a bento highlight, two link variants, a skeleton, and **ten focus rings across six components**
* Buttons had no pointer cursor after Tailwind v4 dropped it from Preflight
* Block sources never resolved in the docs, so no block ever showed its own code
* The chat template on a phone: the composer was cut off, the orb avatar was clipped, and there was no way to change conversation
## 3.5.0 [#350]
### Theme Studio [#theme-studio]
* New **[Playground](/playground)**: a draggable, infinite-canvas board previewing all 70 component demos with your theme applied live
* Dialkit-style inspector with palette, light/dark, font, neutral tint, a continuous radius scrubber, and an accent lightness scrubber
* Component search and one-click board re-centering
### Installable Themes & Presets [#installable-themes--presets]
* Six **`registry:theme`** items (`theme-candy` … `theme-green`) installable in any shadcn project — full token set, light and dark, Radix and Base UI compatible
* **SmoothUI presets**: shareable codes (`s1.…`) that round-trip the entire studio state via URL, and install as on-the-fly custom themes through `theme-custom-.json`
* Per-palette [shadcn/create](https://ui.shadcn.com/create) preset mapping, labeled as approximation
### Accessibility & Quality [#accessibility--quality]
* **100% `prefers-reduced-motion` compliance**: every animated block now renders statically under reduced motion (WCAG 2.1 SC 2.3.3)
* Fixed real accessibility violations caught by new tests: unlabeled logo links, unlabeled carousel buttons, invalid `` structure
* All images across the library are now non-draggable, so drag interactions never fight browser ghost-drags
### Registry & Infrastructure [#registry--infrastructure]
* Registry content rewriting: installed components and blocks now ship with fully resolvable imports (no more workspace specifiers leaking)
* Blocks correctly typed as `registry:block`; new `lib` (animation constants) and `data` items; AI **skill** item installable at `/r/skill.json`
* Test suite grew from 106 to 186 tests (every block and component covered) with coverage gates in CI, plus typecheck and registry-validation CI jobs
## 3.4.0 [#340]
### AI Integration [#ai-integration]
* Added **REST API** with 6 endpoints under `/api/v1/` for component discovery, search, and suggestions
* Added **OpenAPI 3.1 spec** at `/openapi.json` for programmatic access
* Added **`/llms-components.json`** machine-readable component catalog endpoint
* Enhanced **`/llms-full.txt`** with structured component metadata
* Added structured `smoothui` metadata to all **84 component and block** `package.json` files
* Added **AI Integration** and **REST API reference** docs pages
* Added animated **AI-Native** section to the landing page
### New Components [#new-components]
* Added **Book** component inspired by Vercel Geist
* Added **Exposure Slider** component inspired by iOS Camera
### Documentation [#documentation]
* Added per-component **accessibility documentation** across all components
* Added **bundle size badges** to component docs and gallery
* Added **Astro**, **Vite**, **Remix**, and **TanStack Start** framework integration guides
* Added **visual component gallery** with filtering, search, and live previews
* Added **community section** with component requests and showcase
### Fixes [#fixes]
* Resolved 12 Dependabot vulnerability alerts
* Fixed recently-modified indicator system and sorted sidebar components
## 3.3.0 [#330]
### New Components [#new-components-1]
* Added **Gooey Popover** component with SVG filter effects and GSAP
* Added **Agent Avatar** component for AI assistant interfaces
* Added **Animated Avatar Group** component with stacking animations
* Added **Animated Tooltip** component with spring transitions
* Added **Scrubber** component integrated with Grid Loader demo
### Enhancements [#enhancements]
* Enhanced **Grid Loader** with blur, gap, rounded props and redesigned customizer panel
* Added theme tokens for Scrubber, Grid Loader customizer, and reference links
* Added Vercel OSS Program badge and Speed Insights
* Improved structured data across docs site
### Fixes [#fixes-1]
* Fixed TweetCard 100% error rate on Vercel (removed isomorphic-dompurify)
* Reduced Vercel function GB-Hours usage
## 3.2.0 [#320]
### New Components [#new-components-2]
* Added **Grid Loader** component with 65 preset patterns
### CLI [#cli]
* Added standalone **SmoothUI CLI** with ASCII logo header and improved TUI
* Redesigned installer component with dual CLI tabs
* Added custom Shiki themes and global package manager state
### Blog & Landing [#blog--landing]
* Added interactive tutorial blog section
* Added CLI announcement badge to hero section
### Fixes [#fixes-2]
* Patched Dependabot security vulnerabilities
## 3.1.0 [#310]
### New Components [#new-components-3]
* Added **Magnetic Button** component with cursor-following magnetic effect and shadcn-style button variants
* Added **Notification Badge** component with dot, count, and status variants
* Added **Skeleton Loader** component with shimmer, pulse, and wave animation variants
* Added **Animated Tabs** component with underline, pill, and segment style variants
* Added **Animated Toggle** component with morph and icon transition variants
### New Blocks [#new-blocks]
* Added **FAQ 3** block with searchable questions and filter animations
* Added **FAQ 4** block with categorized questions and tab navigation
* Added **Footer 3** mega footer block with newsletter signup
* Added **Footer 4** minimal single-row footer block
* Added **Logo Cloud 3** block with infinite marquee and pause on hover
* Added **Logo Cloud 4** block with interactive grid and hover effects
## 3.0.6 [#306]
* Enhanced accessibility and keyboard navigation across all input components
* Added motion reduction support (`prefers-reduced-motion`) across components
* Integrated motion reduction in AI Branch component
## 3.0.5 [#305]
* Added **TweetCard** component for displaying Twitter/X posts with media support
* Enhanced TweetCard security with DOMPurify sanitization
## 3.0.4 [#304]
* Added **SwitchboardCard** component with animated light grid effect
* Added **Header 4** block with interactive 3D grid hero section
* Enhanced dropdown components with portal rendering and position handling
## 3.0.3 [#303]
* Added **Searchable Dropdown** component with search filtering and keyboard navigation
* Improved Wave Text animation performance
## 3.0.2 [#302]
* Added GlowHover component with cursor-following glow effect - generic and reusable component that works with any React element (cards, buttons, etc.)
* Added InfiniteSlider component for smooth, infinite scrolling with customizable speed and direction
* Added ReviewsCarousel component for displaying testimonials with smooth animations and keyboard navigation
* Enhanced AppleInvites component with responsive sizing and styling support
* Improved RSS feed processing for blocks with better categorization and date extraction
* Optimized image loading across components with enhanced getImageKitUrl options
* Refactored ScrollableCardStack component to use images instead of videos for better performance
* Fixed GitHub Stars Animation component issues
## 3.0.1 [#301]
* Added RSS feed integration using @wandry/analytics-sdk for component registry updates
* Fixed Safari rendering bug in Siri Orb component with improved mask-radius handling
* Created dedicated sponsors page with tier-based sections (Velocity, Supporters, Own Projects)
* Enhanced sponsor display components with rotation and empty state handling
## 3.0.0 [#300]
* Complete monorepo restructure with improved organization and maintainability
* Migrated to Next.js 16 with latest features and performance improvements
* Integrated Fumadocs for better documentation experience
* Added Ultracite for enhanced code quality and tooling
* Implemented Biome for fast linting and formatting
* Improved build system and package management
* Enhanced developer experience with better TypeScript configuration
* Updated all dependencies to latest stable versions
## 2.9.0 [#290]
* New Logo Clouds, Stats, Team, Footer, and FAQs blocks sections
* Enhanced sidebar filter system with All, Components, and Blocks categories
* Improved navigation with conditional sidebar content
* Better content organization separating components from blocks
## 2.8.0 [#280]
* New comprehensive search system with keyboard shortcuts and real-time results
* Advanced tag-based component discovery with categorized organization
* New tag pages with related components and category information
* Enhanced component search dialog with popular tags and smart suggestions
## 2.7.0 [#270]
* Full compatibility with shadcn CLI v3 namespace system
* New registry system with automatic dependency management
* MCP (Model Context Protocol) support for AI assistants
* Enhanced documentation with comprehensive installation guides
## 2.6.0 [#260]
* New AI section with AI-powered components
* New components: AI Input, AI Branch, Scrollable Card Stack, Rich Popover
* New AI menu in the landing page navigation
## 2.0.0 [#200]
* New Design System and website look
* New mascot called Smoothy
* Props documentation
* Color switcher
* Refine shadcn/ui installation
## 1.0.0 [#100]
* Initial release of SmoothUI
* Core component library with React and Framer Motion
* Basic documentation and examples
* CLI tool for component installation
# Design Principles (/docs/guides/design-principles)
## Design Philosophy [#design-philosophy]
SmoothUI is built on the principles of simplicity, accessibility, and performance. Each component is designed to be beautiful by default while remaining highly customizable.
## Color System [#color-system]
SmoothUI uses a carefully crafted color system based on OKLCH color space for better color consistency and accessibility. The system includes both light and dark variants.
### Brand Colors [#brand-colors]
### Neutral Colors [#neutral-colors]
The neutral color palette provides a range of grays that work well in both light and dark modes.
## Design System CSS [#design-system-css]
Add this CSS to your global styles to enable the full SmoothUI design system:
Expand CSS
```css title="global.css"
@import "tailwindcss";
@import "tw-animate-css";
@custom-variant dark (&:is(.dark *));
@theme inline {
--color-brand: var(--color-brand);
--color-brand-secondary: var(--color-brand-secondary);
--color-smooth-50: var(--color-smooth-50);
--color-smooth-100: var(--color-smooth-100);
--color-smooth-200: var(--color-smooth-200);
--color-smooth-300: var(--color-smooth-300);
--color-smooth-400: var(--color-smooth-400);
--color-smooth-500: var(--color-smooth-500);
--color-smooth-600: var(--color-smooth-600);
--color-smooth-700: var(--color-smooth-700);
--color-smooth-800: var(--color-smooth-800);
--color-smooth-900: var(--color-smooth-900);
--color-smooth-950: var(--color-smooth-950);
--color-smooth-1000: var(--color-smooth-1000);
--color-border: var(--color-smooth-500);
--color-sidebar-ring: var(--color-brand);
--color-sidebar-border: var(--color-smooth-400);
--color-sidebar-accent-foreground: var(--color-smooth-900);
--color-sidebar-accent: var(--sidebar-accent);
--color-sidebar-primary-foreground: var(--color-smooth-1000);
--color-sidebar-primary: var(--color-brand);
--color-sidebar-foreground: var(--color-smooth-1000);
--color-sidebar: var(--color-smooth-100);
--color-ring: var(--color-brand);
--color-input: var(--color-smooth-400);
--color-destructive: var(--destructive);
--color-accent-foreground: var(--color-smooth-1000);
--color-accent: var(--color-brand);
--color-muted-foreground: var(--color-smooth-800);
--color-muted: var(--color-smooth-200);
--color-background: var(--color-smooth-50);
--color-foreground: var(--color-smooth-1000);
--color-primary: var(--color-smooth-100);
--color-primary-foreground: var(--color-smooth-950);
--color-secondary: var(--color-smooth-200);
--color-secondary-foreground: var(--color-smooth-900);
--color-popover-foreground: var(--color-smooth-1000);
--color-popover: var(--color-smooth-50);
--color-card-foreground: var(--color-smooth-1000);
--color-card: var(--color-smooth-100);
--radius-sm: calc(var(--radius) - 4px);
--radius-md: calc(var(--radius) - 2px);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) + 4px);
}
:root {
--color-brand: oklch(0.72 0.2 352.53);
--color-brand-secondary: oklch(0.66 0.21 354.31);
--color-smooth-50: oklch(99.11% 0 0);
--color-smooth-100: oklch(97.91% 0 0);
--color-smooth-200: oklch(96.42% 0 0);
--color-smooth-300: oklch(94.61% 0 0);
--color-smooth-400: oklch(93.1% 0 0);
--color-smooth-500: oklch(91.28% 0 0);
--color-smooth-600: oklch(89.14% 0 0);
--color-smooth-700: oklch(82.97% 0 0);
--color-smooth-800: oklch(65% 0 0);
--color-smooth-900: oklch(61.67% 0 0);
--color-smooth-950: oklch(54.17% 0 0);
--color-smooth-1000: oklch(20.46% 0 0);
--border: var(--color-smooth-300);
--shimmer-highlight: var(--color-smooth-200);
--shimmer-base: var(--color-smooth-1000);
--radius: 0.625rem;
}
.dark {
--color-smooth-50: oklch(20.02% 0 0);
--color-smooth-100: oklch(22.64% 0 0);
--color-smooth-200: oklch(25.62% 0 0);
--color-smooth-300: oklch(27.68% 0 0);
--color-smooth-400: oklch(30.12% 0 0);
--color-smooth-500: oklch(32.5% 0 0);
--color-smooth-600: oklch(36.39% 0 0);
--color-smooth-700: oklch(43.13% 0 0);
--color-smooth-800: oklch(54.52% 0 0);
--color-smooth-900: oklch(59.31% 0 0);
--color-smooth-950: oklch(70.58% 0 0);
--color-smooth-1000: oklch(94.61% 0 0);
--border: var(--color-smooth-300);
--shimmer-highlight: var(--color-smooth-200);
--shimmer-base: var(--color-smooth-1000);
}
/* Component NumberFlow */
@layer utilities {
.slide-in-up {
animation: slideInUp 0.3s forwards;
}
.slide-out-up {
animation: slideOutUp 0.3s forwards;
}
.slide-in-down {
animation: slideInDown 0.3s forwards;
}
.slide-out-down {
animation: slideOutDown 0.3s forwards;
}
@keyframes slideInUp {
from {
transform: translateY(50px);
filter: blur(5px);
}
to {
transform: translateY(0px);
filter: blur(0px);
}
}
@keyframes slideOutUp {
from {
transform: translateY(0px);
filter: blur(0px);
}
to {
transform: translateY(-50px);
filter: blur(5px);
}
}
@keyframes slideInDown {
from {
transform: translateY(-50px);
filter: blur(5px);
}
to {
transform: translateY(0px);
filter: blur(0px);
}
}
@keyframes slideOutDown {
from {
transform: translateY(0px);
filter: blur(0px);
}
to {
transform: translateY(50px);
filter: blur(5px);
}
}
}
/* Component PowerOffSlide */
@layer utilities {
.loading-shimmer {
text-fill-color: transparent;
-webkit-text-fill-color: transparent;
animation-delay: 0.5s;
animation-duration: 3s;
animation-iteration-count: infinite;
animation-name: loading-shimmer;
background: var(--shimmer-base)
gradient(
linear,
100% 0,
0 0,
from(var(--shimmer-base)),
color-stop(0.5, var(--shimmer-highlight)),
to(var(--shimmer-base))
);
background: var(--shimmer-base) -webkit-gradient(
linear,
100% 0,
0 0,
from(var(--shimmer-base)),
color-stop(0.5, var(--shimmer-highlight)),
to(var(--shimmer-base))
);
background-clip: text;
-webkit-background-clip: text;
background-repeat: no-repeat;
background-size: 50% 200%;
display: inline-block;
}
.loading-shimmer {
background-position: -100% top;
}
.loading-shimmer:hover {
-webkit-text-fill-color: var(--shimmer-base);
animation: none;
background: transparent;
}
@keyframes loading-shimmer {
0% {
background-position: -100% top;
}
to {
background-position: 250% top;
}
}
}
/* Component AppleInvites */
@layer utilities {
.gradient-mask-t-0 {
-webkit-mask-image: linear-gradient(#0000, #000);
mask-image: linear-gradient(#0000, #000);
}
}
```
## Customization [#customization]
SmoothUI components are highly customizable. Here are the main ways to customize them:
Override CSS variables to customize colors, spacing, and other design tokens globally.
Use Tailwind utility classes to customize individual components or create variants.
Many components accept props for customization like size, variant, and color options.
# Getting Started (/docs/guides/getting-started)
## Prerequisites [#prerequisites]
Before you begin, make sure you have:
* **Node.js** 18.17 or later
* **React** 19 or later
* **Tailwind CSS** 4 or later configured in your project
* A package manager: pnpm (recommended), npm, yarn, or bun
Already have a project? Jump to the framework-specific setup:
* **[Next.js](/docs/guides/nextjs)** — Recommended for most projects
* **[Vite + React](/docs/guides/vite)** — Client-side React apps
* **[Astro](/docs/guides/astro)** — Islands architecture
* **[Remix](/docs/guides/remix)** — Full-stack SSR
* **[TanStack Start](/docs/guides/tanstack-start)** — Type-safe full-stack
***
## Step 1: Set Up a Next.js Project [#step-1-set-up-a-nextjs-project]
If you already have a project, skip to [Step 2](#step-2-initialize-shadcnui).
```bash
npx create-next-app@latest my-app --typescript --tailwind --app
cd my-app
```
***
## Step 2: Initialize shadcn/ui [#step-2-initialize-shadcnui]
SmoothUI builds on the shadcn ecosystem. If you haven't initialized shadcn yet:
Follow the prompts to configure your project. This sets up the `components.json` file and the utility functions SmoothUI components depend on.
***
## Step 3: Install Your First Component [#step-3-install-your-first-component]
SmoothUI is an official shadcn registry — no extra configuration needed. Install a component using either the SmoothUI CLI or the shadcn CLI:
### Option A: SmoothUI CLI (recommended) [#option-a-smoothui-cli-recommended]
### Option B: shadcn Registry [#option-b-shadcn-registry]
Both methods automatically install the component files and any required dependencies (like `motion`).
***
## Step 4: Use the Component [#step-4-use-the-component]
Import and render the component in your page:
```tsx title="app/page.tsx"
import SmoothButton from "@/components/smoothui/ui/SmoothButton"
export default function Home() {
return (
Click me
)
}
```
Start your dev server to see it in action:
You should see an animated button with smooth hover and press transitions.
***
## Step 5: Explore More Components [#step-5-explore-more-components]
Browse the full component library and install anything you need:
Running the add command without arguments launches interactive mode where you can search and select multiple components at once.
### Popular Components to Try [#popular-components-to-try]
* **[Expandable Cards](/docs/components/expandable-cards)** — Cards that expand with smooth spring animations
* **[Tabs](/docs/primitives/tabs)** — Tab navigation with motion indicator
* **[Siri Orb](/docs/components/siri-orb)** — Mesmerizing animated gradient orb
* **[Rich Popover](/docs/components/rich-popover)** — Contextual popover with fluid transitions
* **[Dynamic Island](/docs/components/dynamic-island)** — Apple-inspired adaptive container
***
## How It Works [#how-it-works]
SmoothUI components are **copied into your project** — not installed as a dependency. This means:
1. **Full ownership** — You can customize any component to fit your needs
2. **No version lock-in** — Components don't break when a library updates
3. **Tree-shakeable** — Only the components you install are in your bundle
4. **Type-safe** — Full TypeScript support with exported prop types
Components are installed to `components/smoothui/ui/` by default and use:
* **[Motion](https://motion.dev)** for spring-based animations
* **[Tailwind CSS](https://tailwindcss.com)** for styling
* **[shadcn/ui](https://ui.shadcn.com)** primitives where applicable
***
## Next Steps [#next-steps]
* **[Installation methods](/docs/guides/installation)** — Learn about all installation options in detail
* **[Animation best practices](/docs/guides/animation-best-practices)** — Understand how SmoothUI handles animations
* **[Design principles](/docs/guides/design-principles)** — The philosophy behind SmoothUI components
* **[SmoothUI vs shadcn](/docs/guides/shadcn-alternative)** — How SmoothUI complements shadcn/ui
# React Hooks (/docs/guides/hooks)
## Overview [#overview]
SmoothUI provides utility hooks that help you build responsive, device-aware components. These hooks are designed for performance and work seamlessly with Server-Side Rendering (SSR).
***
## useIsMobile [#useismobile]
Detects whether the current viewport is mobile-sized. Returns a boolean that updates in real-time as the viewport changes.
### Installation [#installation]
```bash
npx shadcn@latest add @smoothui/use-mobile
```
Or copy the hook directly:
```tsx
import * as React from "react";
const MOBILE_BREAKPOINT = 768;
export function useIsMobile() {
const [isMobile, setIsMobile] = React.useState(
undefined
);
React.useEffect(() => {
const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
const onChange = () => {
setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
};
mql.addEventListener("change", onChange);
setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
return () => mql.removeEventListener("change", onChange);
}, []);
return !!isMobile;
}
```
### Usage [#usage]
```tsx
import { useIsMobile } from "@/hooks/use-mobile";
function ResponsiveComponent() {
const isMobile = useIsMobile();
return (
{isMobile ? (
) : (
)}
);
}
```
### Parameters [#parameters]
This hook takes no parameters. The mobile breakpoint is set to **768px** by default.
### Returns [#returns]
| Value | Type | Description |
| ---------- | --------- | ------------------------------------------- |
| `isMobile` | `boolean` | `true` if viewport width is less than 768px |
### Features [#features]
* **SSR Safe**: Returns `false` during server-side rendering (no hydration mismatch)
* **Real-time Updates**: Responds to viewport changes via `matchMedia` listener
* **Performance Optimized**: Uses `matchMedia` instead of resize events for better performance
* **Memory Safe**: Properly cleans up event listeners on unmount
### Common Use Cases [#common-use-cases]
#### Conditional Rendering [#conditional-rendering]
```tsx
function Header() {
const isMobile = useIsMobile();
return (
);
}
```
#### Responsive Animations [#responsive-animations]
```tsx
import { motion } from "motion/react";
import { useIsMobile } from "@/hooks/use-mobile";
function AnimatedCard() {
const isMobile = useIsMobile();
return (
Card content
);
}
```
#### Responsive Grid [#responsive-grid]
```tsx
function ProductGrid({ products }) {
const isMobile = useIsMobile();
const columns = isMobile ? 1 : 3;
return (
{products.map(product => (
))}
);
}
```
### SSR Considerations [#ssr-considerations]
The hook returns `false` on the initial server render, then updates on the client. If you need to avoid layout shift, consider:
```tsx
function ResponsiveLayout() {
const isMobile = useIsMobile();
const [mounted, setMounted] = React.useState(false);
React.useEffect(() => {
setMounted(true);
}, []);
// Show a loading state or neutral layout until mounted
if (!mounted) {
return ;
}
return isMobile ? : ;
}
```
### Customizing the Breakpoint [#customizing-the-breakpoint]
If you need a different breakpoint, create a modified version:
```tsx
const TABLET_BREAKPOINT = 1024;
export function useIsTablet() {
const [isTablet, setIsTablet] = React.useState(
undefined
);
React.useEffect(() => {
const mql = window.matchMedia(`(max-width: ${TABLET_BREAKPOINT - 1}px)`);
const onChange = () => {
setIsTablet(window.innerWidth < TABLET_BREAKPOINT);
};
mql.addEventListener("change", onChange);
setIsTablet(window.innerWidth < TABLET_BREAKPOINT);
return () => mql.removeEventListener("change", onChange);
}, []);
return !!isTablet;
}
```
***
## Best Practices [#best-practices]
### Prefer CSS for Simple Responsive Layouts [#prefer-css-for-simple-responsive-layouts]
For simple responsive styling, CSS media queries are more performant than JavaScript:
```tsx
// Prefer CSS when possible
// Use hooks for complex logic or conditional rendering
const isMobile = useIsMobile();
if (isMobile) return
;
```
### Avoid Excessive Re-renders [#avoid-excessive-re-renders]
The hook only triggers re-renders when crossing the breakpoint threshold, not on every resize event.
### Test Across Devices [#test-across-devices]
Always test responsive behavior on actual devices, not just browser dev tools resizing.
***
## Related [#related]
Explore utility functions like cn() for class merging.
Learn how to create performant, accessible animations.
# Introduction (/docs/guides)
## What is SmoothUI? [#what-is-smoothui]
SmoothUI is a modern component library that brings together the best of React, Tailwind CSS, [Motion](https://motion.dev), and [GSAP](https://gsap.com) to create beautiful, accessible, and performant user interfaces. Each component is carefully crafted with smooth animations and thoughtful design principles.
## Key Features [#key-features]
* **shadcn CLI Compatible**: Install components using the familiar shadcn CLI
* **MCP Support**: AI assistants can discover and install components automatically
* **TypeScript First**: Full type safety with comprehensive TypeScript support
* **Accessible by Default**: Built with accessibility best practices
* **Dark Mode Support**: All components work seamlessly in light and dark themes
* **Customizable**: Easy to customize with Tailwind CSS classes
* **Performance Optimized**: Built with performance in mind using modern React patterns
## Get Started [#get-started]
1. **[Getting Started](/docs/guides/getting-started)** — project setup in under five minutes
2. **[Installation](/docs/guides/installation)** — CLI and manual install paths
3. **[Browse components](/docs/components)** — pick something animated and drop it in
Already on shadcn/ui? Jump to **[How to add animations](/docs/guides/add-animations-to-shadcn)** or the **[migration guide](/docs/guides/migration-from-shadcn)**.
Learn how to install SmoothUI components using shadcn CLI or manual installation methods.
Explore all available components with live demos and documentation.
## Frequently asked questions [#frequently-asked-questions]
Yes! SmoothUI is completely free and open source. You can use it in personal and commercial projects.
No! All animations are built-in. You can use components without any Motion or GSAP knowledge.
Absolutely! All components are built with Tailwind CSS and can be customized using standard Tailwind classes.
Yes! SmoothUI works with any React framework including Next.js, Vite, Create React App, and more.
## Contributing [#contributing]
We welcome contributions to SmoothUI! Whether you want to add new components, improve existing ones, or fix bugs, your contributions help make SmoothUI better for everyone.
* Fork the repository on GitHub
* Create a new branch for your feature or bug fix
* Make your changes and test them thoroughly
* Submit a pull request with a clear description
Check out our [contributing guide](https://github.com/educlopez/smoothui/blob/main/CONTRIBUTING.md) for more detailed information.
# Installation (/docs/guides/installation)
SmoothUI works with any React-compatible framework. Check out the dedicated setup guides:
* **[Vite + React](/docs/guides/vite)** — The simplest setup for client-side React apps
* **[Astro](/docs/guides/astro)** — Islands architecture with selective hydration
* **[Remix](/docs/guides/remix)** — Full-stack SSR with React Router v7
* **[TanStack Start](/docs/guides/tanstack-start)** — Type-safe full-stack with streaming SSR
## Installation (SmoothUI CLI) [#installation-smoothui-cli]
The SmoothUI CLI provides an interactive way to browse and install components with automatic dependency resolution.
Owned SmoothUI primitives (button, dialog, checkbox, …) ship on **Base UI** by
default (`/r/{name}.json` and `base-*` styles). Radix projects set a non-`base-*`
style and point at `https://smoothui.dev/r/{style}/{name}.json`. See
[Primitives](/docs/primitives).
### Add Components [#add-components]
### Add Multiple Components [#add-multiple-components]
### Interactive Mode [#interactive-mode]
### List Available Components [#list-available-components]
Run the add command without arguments to launch an interactive picker. Search and browse components by category, then select multiple components to install at once.
***
## Installation (shadcn Registry) [#installation-shadcn-registry]
SmoothUI is an official shadcn registry. Use the `@smoothui{:js}` namespace.
Owned primitives ship on **Base UI** by default; Radix projects should use the
style-aware registry URL.
```json
{
"style": "base-nova",
"registries": {
"@smoothui": "https://smoothui.dev/r/{style}/{name}.json"
}
}
```
Plain `@smoothui/...` installs get the Base twin. Set a non-`base-*` style plus
the style-aware URL above for Radix — see [Primitives](/docs/primitives).
### Install Components [#install-components]
Install SmoothUI components using the shadcn CLI with the `@smoothui{:js}` namespace:
### Install Multiple Components [#install-multiple-components]
### Use Components [#use-components]
Import and use the installed components in your React application:
```tsx
import { SiriOrb } from "@/components/smoothui/ui/SiriOrb"
import { RichPopover } from "@/components/smoothui/ui/RichPopover"
export default function App() {
return (
)
}
```
# MCP Server (/docs/guides/mcp)
MCP support for registry developers - Enable AI assistants to discover and use SmoothUI components.
The **shadcn MCP server** works out of the box with any shadcn-compatible registry. You do not need to do anything special to enable MCP support for your SmoothUI registry.
## Prerequisites [#prerequisites]
The MCP server works by requesting your registry index. Make sure you have a registry item file at the root of your registry named `registry.json{:js}`.
For example, if your registry is hosted at `https://smoothui.dev/r/[name].json{:js}`, you should have a file at `https://smoothui.dev/r/registry.json{:js}`.
This file must be a valid JSON file that conforms to the registry schema.
## Configuring MCP [#configuring-mcp]
Ask your registry consumers to configure your registry in their `components.json{:js}` file and install the shadcn MCP server:
**Configure your registry** in your `components.json{:js}` file:
```json title="components.json"
{
"registries": {
// [!code highlight]
"@smoothui": "https://smoothui.dev/r/{name}.json"
}
}
```
**Run the following command** in your project:
```shell title="Terminal"
pnpm dlx shadcn@latest mcp init --client claude
```
```shell title="Terminal"
npx shadcn@latest mcp init --client claude
```
```shell title="Terminal"
yarn dlx shadcn@latest mcp init --client claude
```
```shell title="Terminal"
bunx shadcn@latest mcp init --client claude
```
**Restart Claude Code** and try the following prompts:
* Show me the components in the smoothui registry
* Create a landing page using items from the smoothui registry
* Install the SiriOrb component from smoothui
**Note:** You can use `/mcp{:js}` command in Claude Code to debug the MCP server.
**Configure your registry** in your `components.json{:js}` file:
```json title="components.json"
{
"registries": {
// [!code highlight]
"@smoothui": "https://smoothui.dev/r/{name}.json"
}
}
```
**Run the following command** in your project:
```shell title="Terminal"
pnpm dlx shadcn@latest mcp init --client cursor
```
```shell title="Terminal"
npx shadcn@latest mcp init --client cursor
```
```shell title="Terminal"
yarn dlx shadcn@latest mcp init --client cursor
```
```shell title="Terminal"
bunx shadcn@latest mcp init --client cursor
```
Open **Cursor Settings** and **Enable the MCP server** for shadcn. Then try the following prompts:
* Show me the components in the smoothui registry
* Create a landing page using items from the smoothui registry
* Install the SiriOrb component from smoothui
**Configure your registry** in your `components.json{:js}` file:
```json title="components.json"
{
"registries": {
// [!code highlight]
"@smoothui": "https://smoothui.dev/r/{name}.json"
}
}
```
**Run the following command** in your project:
```shell title="Terminal"
pnpm dlx shadcn@latest mcp init --client vscode
```
```shell title="Terminal"
npx shadcn@latest mcp init --client vscode
```
```shell title="Terminal"
yarn dlx shadcn@latest mcp init --client vscode
```
```shell title="Terminal"
bunx shadcn@latest mcp init --client vscode
```
Open `.vscode/mcp.json{:js}` and click **Start** next to the shadcn server. Then try the following prompts with GitHub Copilot:
* Show me the components in the smoothui registry
* Create a landing page using items from the smoothui registry
* Install the SiriOrb component from smoothui
## Example Prompts [#example-prompts]
Once MCP is configured, you can use these prompts with your AI assistant:
Component Discovery
“Show me all available components in the smoothui registry”
“What animation components are available in smoothui?”
“List all interactive components from smoothui”
Component Installation
“Install the SiriOrb component from smoothui”
“Add the RichPopover component to my project”
“Install multiple components: SiriOrb, FloatInput, and ScrollableCardStack”
Component Usage
“Create a landing page using the SiriOrb component”
“Show me how to use the ScrollableCardStack component”
“Build a dashboard with smoothui components”
## Learn More [#learn-more]
Full overview of all AI integration options — MCP, REST API, and machine-readable catalogs.
Complete API reference for programmatic access to the component catalog.
You can also read more about the shadcn MCP protocol in the shadcn MCP documentation .
# Migration from shadcn (/docs/guides/migration-from-shadcn)
## Overview [#overview]
SmoothUI is designed to complement shadcn/ui, not replace it entirely. This guide covers how to swap specific shadcn components with their SmoothUI animated equivalents when you want to add motion and polish to your interface.
SmoothUI components are additive. You can migrate one component at a time without affecting the rest of your application. Both shadcn and SmoothUI components can coexist in the same project.
***
## Step 1: Install the SmoothUI Component [#step-1-install-the-smoothui-component]
Use either the SmoothUI CLI or the shadcn registry to add the component you want:
This installs the component to `components/smoothui/ui/` alongside your existing shadcn components in `components/ui/`.
***
## Step 2: Update Imports [#step-2-update-imports]
Replace the shadcn import with the SmoothUI import:
```tsx
// Before: shadcn/ui
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs"
// After: SmoothUI
import Tabs from "@/components/smoothui/ui/Tabs"
```
SmoothUI components use a **default export** pattern rather than named exports. Each component is a single self-contained import.
***
## Step 3: Adapt Props [#step-3-adapt-props]
SmoothUI components have their own prop interfaces. Here are the common patterns to adjust:
### Composition vs Props [#composition-vs-props]
shadcn uses a **compound component** pattern with multiple named exports. SmoothUI components are **single components** that accept data as props:
```tsx
// shadcn: Compound components
Tab 1
Tab 2
Content 1
Content 2
// SmoothUI: Data-driven props
Content 1 },
{ label: "Tab 2", content: Content 2
},
]}
/>
```
### Styling [#styling]
Both shadcn and SmoothUI use Tailwind CSS. SmoothUI components accept a `className` prop for customization:
```tsx
// Both support className for custom styling
```
***
## Component Mapping Reference [#component-mapping-reference]
Below is a mapping of shadcn components to their SmoothUI animated equivalents:
| shadcn/ui Component | SmoothUI Equivalent | Key Differences |
| ------------------- | --------------------------------------------------------------- | ------------------------------------------------------------ |
| `Tabs` | [Tabs](/docs/primitives/tabs) | Animated sliding indicator, data-driven API |
| `Dialog` | [Dialog](/docs/primitives/dialog) | Spring entrance animation, controlled via `isOpen`/`onClose` |
| `Toast` / `Sonner` | [Toast](/docs/primitives/toast) | Animated entrance/exit with spring physics |
| `Accordion` | [Accordion](/docs/components/accordion) | Smooth height animation with spring easing |
| `Tooltip` | [Tooltip](/docs/primitives/tooltip) | Spring-based show/hide with configurable delay |
| `DropdownMenu` | [Dropdown Menu](/docs/primitives/dropdown-menu) | Animated open/close with spring transitions |
| `Input` | [Animated Input](/docs/components/float-input) | Floating label animation, focus effects |
| `Toggle` | [Morph Toggle](/docs/components/morph-toggle) | Spring-based toggle with smooth state transitions |
| `Progress` | [Progress](/docs/primitives/progress) | Animated fill with spring physics |
| `Skeleton` | [Skeleton Loader](/docs/components/content-skeleton) | Enhanced shimmer animation |
| `Avatar` | [Animated Avatar Group](/docs/components/animated-avatar-group) | Staggered entrance, hover expansion |
***
## Disabling Animations [#disabling-animations]
If you need to disable animations for specific instances (for example, in a performance-critical area), SmoothUI components respect the system `prefers-reduced-motion` setting automatically.
To programmatically control animation behavior, you can wrap components and use the Motion library's `MotionConfig` provider:
```tsx
import { MotionConfig } from "motion/react"
// Disable all animations within this subtree
// Respect system setting (default behavior)
```
***
## Migration Checklist [#migration-checklist]
For each component you migrate:
* [ ] Install the SmoothUI component via CLI
* [ ] Update the import path from `@/components/ui/` to `@/components/smoothui/ui/`
* [ ] Adjust the JSX from compound component pattern to SmoothUI's prop-based API
* [ ] Verify the component renders correctly in development
* [ ] Test keyboard navigation still works as expected
* [ ] Test with `prefers-reduced-motion` enabled to verify graceful degradation
* [ ] Remove the old shadcn component file if it is no longer used elsewhere
***
## Keeping Both [#keeping-both]
You don't have to choose one or the other. A common pattern is:
* **shadcn/ui** for form primitives, data tables, and areas where animation adds no value
* **SmoothUI** for hero sections, interactive cards, navigation, and anywhere you want to add visual delight
Both libraries use Tailwind CSS and share the same design token system, so they integrate seamlessly.
# Next.js (/docs/guides/nextjs)
## Overview [#overview]
[Next.js](https://nextjs.org) is the recommended framework for SmoothUI. With App Router, React Server Components, and built-in Tailwind CSS support, Next.js provides the best developer experience for building animated interfaces. SmoothUI components work seamlessly with both the App Router and Pages Router.
SmoothUI components are React client components that use the `"use client"{:tsx}` directive. In Next.js App Router, they render on the server and hydrate on the client — animations start smoothly after hydration with no extra configuration.
## Prerequisites [#prerequisites]
Before getting started, make sure you have the following:
| Requirement | Minimum Version | Purpose |
| --------------------------------------- | --------------- | -------------------------- |
| [Node.js](https://nodejs.org/en) | 18+ | Runtime |
| [Next.js](https://nextjs.org) | 15.0+ | Framework |
| [React](https://react.dev) | 19.0+ | UI library |
| [Tailwind CSS](https://tailwindcss.com) | 4.0+ | Styling |
| [Motion](https://motion.dev) | 12.0+ | Animations (Framer Motion) |
## Project Setup [#project-setup]
### Create a New Next.js Project [#1-create-a-new-nextjs-project]
If you're starting from scratch, create a new Next.js project with TypeScript and Tailwind CSS:
```bash
npx create-next-app@latest my-smoothui-app --typescript --tailwind --app
cd my-smoothui-app
```
This scaffolds a Next.js project with App Router, TypeScript, and Tailwind CSS 4 pre-configured.
### Tailwind CSS 4 Configuration [#2-tailwind-css-4-configuration]
If you used `create-next-app` with the `--tailwind` flag, Tailwind CSS 4 is already configured. Your `app/globals.css` should contain:
```css title="app/globals.css"
@import "tailwindcss";
```
If you're adding Tailwind to an existing project, install it:
Then configure PostCSS:
```js title="postcss.config.mjs"
const config = {
plugins: {
"@tailwindcss/postcss": {},
},
};
export default config;
```
### Install Motion [#3-install-motion]
SmoothUI animations are powered by Motion (Framer Motion). Install it as a dependency:
### Initialize shadcn/ui [#4-initialize-shadcnui]
SmoothUI builds on the shadcn ecosystem. Initialize shadcn in your project:
Follow the prompts to configure your project. This sets up `components.json` and the `cn()` utility that SmoothUI components depend on.
## Installing SmoothUI Components [#installing-smoothui-components]
### Using the SmoothUI CLI [#using-the-smoothui-cli]
### Using the shadcn CLI [#using-the-shadcn-cli]
SmoothUI is an official shadcn registry. You don't need to add anything to `components.json{:json}` — just use the `@smoothui{:ts}` namespace and components are installed automatically.
## Server Component Boundaries [#server-component-boundaries]
Next.js App Router uses React Server Components by default. SmoothUI components include the `"use client"{:tsx}` directive, so they automatically become client components when imported. Here's what you need to know:
| Pattern | Behavior |
| ----------------------------------------------- | --------------------------------------------------------------------------------- |
| Import SmoothUI component in a Server Component | Works — the component boundary switches to client at the import. |
| Import SmoothUI component in a Client Component | Works — standard client-side rendering. |
| Pass Server Component children to SmoothUI | Works — Server Components can be passed as `children{:tsx}` to client components. |
| Use SmoothUI in `layout.tsx` | Works — layout renders on server, SmoothUI component hydrates on client. |
### Example: Server Component with SmoothUI [#example-server-component-with-smoothui]
```tsx title="app/page.tsx"
import { SiriOrb } from "@/components/smoothui/ui/SiriOrb";
import { MagneticButton } from "@/components/smoothui/ui/MagneticButton";
// This is a Server Component — SmoothUI components hydrate on the client
export default function Home() {
return (
SmoothUI + Next.js
Get Started
);
}
```
### Example: Passing Server Component Children [#example-passing-server-component-children]
```tsx title="app/page.tsx"
import { ExpandableCards } from "@/components/smoothui/ui/ExpandableCards";
// Server-fetched data passed to a client component
export default async function Page() {
const items = await fetchItems(); // Runs on the server
return (
);
}
```
You do **not** need to add `"use client"{:tsx}` to your page or layout files just because they use SmoothUI components. The directive is already in the component files themselves. Your pages stay as Server Components, keeping data fetching on the server.
## App Router vs Pages Router [#app-router-vs-pages-router]
SmoothUI works with both routing systems, but there are differences to be aware of:
### App Router (Recommended) [#app-router-recommended]
The App Router is the recommended approach. Server Components are the default, and SmoothUI's `"use client"{:tsx}` directive handles the boundary automatically.
```tsx title="app/dashboard/page.tsx"
import { AnimatedTabs } from "@/components/smoothui/ui/AnimatedTabs";
export default function Dashboard() {
return ;
}
```
### Pages Router [#pages-router]
In the Pages Router, every page is a client component by default, so there are no Server Component boundaries to consider. SmoothUI components work the same way as any other React component:
```tsx title="pages/dashboard.tsx"
import { AnimatedTabs } from "@/components/smoothui/ui/AnimatedTabs";
export default function Dashboard() {
return ;
}
```
Pages Router still uses SSR via `getServerSideProps{:ts}` or SSG via `getStaticProps{:ts}`. SmoothUI components render on the server and hydrate on the client — the same as App Router, just without the Server Component model.
## Custom Animated Components [#custom-animated-components]
If you create custom animated components alongside SmoothUI, follow the same pattern:
```tsx title="components/FadeIn.tsx"
"use client";
import { motion, useReducedMotion } from "motion/react";
import type { ReactNode } from "react";
export type FadeInProps = {
children: ReactNode;
};
const FadeIn = ({ children }: FadeInProps) => {
const shouldReduceMotion = useReducedMotion();
return (
{children}
);
};
export default FadeIn;
```
## Troubleshooting [#troubleshooting]
This means you're trying to use React hooks in a Server Component. SmoothUI components already include `"use client"{:tsx}`, so importing them in a Server Component should work. If you're building a custom wrapper, add `"use client"{:tsx}` at the top of that file.
Hydration mismatches happen when server-rendered HTML differs from client output. Common causes: using `Math.random(){:ts}`, `Date.now(){:ts}`, or browser APIs during render. Wrap those values in `useEffect{:tsx}` or use `useState{:tsx}` with an initial value that matches server output.
Verify that `@tailwindcss/postcss{:ts}` is configured in `postcss.config.mjs{:js}` and that `app/globals.css{:css}` contains `@import "tailwindcss"{:css}`. Also check that `globals.css` is imported in your root layout.
Next.js 15+ uses Turbopack in development by default. SmoothUI components are fully compatible with Turbopack. If you encounter issues, try running `next dev --no-turbopack` to verify the issue is Turbopack-related, then report it.
Motion supports tree-shaking, so only the features you use are included in your bundle. Import from `motion/react{:ts}` rather than `framer-motion{:ts}` for the smallest bundle. Next.js also optimizes client bundles automatically with code splitting.
## Next Steps [#next-steps]
Learn about all available installation methods including the SmoothUI CLI and shadcn registry.
Explore the complete collection of {COMPONENT_COUNT} animated React components.
Master animation performance, accessibility, and timing guidelines.
The simplest setup for using SmoothUI in a client-side React app.
# Remix (/docs/guides/remix)
## Overview [#overview]
[Remix](https://remix.run) is a full-stack React framework focused on web standards and progressive enhancement. As of v2, Remix has evolved into the framework mode of [React Router v7](https://reactrouter.com), bringing the same SSR-first architecture with a streamlined API. SmoothUI components work seamlessly in both Remix and React Router v7 projects.
SmoothUI components are standard React client components. Remix renders them on the server and hydrates them on the client. The `"use client"{:tsx}` directive ensures components with animations and browser APIs hydrate correctly. No special wrappers are needed for most components.
## Prerequisites [#prerequisites]
Before getting started, make sure you have the following:
| Requirement | Minimum Version | Purpose |
| -------------------------------------------------------------------- | --------------- | -------------------------- |
| [Node.js](https://nodejs.org/en) | 18+ | Runtime |
| [Remix](https://remix.run) / [React Router](https://reactrouter.com) | 2.0+ / 7.0+ | Framework |
| [React](https://react.dev) | 19.0+ | UI library |
| [Tailwind CSS](https://tailwindcss.com) | 4.0+ | Styling |
| [Motion](https://motion.dev) | 12.0+ | Animations (Framer Motion) |
Remix has merged into React Router v7. If you're starting a new project, use `create react-router{:bash}`. Existing Remix v2 projects can upgrade to React Router v7 — see the [migration guide](https://reactrouter.com/upgrading/remix). Both setups work identically with SmoothUI.
## Project Setup [#project-setup]
### Create a New Project [#1-create-a-new-project]
If you're starting from scratch, create a new React Router v7 project (the successor to Remix):
Then install dependencies:
### Set Up Tailwind CSS 4 [#2-set-up-tailwind-css-4]
Remix and React Router v7 use Vite under the hood, so Tailwind CSS 4 setup uses the Vite plugin:
Add the Tailwind CSS Vite plugin to your Vite config:
```ts title="vite.config.ts"
import { reactRouter } from "@react-router/dev/vite";
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";
import tsconfigPaths from "vite-tsconfig-paths";
export default defineConfig({
plugins: [tailwindcss(), reactRouter(), tsconfigPaths()],
});
```
Update your main CSS file with the Tailwind import:
```css title="app/app.css"
@import "tailwindcss";
```
### Install Motion [#3-install-motion]
SmoothUI animations are powered by Motion (Framer Motion). Install it as a dependency:
### Configure Path Aliases [#4-configure-path-aliases]
SmoothUI components use the `@/{:ts}` path alias. React Router v7 projects typically use `vite-tsconfig-paths{:ts}` to resolve paths from `tsconfig.json{:json}` automatically. Make sure your tsconfig includes the alias:
```json title="tsconfig.json"
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./app/*"]
}
}
}
```
React Router v7 projects include `vite-tsconfig-paths{:ts}` by default, which reads your `tsconfig.json{:json}` paths and applies them as Vite aliases. You only need to configure paths in one place — your tsconfig.
## Installing SmoothUI Components [#installing-smoothui-components]
### Using the SmoothUI CLI [#using-the-smoothui-cli]
### Using the shadcn CLI [#using-the-shadcn-cli]
If this is your first time using the shadcn CLI in a Remix / React Router project, it will prompt you to create a `components.json{:json}` file. Accept the defaults — the CLI auto-detects the project structure and configures paths accordingly.
## SSR Considerations [#ssr-considerations]
Remix and React Router v7 render components on the server first, then hydrate them on the client. Here's what you need to know when using SmoothUI components in an SSR environment:
| Concern | How SmoothUI Handles It |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| `"use client"` directive | SmoothUI components include this directive. Remix respects it for client-side hydration. |
| Motion SSR | Motion handles SSR gracefully — animations simply start after hydration. No special config needed. |
| Browser APIs | Components that use `window{:ts}` or `localStorage{:ts}` during render need a `ClientOnly` wrapper. |
| Hydration mismatches | Rare with SmoothUI. If seen, ensure no random values are generated during SSR (see Troubleshooting). |
### The ClientOnly Pattern [#the-clientonly-pattern]
If you use a SmoothUI component that relies on browser measurements during initial render, wrap it with a `ClientOnly` helper:
```tsx title="app/components/client-only.tsx"
"use client";
import { type ReactNode, useEffect, useState } from "react";
export type ClientOnlyProps = {
children: ReactNode;
fallback?: ReactNode;
};
const ClientOnly = ({ children, fallback = null }: ClientOnlyProps) => {
const [mounted, setMounted] = useState(false);
useEffect(() => {
setMounted(true);
}, []);
return mounted ? children : fallback;
};
export default ClientOnly;
```
```tsx title="app/routes/home.tsx"
import ClientOnly from "@/components/client-only";
import { SiriOrb } from "@/components/smoothui/ui/SiriOrb";
const Home = () => {
return (
}>
);
};
export default Home;
```
The majority of SmoothUI components work fine with SSR out of the box. Only use `ClientOnly` for components that access browser-only APIs like `window.matchMedia{:ts}` or `ResizeObserver{:ts}` during their initial render.
## Using Components in Routes [#using-components-in-routes]
Here is a complete example of using SmoothUI components in a Remix / React Router v7 route:
```tsx title="app/routes/home.tsx"
import { SiriOrb } from "@/components/smoothui/ui/SiriOrb";
import { MagneticButton } from "@/components/smoothui/ui/MagneticButton";
const Home = () => {
return (
SmoothUI + Remix
Get Started
);
};
export default Home;
```
### Custom Animated Components [#custom-animated-components]
If you create custom animated components alongside SmoothUI, follow the same pattern:
```tsx title="app/components/FadeIn.tsx"
"use client";
import { motion, useReducedMotion } from "motion/react";
import type { ReactNode } from "react";
export type FadeInProps = {
children: ReactNode;
};
const FadeIn = ({ children }: FadeInProps) => {
const shouldReduceMotion = useReducedMotion();
return (
{children}
);
};
export default FadeIn;
```
## Troubleshooting [#troubleshooting]
Hydration mismatches occur when the server-rendered HTML differs from what the client renders. Common causes: using `Math.random(){:ts}`, `Date.now(){:ts}`, or browser APIs during render. Use the `ClientOnly` pattern shown above for components that depend on browser-only values.
If you see `useLayoutEffect{:tsx}` warnings in your server logs, they're harmless — Motion uses `useLayoutEffect{:tsx}` for performance, and React warns when it's called during SSR. The animations will work correctly after hydration. To suppress the warning, you can use `client:only` or the `ClientOnly` wrapper.
Verify that `@tailwindcss/vite{:ts}` is included in your `vite.config.ts{:ts}` plugins array and that your `app/app.css{:css}` (or `app/root.css{:css}`) contains `@import "tailwindcss"{:css}`. Also check that the CSS file is imported in your root route.
When using `ClientOnly`, provide a `fallback{:tsx}` with the same dimensions as the component to prevent layout shifts. For example: ` }>{:tsx}`.
## Next Steps [#next-steps]
Learn about all available installation methods including the SmoothUI CLI and shadcn registry.
Explore the complete collection of {COMPONENT_COUNT} animated React components.
Master animation performance, accessibility, and timing guidelines.
The simplest setup for using SmoothUI in a client-side React app.
# SmoothUI vs shadcn/ui (/docs/guides/shadcn-alternative)
## The Best of Both Worlds [#the-best-of-both-worlds]
SmoothUI isn't a replacement for shadcn/ui - it's the perfect companion. While shadcn/ui excels at providing solid, accessible base components, SmoothUI extends the ecosystem with **animated, interactive components** that bring your interfaces to life.
## Why Choose SmoothUI? [#why-choose-smoothui]
### Smooth Motion Animations [#smooth-motion-animations]
Every SmoothUI component is built with **[Motion](https://motion.dev)** and **[GSAP](https://gsap.com)** animations that feel natural and polished. No more wrestling with CSS keyframes or animation libraries - animations are built-in and optimized for performance.
```tsx
// Just import and use - animations included
import { ExpandableCards } from "@/components/ui/expandable-cards"
```
### Same Workflow, Added Motion [#same-workflow-added-motion]
If you're familiar with shadcn/ui, you'll feel right at home. SmoothUI uses the **same CLI installation pattern**:
```bash
npx shadcn@latest add @smoothui/expandable-cards
```
Components are copied into your project, giving you full ownership and customization control.
### Built for Modern React [#built-for-modern-react]
SmoothUI components follow React best practices:
* **Server Components compatible** - Works with Next.js App Router
* **TypeScript first** - Full type definitions included
* **Tailwind CSS v4** - Uses the latest Tailwind features
* **Accessibility** - Respects `prefers-reduced-motion`
## Feature Comparison [#feature-comparison]
| Feature | shadcn/ui | SmoothUI |
| ------------------- | ------------ | ----------------- |
| Static Components | Excellent | Good |
| Animated Components | Limited | Excellent |
| Motion Animations | Manual setup | Built-in |
| Installation | shadcn CLI | shadcn CLI |
| Customization | Full control | Full control |
| TypeScript | Yes | Yes |
| Tailwind CSS | v3/v4 | v4 |
| Dark Mode | Yes | Yes |
| Accessibility | Excellent | Good |
| Component Count | 40+ | {COMPONENT_COUNT} |
## When to Use Each [#when-to-use-each]
### Use shadcn/ui for: [#use-shadcnui-for]
* Form inputs, selects, and form validation
* Modal dialogs and alert dialogs
* Navigation menus and dropdowns
* Data tables and pagination
* Basic buttons and badges
### Use SmoothUI for: [#use-smoothui-for]
* Animated card layouts and expandable cards
* Smooth hover effects and micro-interactions
* Dynamic content transitions
* Interactive showcases and galleries
* Animated text effects (typewriter, wave, scramble)
* Loading states with motion
## Working Together [#working-together]
The best approach is using both libraries together. Here's a typical setup:
```tsx
// shadcn/ui for the form structure
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Dialog, DialogContent } from "@/components/ui/dialog"
// SmoothUI for animated elements
import { FloatInput } from "@/components/ui/float-input"
import { ScrambleHover } from "@/components/ui/scramble-hover"
import { ExpandableCards } from "@/components/ui/expandable-cards"
```
Both libraries use the same folder structure (`components/ui/`) and Tailwind CSS foundation, making them seamlessly compatible.
## Get Started [#get-started]
Set up SmoothUI in your project alongside shadcn/ui.
Explore {COMPONENT_COUNT} animated components ready to use.
## Frequently asked questions [#frequently-asked-questions]
No! SmoothUI is designed to complement shadcn/ui, not replace it. Use shadcn/ui for forms and foundational UI, and add SmoothUI components when you need animations and interactivity.
Absolutely! Both libraries use the same installation pattern and folder structure. They work together seamlessly in the same project.
Minimal. If you're familiar with shadcn/ui, you already know the workflow. SmoothUI components follow the same patterns - just with added animations.
SmoothUI animations are built with Motion and GSAP, optimized for performance. They use GPU-accelerated transforms and respect the user's reduced motion preferences for accessibility.
# Sponsors (/docs/guides/sponsors)
# TanStack Start (/docs/guides/tanstack-start)
## Overview [#overview]
[TanStack Start](https://tanstack.com/start/latest) is a modern full-stack React framework built on [Vinxi](https://vinxi.vercel.app) (a Vite-based server toolkit) and [TanStack Router](https://tanstack.com/router/latest). It provides type-safe routing, streaming SSR, and server functions out of the box. SmoothUI components integrate smoothly with TanStack Start's architecture.
TanStack Start uses Vite under the hood via Vinxi, so SmoothUI components work the same way as in any Vite-based project. Components are server-rendered and hydrated on the client. The `"use client"{:tsx}` directive ensures animations activate after hydration.
TanStack Start is a newer framework that is evolving quickly. The setup steps below reflect the current stable release. Check the [official docs](https://tanstack.com/start/latest/docs/framework/react/overview) for the latest changes.
## Prerequisites [#prerequisites]
Before getting started, make sure you have the following:
| Requirement | Minimum Version | Purpose |
| --------------------------------------------------- | --------------- | -------------------------- |
| [Node.js](https://nodejs.org/en) | 18+ | Runtime |
| [TanStack Start](https://tanstack.com/start/latest) | 1.0+ | Framework |
| [React](https://react.dev) | 19.0+ | UI library |
| [Tailwind CSS](https://tailwindcss.com) | 4.0+ | Styling |
| [Motion](https://motion.dev) | 12.0+ | Animations (Framer Motion) |
## Project Setup [#project-setup]
### Create a New TanStack Start Project [#1-create-a-new-tanstack-start-project]
If you're starting from scratch, create a new TanStack Start project:
Then install dependencies:
### Set Up Tailwind CSS 4 [#2-set-up-tailwind-css-4]
TanStack Start uses Vinxi, which is built on Vite. Install Tailwind CSS and the Vite plugin:
Add the Tailwind CSS Vite plugin to your app config:
```ts title="app.config.ts"
import { defineConfig } from "@tanstack/react-start/config";
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({
vite: {
plugins: () => [tailwindcss()],
},
});
```
Create or update your main CSS file with the Tailwind import:
```css title="app/styles/app.css"
@import "tailwindcss";
```
Import the stylesheet in your root route (typically `app/routes/__root.tsx{:tsx}`):
```tsx title="app/routes/__root.tsx"
import { createRootRoute, Outlet } from "@tanstack/react-router";
import appCss from "@/styles/app.css?url";
export const Route = createRootRoute({
head: () => ({
links: [{ rel: "stylesheet", href: appCss }],
}),
component: RootComponent,
});
function RootComponent() {
return (
);
}
```
### Install Motion [#3-install-motion]
SmoothUI animations are powered by Motion (Framer Motion). Install it as a dependency:
### Configure Path Aliases [#4-configure-path-aliases]
SmoothUI components use the `@/{:ts}` path alias. Configure it in your `tsconfig.json{:json}`:
```json title="tsconfig.json"
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./app/*"]
}
}
}
```
TanStack Start resolves TypeScript paths automatically via Vinxi's Vite integration. If path aliases don't resolve at runtime, add `vite-tsconfig-paths{:ts}` to your app config:
```ts title="app.config.ts"
import { defineConfig } from "@tanstack/react-start/config";
import tailwindcss from "@tailwindcss/vite";
import tsconfigPaths from "vite-tsconfig-paths";
export default defineConfig({
vite: {
plugins: () => [tailwindcss(), tsconfigPaths()],
},
});
```
## Installing SmoothUI Components [#installing-smoothui-components]
### Using the SmoothUI CLI [#using-the-smoothui-cli]
### Using the shadcn CLI [#using-the-shadcn-cli]
If this is your first time using the shadcn CLI in a TanStack Start project, it will prompt you to create a `components.json{:json}` file. Configure the `aliases.components{:json}` path to match your project structure (typically `@/components{:json}`).
## SSR & Streaming [#ssr--streaming]
TanStack Start supports streaming SSR by default, which means components render progressively on the server. Here's what you need to know when using SmoothUI components:
| Concern | How SmoothUI Handles It |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| `"use client"` directive | SmoothUI components include this directive. TanStack Start respects it for client-side hydration. |
| Motion SSR | Motion handles SSR gracefully — animations start after hydration. No special config needed. |
| Streaming compatibility | SmoothUI components work with streaming SSR. Animations start as each component hydrates. |
| Browser APIs | Components using `window{:ts}` or `ResizeObserver{:ts}` during render need a client-only guard. |
### Client-Only Components [#client-only-components]
For the rare component that needs browser APIs during initial render, use a mounted check:
```tsx title="app/components/client-only.tsx"
"use client";
import { type ReactNode, useEffect, useState } from "react";
export type ClientOnlyProps = {
children: ReactNode;
fallback?: ReactNode;
};
const ClientOnly = ({ children, fallback = null }: ClientOnlyProps) => {
const [mounted, setMounted] = useState(false);
useEffect(() => {
setMounted(true);
}, []);
return mounted ? children : fallback;
};
export default ClientOnly;
```
## Using Components in Routes [#using-components-in-routes]
Here is a complete example of using SmoothUI components in a TanStack Start route:
```tsx title="app/routes/index.tsx"
import { createFileRoute } from "@tanstack/react-router";
import { SiriOrb } from "@/components/smoothui/ui/SiriOrb";
import { MagneticButton } from "@/components/smoothui/ui/MagneticButton";
export const Route = createFileRoute("/")({
component: Home,
});
function Home() {
return (
SmoothUI + TanStack Start
Get Started
);
}
```
### Custom Animated Components [#custom-animated-components]
If you create custom animated components alongside SmoothUI, follow the same pattern:
```tsx title="app/components/FadeIn.tsx"
"use client";
import { motion, useReducedMotion } from "motion/react";
import type { ReactNode } from "react";
export type FadeInProps = {
children: ReactNode;
};
const FadeIn = ({ children }: FadeInProps) => {
const shouldReduceMotion = useReducedMotion();
return (
{children}
);
};
export default FadeIn;
```
## Troubleshooting [#troubleshooting]
Verify that `@tailwindcss/vite{:ts}` is included in your `app.config.ts{:ts}` Vite plugins, and that your CSS file contains `@import "tailwindcss"{:css}`. Also check that the stylesheet is linked in your root route's `head{:tsx}` function.
TanStack Start uses Vinxi (Vite-based), which should resolve TypeScript paths. If aliases don't work, add `vite-tsconfig-paths{:ts}` to your `app.config.ts{:ts}` Vite plugins as shown in the setup section.
Hydration mismatches occur when server-rendered HTML differs from client output. Avoid using `Math.random(){:ts}`, `Date.now(){:ts}`, or browser APIs during render. For components that depend on client-only values, use the `ClientOnly` wrapper pattern.
With streaming SSR, components hydrate progressively. Animations using `initial{:tsx}` and `animate{:tsx}` props will play as each component hydrates — this is the expected behavior. If you want animations to trigger on scroll instead, use Motion's `whileInView{:tsx}` prop.
## Next Steps [#next-steps]
Learn about all available installation methods including the SmoothUI CLI and shadcn registry.
Explore the complete collection of {COMPONENT_COUNT} animated React components.
Master animation performance, accessibility, and timing guidelines.
Full-stack SSR setup with Remix and React Router v7.
# Themes (/docs/guides/themes)
SmoothUI ships complete color themes you can install in **any shadcn project** with one command — light and dark mode included, compatible with both Radix UI and Base UI primitives.
## Quick start [#quick-start]
Pick a palette and install it. The CLI writes every CSS variable into your global stylesheet:
```bash
npx shadcn@latest add https://smoothui.dev/r/theme-candy.json
```
Available themes: `theme-candy`, `theme-indigo`, `theme-blue`, `theme-red`, `theme-orange`, `theme-green`.
Each theme defines the full token set — backgrounds, foregrounds, borders, inputs, ring, charts, sidebar — using SmoothUI's smooth neutral scale with the palette's accent, in both `:root` and `.dark`.
## Theme Studio [#theme-studio]
[smoothui.dev/playground](https://smoothui.dev/playground) is an interactive studio: a draggable board previewing the entire component registry with your theme applied live.
* **Theme** — six accent palettes.
* **Mode** — preview light or dark.
* **Font** — Sans, Serif or Mono, applied to the preview and the exported CSS (`--font-sans`).
* **Tint** — re-tint the neutral scale: pure Neutral, Warm or Cool.
* **Radius** — a continuous 0–24px scrubber driving every `rounded-*` value.
* **Accent** — shift the accent's oklch lightness ±15 points.
Every card on the board shows a real component demo, links to its docs, and copies its install command.
## SmoothUI presets [#smoothui-presets]
The studio encodes your full configuration into a compact preset code:
```
s1.candy.16.20.mono.warm
```
Unlike shadcn/create presets (limited to their catalog values), SmoothUI presets carry the exact oklch palette, continuous radius, accent shift, font and tint. Three ways to use one:
### Share it [#share-it]
`Copy preset link` produces a URL that restores every control:
```
https://smoothui.dev/playground?preset=s1.candy.16.20.mono.warm
```
### Install it [#install-it]
Any custom configuration is installable directly — the registry builds the theme on the fly from the code:
```bash
npx shadcn@latest add https://smoothui.dev/r/theme-custom-s1.candy.16.20.mono.warm.json
```
### Copy the CSS [#copy-the-css]
`Copy CSS variables` exports the exact `:root` / `.dark` blocks for manual pasting, always reflecting the current controls.
## shadcn/create interop [#shadcncreate-interop]
Each palette also maps to the closest [shadcn/create](https://ui.shadcn.com/create) preset (for example Candy ≈ `b3gmgq`, their pink). The studio links to it as an **approximation**: shadcn's preset system only supports its own catalog values, so the exact SmoothUI palette, tint and accent shift don't survive the round trip. For full fidelity, use SmoothUI presets.
# Utility Functions (/docs/guides/utilities)
## Overview [#overview]
SmoothUI provides utility functions that simplify common patterns in React development. These utilities are used throughout the component library and are available for your own components.
***
## cn() - Class Name Utility [#cn---class-name-utility]
The `cn()` function merges class names intelligently, combining the power of [clsx](https://github.com/lukeed/clsx) for conditional classes and [tailwind-merge](https://github.com/dcastil/tailwind-merge) for resolving Tailwind CSS conflicts.
### Installation [#installation]
The `cn()` utility is included with any SmoothUI component installation. You can also install it directly:
```bash
pnpm add clsx tailwind-merge
```
Then create the utility:
```tsx
// lib/utils.ts
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
```
### Usage [#usage]
```tsx
import { cn } from "@/lib/utils";
function Button({ className, variant, ...props }) {
return (
);
}
```
### Why cn()? [#why-cn]
#### Problem: Tailwind Class Conflicts [#problem-tailwind-class-conflicts]
Without `cn()`, Tailwind classes can conflict unpredictably:
```tsx
// Without cn() - which padding wins? Unpredictable!
// If className="p-2", result is "p-4 p-2" - browser uses last one (p-2)
// But this isn't guaranteed and varies by property
```
#### Solution: Smart Merging [#solution-smart-merging]
`cn()` intelligently resolves conflicts:
```tsx
// With cn() - consumer override always wins
// If className="p-2", result is "p-2" - clean, predictable
```
### Features [#features]
#### Conditional Classes [#conditional-classes]
```tsx
cn(
"base-class",
isActive && "active-class", // Boolean condition
!isDisabled && "enabled-class", // Negated condition
error ? "error-class" : "success" // Ternary
)
```
#### Object Syntax [#object-syntax]
```tsx
cn({
"bg-blue-500": variant === "primary",
"bg-gray-500": variant === "secondary",
"opacity-50 cursor-not-allowed": isDisabled,
})
```
#### Array Syntax [#array-syntax]
```tsx
cn([
"base-styles",
conditionalStyles,
[nestedArray, "also-works"]
])
```
#### Tailwind Conflict Resolution [#tailwind-conflict-resolution]
```tsx
// Input
cn("px-4 py-2", "px-6")
// Output: "py-2 px-6" (px-6 wins, py-2 preserved)
// Input
cn("text-red-500", "text-blue-500")
// Output: "text-blue-500" (last color wins)
// Input
cn("hover:bg-red-500", "hover:bg-blue-500")
// Output: "hover:bg-blue-500" (handles modifiers correctly)
```
### Common Patterns [#common-patterns]
#### Component Variants [#component-variants]
```tsx
const buttonVariants = {
primary: "bg-blue-500 text-white hover:bg-blue-600",
secondary: "bg-gray-200 text-gray-900 hover:bg-gray-300",
ghost: "bg-transparent hover:bg-gray-100",
};
const buttonSizes = {
sm: "px-3 py-1.5 text-sm",
md: "px-4 py-2 text-base",
lg: "px-6 py-3 text-lg",
};
function Button({ variant = "primary", size = "md", className, ...props }) {
return (
);
}
```
#### Forwarding className [#forwarding-classname]
Always accept and forward `className` as the last argument to `cn()`:
```tsx
// Correct: className last, can override anything
function Card({ className, ...props }) {
return (
);
}
// Usage
// Result: p-8 and shadow-lg override defaults
```
#### With cva (Class Variance Authority) [#with-cva-class-variance-authority]
`cn()` pairs well with [cva](https://cva.style/docs) for complex variant systems:
```tsx
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";
const buttonVariants = cva(
"inline-flex items-center justify-center rounded-md font-medium",
{
variants: {
variant: {
default: "bg-primary text-primary-foreground hover:bg-primary/90",
outline: "border border-input bg-background hover:bg-accent",
},
size: {
default: "h-10 px-4 py-2",
sm: "h-9 px-3",
lg: "h-11 px-8",
},
},
defaultVariants: {
variant: "default",
size: "default",
},
}
);
interface ButtonProps
extends React.ButtonHTMLAttributes,
VariantProps {}
function Button({ className, variant, size, ...props }: ButtonProps) {
return (
);
}
```
### TypeScript [#typescript]
The `cn()` function is fully typed:
```tsx
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
// ClassValue accepts:
// - string
// - number
// - boolean | null | undefined (falsy values ignored)
// - ClassValue[] (arrays)
// - { [key: string]: boolean } (objects)
```
***
## Animation Constants [#animation-constants]
Several SmoothUI components share a small set of animation constants — spring
configs, easing curves, and durations — so motion feels consistent across the
library. They live in `lib/animation.ts` and follow the project's [animation
guidelines](/docs/guides/animation-best-practices) (durations of 0.2–0.25s and
bounce ≤ 0.1 for standard UI).
### Installation [#installation-1]
You don't install these directly. Any component that uses them (for example
`pagination`, `select`, `combobox`, `dropdown-menu`, `context-menu`,
`radio-group`, `checkbox`, `form`, or `breadcrumb`) lists them as a registry
dependency, so `shadcn` pulls `lib/animation.ts` into your project automatically:
```bash
npx shadcn@latest add @smoothui/pagination
```
The file lands at `components/smoothui/lib/animation.ts` and the component's
imports resolve to `@/components/smoothui/lib/animation`. There is no standalone
install for that shared file — pull it in by installing a component that uses it.
### Available Constants [#available-constants]
```tsx
// components/smoothui/lib/animation.ts
/** Default spring for most UI animations */
export const SPRING_DEFAULT = { type: "spring", duration: 0.25, bounce: 0.1 };
/** Snappy spring for quick, no-overshoot transitions */
export const SPRING_SNAPPY = { type: "spring", duration: 0.2, bounce: 0 };
/** Ease-out for entering elements — cubic-bezier(.23, 1, .32, 1) */
export const EASE_OUT = [0.23, 1, 0.32, 1] as const;
/** Ease-in-out for moving elements — cubic-bezier(0.645, 0.045, 0.355, 1) */
export const EASE_IN_OUT = [0.645, 0.045, 0.355, 1] as const;
/** Instant transition for reduced-motion contexts */
export const DURATION_INSTANT = { duration: 0 };
/** Standard animation durations (seconds) */
export const DURATION = { fast: 0.15, default: 0.25, slow: 0.3, complex: 0.4 } as const;
```
### Usage [#usage-1]
Feed them straight into Motion's `transition` prop, and swap to
`DURATION_INSTANT` when the user prefers reduced motion:
```tsx
import { motion, useReducedMotion } from "motion/react";
import { SPRING_DEFAULT, DURATION_INSTANT } from "@/components/smoothui/lib/animation";
function Panel() {
const shouldReduceMotion = useReducedMotion();
return (
);
}
```
Use the easing curves anywhere Motion accepts an `ease` value:
```tsx
import { EASE_OUT } from "@/components/smoothui/lib/animation";
```
***
## Best Practices [#best-practices]
### Always Use cn() for Component Styling [#always-use-cn-for-component-styling]
```tsx
// Good: Allows overrides, resolves conflicts
className={cn("base-styles", className)}
// Avoid: No conflict resolution
className={`base-styles ${className}`}
```
### Keep Base Styles First [#keep-base-styles-first]
```tsx
cn(
"base-styles", // 1. Foundational styles
"variant-styles", // 2. Variant-specific
"state-styles", // 3. State-based (hover, active)
className // 4. Consumer overrides (last!)
)
```
### Use Semantic Groups [#use-semantic-groups]
```tsx
cn(
// Layout
"flex items-center gap-2",
// Sizing
"h-10 px-4",
// Typography
"text-sm font-medium",
// Colors
"bg-blue-500 text-white",
// Interactions
"hover:bg-blue-600 focus:ring-2",
// Overrides
className
)
```
***
## Related [#related]
Explore SmoothUI hooks like useIsMobile.
Learn more about Tailwind class conflict resolution.
Learn more about conditional class name construction.
# Vite + React (/docs/guides/vite)
## Overview [#overview]
[Vite](https://vite.dev) is a fast build tool that provides an excellent developer experience for React projects. SmoothUI components work out of the box with Vite — no special configuration or SSR workarounds needed. This is the simplest way to get started with SmoothUI.
Vite + React is a purely client-side setup by default. SmoothUI components render directly in the browser with full access to DOM APIs, so every animation feature — spring physics, gestures, layout animations, and `AnimatePresence{:tsx}` — works without any additional setup.
## Prerequisites [#prerequisites]
Before getting started, make sure you have the following:
| Requirement | Minimum Version | Purpose |
| --------------------------------------- | --------------- | -------------------------- |
| [Node.js](https://nodejs.org/en) | 18+ | Runtime |
| [Vite](https://vite.dev) | 6.0+ | Build tool |
| [React](https://react.dev) | 19.0+ | UI library |
| [Tailwind CSS](https://tailwindcss.com) | 4.0+ | Styling |
| [Motion](https://motion.dev) | 12.0+ | Animations (Framer Motion) |
## Project Setup [#project-setup]
### Create a New Vite + React Project [#1-create-a-new-vite--react-project]
If you're starting from scratch, create a new Vite project with the React TypeScript template:
Then install dependencies:
### Set Up Tailwind CSS 4 [#2-set-up-tailwind-css-4]
Install Tailwind CSS and the Vite plugin:
Add the Tailwind CSS Vite plugin to your Vite config:
```ts title="vite.config.ts"
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({
plugins: [react(), tailwindcss()],
});
```
Replace the contents of your main CSS file with the Tailwind import:
```css title="src/index.css"
@import "tailwindcss";
```
### Install Motion [#3-install-motion]
SmoothUI animations are powered by Motion (Framer Motion). Install it as a dependency:
### Configure Path Aliases [#4-configure-path-aliases]
SmoothUI components use the `@/{:ts}` path alias. Configure it in both `vite.config.ts{:ts}` and `tsconfig.json{:json}`:
```ts title="vite.config.ts"
import path from "node: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"),
},
},
});
```
```json title="tsconfig.app.json"
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"]
}
}
}
```
Vite uses the `resolve.alias{:ts}` config for runtime path resolution, while TypeScript uses `paths{:json}` in `tsconfig.app.json{:json}` for type checking. You need both for everything to work correctly.
## Installing SmoothUI Components [#installing-smoothui-components]
### Using the SmoothUI CLI [#using-the-smoothui-cli]
### Using the shadcn CLI [#using-the-shadcn-cli]
If this is your first time using the shadcn CLI in a Vite project, it will prompt you to create a `components.json{:json}` file. Accept the defaults — the CLI auto-detects Vite + React projects and configures paths accordingly.
## Using Components [#using-components]
Here is a complete example of using SmoothUI components in your Vite + React app:
```tsx title="src/App.tsx"
import { SiriOrb } from "@/components/smoothui/ui/SiriOrb";
import { MagneticButton } from "@/components/smoothui/ui/MagneticButton";
const App = () => {
return (
SmoothUI + Vite
Get Started
);
};
export default App;
```
### Custom Animated Components [#custom-animated-components]
If you create custom animated components alongside SmoothUI, follow the same pattern:
```tsx title="src/components/FadeIn.tsx"
"use client";
import { motion, useReducedMotion } from "motion/react";
import type { ReactNode } from "react";
export type FadeInProps = {
children: ReactNode;
};
const FadeIn = ({ children }: FadeInProps) => {
const shouldReduceMotion = useReducedMotion();
return (
{children}
);
};
export default FadeIn;
```
The `"use client"{:tsx}` directive at the top of component files is a Next.js convention. Vite ignores it, so it does no harm — and it keeps your components compatible if you ever migrate to a framework with SSR support.
## Troubleshooting [#troubleshooting]
Make sure the `@tailwindcss/vite{:ts}` plugin is included in your `vite.config.ts{:ts}` plugins array, and that your `src/index.css{:css}` contains `@import "tailwindcss"{:css}`. Also verify that `index.css{:css}` is imported in your `src/main.tsx{:tsx}` entry file.
You need path aliases configured in **two places**: `resolve.alias{:ts}` in `vite.config.ts{:ts}` for Vite's bundler, and `paths{:json}` in `tsconfig.app.json{:json}` for TypeScript. If only one is configured, you'll get either build errors or type errors.
Vite's HMR requires that React components are exported as named or default exports from files that only export components. If HMR breaks, try restarting the dev server with `pnpm dev`. Also ensure `@vitejs/plugin-react{:ts}` is in your Vite config.
Motion supports tree-shaking, so only the features you use are included in your bundle. If you want to verify, run `pnpm build` and inspect the output. For the smallest bundle, import directly from `motion/react{:ts}` rather than `framer-motion{:ts}`.
## Next Steps [#next-steps]
Learn about all available installation methods including the SmoothUI CLI and shadcn registry.
Explore the complete collection of {COMPONENT_COUNT} animated React components.
Master animation performance, accessibility, and timing guidelines.
Learn how to use SmoothUI components in Astro with islands architecture.