# React Bits User Guide

React Bits is an open-source collection of **130+ animated, interactive, and fully customizable React components** — text animations, UI elements, and shader-powered backgrounds — designed to help you build memorable interfaces fast. Unlike a traditional component library, React Bits is **not a dependency you import**: you copy each component's source straight into your project (manually or via a one-time CLI command), so the code is yours to own, read, and modify.

This guide shows you how to browse the catalog, install components in the flavor you prefer (JavaScript or TypeScript, plain CSS or Tailwind), customize them through props, and use the AI-assisted (MCP) and creative-tool workflows. Written from the project source.

> [!NOTE]
> React Bits ships every component in **four variants** — `JS-CSS`, `JS-TW` (Tailwind), `TS-CSS`, and `TS-TW`. You pick the variant when you install; there is no separate package to add to `package.json`.

---

## Table of Contents

1. [Quick Start](#1-quick-start)
2. [What React Bits Is (and Isn't)](#2-what-react-bits-is-and-isnt)
3. [Requirements](#3-requirements)
4. [Installation](#4-installation)
5. [Choosing a Variant](#5-choosing-a-variant)
6. [Everyday Usage](#6-everyday-usage)
7. [Customizing Components with Props](#7-customizing-components-with-props)
8. [AI-Assisted Install (MCP Server)](#8-ai-assisted-install-mcp-server)
9. [Creative Tools](#9-creative-tools)
10. [Performance Best Practices](#10-performance-best-practices)
11. [Component Catalog](#11-component-catalog)
12. [Troubleshooting](#12-troubleshooting)
13. [FAQ](#13-faq)
14. [Reference](#14-reference)

---

## 1. Quick Start

Add your first component in seconds. The example below pulls the **Aurora** background into your project using the [shadcn](https://ui.shadcn.com/) CLI in the TypeScript + Tailwind variant:

```bash
npx shadcn@latest add @react-bits/Aurora-TS-TW
```

Then use it like any other React component:

```jsx
import Aurora from "./components/Aurora";

export default function Hero() {
  return (
    <div style={{ position: "relative", height: "100vh" }}>
      <Aurora colorStops={["#5227FF", "#7cff67", "#5227FF"]} amplitude={1.0} blend={0.5} />
    </div>
  );
}
```

That's the whole loop: **browse → install → use → customize via props.**

> [!TIP]
> Prefer not to use a CLI? Every component page on [reactbits.dev](https://reactbits.dev) has a **Code** tab where you can copy the source directly and paste it into your own file. The CLI and manual methods fetch the exact same code.

> [!IMPORTANT]
> React Bits components are copied **into your codebase**. After installing, the component lives in your repo — you maintain and customize it yourself. There is nothing to keep up to date via a package manager.

---

## 2. What React Bits Is (and Isn't)

React Bits is built on four principles, taken directly from the project's own introduction:

- **Free For All** — You own the code, and it's free to use in your projects. Every component you bring in is yours to modify or extend, because you get full visibility of the source, not just an import.
- **Prop-First Approach** — Components are designed to be customized through thoughtfully exposed props, so you can adjust the look and feel without diving into the code.
- **Fully Modular** — You install strictly what you need. React Bits is **not** a classic NPM library; you never pull in a whole package.
- **Free Choice** — JavaScript or TypeScript, plain CSS or Tailwind. The code is all there for you to use as you see fit.

**This is not a generic UI kit.** You won't find buttons, inputs, or form controls here. React Bits focuses on *expressive* components — animated text, cursor effects, 3D and shader backgrounds, and eye-catching cards and menus — meant to help your project stand out visually.

| React Bits is… | React Bits is not… |
|----------------|--------------------|
| A catalog of copy-in animated components | An `npm install react-bits` dependency |
| Source code you own and edit | A black-box compiled package |
| Framework-agnostic within React (works with any modern React project) | A full design system with form primitives |
| Distributed via shadcn / jsrepo registries | Published to the npm registry |

> [!NOTE]
> Official ports exist for other frameworks: **Vue** at [vue-bits.dev](https://vue-bits.dev/) and **Svelte** at [sveltebits.xyz](https://sveltebits.xyz/). This guide covers the React edition.

---

## 3. Requirements

React Bits components are dropped into *your* React application, so the requirements are whatever your app already uses, plus any libraries an individual component depends on.

| Requirement | Detail |
|-------------|--------|
| **React** | A modern React project (React 18+; the React Bits site itself runs on React 19). |
| **Build tooling** | Any modern bundler — Vite, Next.js, Create React App, Remix, etc. Components are plain `.jsx`/`.tsx` files. |
| **Node.js + a package manager** | Required only to run the CLI installer (`npx`, `pnpm dlx`, `bunx`, or `yarn dlx`) and to install per-component dependencies. |
| **Tailwind CSS** | Required **only** if you choose a Tailwind variant (`JS-TW` / `TS-TW`). |
| **Per-component libraries** | Some components pull in external libraries (e.g. `gsap`, `three`, `ogl`, `motion`). Each component page lists what to install. |

> [!TIP]
> Components have **minimal, opt-in dependencies**. A pure-canvas effect like `ClickSpark` needs nothing extra, while a GSAP-driven text animation needs `gsap`, and a shader background needs a WebGL library such as `ogl` or `three`. You only install what the components you actually use require.

---

## 4. Installation

There are three ways to bring a component into your project. All of them deliver identical source code — pick whichever fits your workflow.

### 4.1 Method 1 — CLI (shadcn or jsrepo)

React Bits supports two CLI installers: [**shadcn**](https://ui.shadcn.com/) and [**jsrepo**](https://jsrepo.dev/). Both fetch the same component source; pick whichever you prefer.

=== "shadcn"

    ```bash
    npx shadcn@latest add @react-bits/<Component>-<LANG>-<STYLE>
    ```

    The `@react-bits` shorthand requires the registry to be configured in your `components.json` (see [section 8](#8-ai-assisted-install-mcp-server)). You can also use the full URL form, which needs no configuration:

    ```bash
    npx shadcn@latest add https://reactbits.dev/r/<Component>-<LANG>-<STYLE>
    ```

=== "jsrepo"

    ```bash
    npx jsrepo@latest add https://reactbits.dev/r/<Component>-<LANG>-<STYLE>
    ```

    jsrepo can also pull directly from the GitHub repository:

    ```bash
    npx jsrepo@latest add github/davidhaz/react-bits <Component>-<LANG>-<STYLE>
    ```

Replace the placeholders:

- `<Component>` — the PascalCase component name, e.g. `SplitText`, `Aurora`, `Dock`.
- `<LANG>` — `JS` or `TS`.
- `<STYLE>` — `CSS` or `TW` (Tailwind).

**Concrete examples:**

```bash
# BlurText, TypeScript + Tailwind, via shadcn
npx shadcn@latest add @react-bits/BlurText-TS-TW

# Aurora background, JavaScript + plain CSS, via jsrepo URL
npx jsrepo@latest add https://reactbits.dev/r/Aurora-JS-CSS

# Dock, TypeScript + plain CSS, via jsrepo from GitHub
npx jsrepo@latest add github/davidhaz/react-bits Dock-TS-CSS
```

> [!TIP]
> You can run any of these with another package manager — just swap the runner prefix:
>
> | Package manager | Runner prefix |
> |-----------------|---------------|
> | npm | `npx` |
> | pnpm | `pnpm dlx` |
> | Bun | `bunx --bun` |
> | Yarn | `yarn dlx` |

### 4.2 Method 2 — Manual copy

If you'd rather not use a CLI, copy the code by hand:

1. **Pick a component.** Preview components on [reactbits.dev](https://reactbits.dev) until you find one you like, then open the **Code** tab.
2. **Install dependencies.** A component may use external libraries. Switch the code controls to **Manual** to see the install command, then run it. For example:
   ```bash
   npm install gsap
   ```
3. **Copy the code.** The **Code** tab contains the full component source. Use the technology toggle to switch between JS/TS and CSS/Tailwind before copying.
4. **Use the component.** A basic usage example is provided for every component:
   ```jsx
   import SplitText from "./SplitText";

   <SplitText
     text="Hello, you!"
     delay={100}
     duration={0.6}
   />
   ```

### 4.3 Method 3 — AI assistant (MCP)

You can also browse, search, and install components by talking to an AI coding assistant such as Claude Code, Cursor, or VS Code Copilot. See [section 8](#8-ai-assisted-install-mcp-server) for setup.

> [!IMPORTANT]
> After installation, the component is **part of your project**. From here on, it's about how you integrate it — modify styling, behavior, anything goes. The code is yours.

---

## 5. Choosing a Variant

Every component is available in four variants. Choose the one that matches your project's language and styling approach.

| Variant code (shadcn) | Variant code (jsrepo) | Language | Styling |
|-----------------------|-----------------------|----------|---------|
| `JS-CSS` | `default` | JavaScript | Plain CSS |
| `JS-TW` | `tailwind` | JavaScript | Tailwind CSS |
| `TS-CSS` | `ts/default` | TypeScript | Plain CSS |
| `TS-TW` | `ts/tailwind` | TypeScript | Tailwind CSS |

How the variant maps onto what you install:

- **Plain-CSS variants** ship the component file plus a matching `.css` file you import.
- **Tailwind variants** ship a single component file with styling applied through Tailwind utility classes — no separate stylesheet.
- **TypeScript variants** ship `.tsx` files with typed props.

> [!TIP]
> The React Bits site header has a dropdown that remembers your preferred **language** and **styling**, so the copy-ready commands and code snippets on every component page default to your chosen variant.

> [!WARNING]
> Tailwind variants assume Tailwind CSS is configured in your project. If you install a `-TW` variant into a project without Tailwind, the component will render unstyled. Either set up Tailwind or choose a `-CSS` variant instead.

---

## 6. Everyday Usage

### 6.1 The component categories

React Bits organizes its catalog into four categories. Use these to navigate the site and to reason about which `<Category>` a component belongs to when installing.

| Category | What it contains | Examples |
|----------|------------------|----------|
| **Text Animations** | Effects applied to text | `SplitText`, `BlurText`, `GlitchText`, `CountUp` |
| **Animations** | Cursor effects, hover effects, and motion wrappers | `ClickSpark`, `Magnet`, `StarBorder`, `ImageTrail` |
| **Components** | Interactive UI pieces | `Dock`, `Carousel`, `Stepper`, `MagicBento`, `ProfileCard` |
| **Backgrounds** | Full-surface shader / canvas backgrounds | `Aurora`, `Silk`, `Galaxy`, `Dither`, `Particles` |

The full list is in the [Component Catalog](#11-component-catalog).

### 6.2 A complete usage example

After installing a component, import it and render it. Here is a text animation that reveals on scroll:

```jsx
import SplitText from "./SplitText";

export default function Title() {
  return (
    <SplitText
      text="Make a statement."
      delay={50}
      duration={1.25}
      splitType="chars"
      from={{ opacity: 0, y: 40 }}
      to={{ opacity: 1, y: 0 }}
      textAlign="center"
    />
  );
}
```

### 6.3 Using a background component

Background components fill their container, so give the container an explicit size and position your content above it:

```jsx
import Aurora from "./Aurora";

export default function Landing() {
  return (
    <section style={{ position: "relative", minHeight: "100vh" }}>
      {/* Background sits behind everything */}
      <div style={{ position: "absolute", inset: 0, zIndex: 0 }}>
        <Aurora colorStops={["#5227FF", "#7cff67", "#5227FF"]} blend={0.5} amplitude={1.0} />
      </div>

      {/* Foreground content */}
      <div style={{ position: "relative", zIndex: 1 }}>
        <h1>Welcome</h1>
      </div>
    </section>
  );
}
```

> [!NOTE]
> Many backgrounds and animations render to a `<canvas>` or WebGL surface sized to their parent element. If a component appears blank, confirm its parent has a non-zero width and height.

### 6.4 Wrapping content with an effect

Some animations are **wrappers** — they take `children` and apply an effect to whatever you nest inside. `ClickSpark`, for example, emits a spark burst at the click position over its children:

```jsx
import ClickSpark from "./ClickSpark";

<ClickSpark sparkColor="#fff" sparkCount={8} sparkRadius={15} duration={400}>
  <button>Click me</button>
</ClickSpark>
```

---

## 7. Customizing Components with Props

React Bits is **prop-first**: nearly all customization is done by passing props, so you rarely need to edit the source.

### 7.1 Where to find a component's props

- **The Preview tab** on each component's page at [reactbits.dev](https://reactbits.dev) is the authoritative, interactive prop reference. It lets you change every prop live and watch the result — and it generates the matching code for you.
- **The source file** you installed lists every prop in the component's function signature, with default values.

> [!TIP]
> Because you own the source after installing, the component file itself is your most reliable prop reference. Open it and read the destructured props at the top of the function — each one shows its default value.

### 7.2 Representative prop examples

The exact props differ per component, but the patterns are consistent. Here are three real components from across the catalog:

**`SplitText`** (Text Animations) — animates text character-by-character on scroll:

| Prop | Default | Description |
|------|---------|-------------|
| `text` | — | The string to animate (required). |
| `delay` | `50` | Stagger between elements, in milliseconds. |
| `duration` | `1.25` | Animation duration in seconds. |
| `ease` | `'power3.out'` | GSAP easing function. |
| `splitType` | `'chars'` | Split granularity: `'chars'`, `'words'`, or `'lines'`. |
| `from` | `{ opacity: 0, y: 40 }` | Starting style of each piece. |
| `to` | `{ opacity: 1, y: 0 }` | Ending style of each piece. |
| `threshold` | `0.1` | Scroll-trigger threshold (0–1). |
| `textAlign` | `'center'` | Text alignment. |
| `tag` | `'p'` | HTML tag to render. |
| `onLetterAnimationComplete` | — | Callback fired when the animation finishes. |

**`ClickSpark`** (Animations) — a canvas spark burst on click:

| Prop | Default | Description |
|------|---------|-------------|
| `sparkColor` | `'#fff'` | Color of the spark lines. |
| `sparkSize` | `10` | Length of each spark. |
| `sparkRadius` | `15` | How far sparks travel. |
| `sparkCount` | `8` | Number of sparks per click. |
| `duration` | `400` | Spark lifetime in milliseconds. |
| `easing` | `'ease-out'` | `'linear'`, `'ease-in'`, `'ease-in-out'`, or `'ease-out'`. |
| `extraScale` | `1.0` | Multiplier on the travel distance. |
| `children` | — | Content rendered beneath the spark layer. |

**`Aurora`** (Backgrounds) — a WebGL aurora gradient:

| Prop | Default | Description |
|------|---------|-------------|
| `colorStops` | `['#5227FF', '#7cff67', '#5227FF']` | Three colors that form the gradient ramp. |
| `amplitude` | `1.0` | Height/intensity of the aurora waves. |
| `blend` | `0.5` | Softness of the aurora's lower edge. |
| `speed` | `1.0` | Animation speed multiplier. |

> [!NOTE]
> These tables illustrate the *shape* of React Bits props — concise, well-named, with sensible defaults. For any specific component, the Preview tab and the installed source file give you the complete, current list.

### 7.3 Editing the source

Because the component is in your repo, you can go beyond props: change the markup, swap colors hard-coded in a shader, adjust timing curves, or strip out features you don't need. This is encouraged — *"the code is yours to play around with."*

---

## 8. AI-Assisted Install (MCP Server)

React Bits supports the **shadcn MCP server**, which lets an AI assistant browse, search, and install components from the registry using natural language. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that connects AI assistants to external tools and data.

### 8.1 Configure the registry

Add the `@react-bits` registry to your project's `components.json`:

```json
{
  "registries": {
    "@react-bits": "https://reactbits.dev/r/{name}.json"
  }
}
```

### 8.2 Initialize the MCP server for your client

Run the init command for your editor:

=== "Claude Code"

    ```bash
    npx shadcn@latest mcp init --client claude
    ```

    Restart Claude Code, then try prompts like the ones below. Use `/mcp` in Claude Code to debug the MCP server.

=== "Cursor"

    ```bash
    npx shadcn@latest mcp init --client cursor
    ```

    Open Cursor Settings and enable the shadcn MCP server, then try the prompts below.

=== "VS Code"

    ```bash
    npx shadcn@latest mcp init --client vscode
    ```

    Open `.vscode/mcp.json` and click **Start** next to the shadcn server, then try the prompts below.

### 8.3 Example prompts

Once the MCP server is running, you can ask your assistant things like:

- *"Show me all the available backgrounds from the React Bits registry"*
- *"Add the Dither background from React Bits to the page, make it purple"*
- *"Add a new section which fades in on scroll using FadeContent from React Bits"*

> [!TIP]
> To learn more about the shadcn MCP server, including manual setup for other clients, see the official documentation at [ui.shadcn.com/docs/mcp](https://ui.shadcn.com/docs/mcp).

---

## 9. Creative Tools

Beyond components, React Bits offers free creative tools at [reactbits.dev/tools](https://reactbits.dev/tools) to speed up your workflow.

| Tool | What it does |
|------|--------------|
| **Background Studio** | Explore animated backgrounds, customize their effects, and export as video, image, or code — or share your creations as URLs. |
| **Shape Magic** | Automatically create inner rounded corners between shapes of different sizes. Export as React code, SVG, or `clip-path` CSS. |
| **Texture Lab** | Apply 20+ effects (noise, dithering, halftone, ASCII art, and more) to images and videos, then export in high quality. Save presets for reuse. |

> [!NOTE]
> A tool listed as "Coming Soon" on the Tools page is not yet available; the interface will show a placeholder until it ships.

---

## 10. Performance Best Practices

React Bits components are animation-heavy — many run continuous WebGL shaders or `requestAnimationFrame` loops. The project's own guidance:

- **Less is more.** Using more than 2–3 animated components on a single page is not advised — it can overload the page with animations and hurt performance or UX.
- **Optimize for mobile.** Consider disabling heavier effects on mobile and replacing them with static placeholders.
- **Test thoroughly.** Your device may be high-end, but your users' devices vary. Always test on multiple devices before going live.

> [!CAUTION]
> Shader and physics backgrounds (e.g. `Galaxy`, `Ballpit`, `LiquidEther`, `Hyperspeed`) are the most GPU/CPU-intensive components. Running several at once, or leaving one mounted off-screen, can drive CPU usage high (see issue [#953](https://github.com/DavidHDev/react-bits/issues/953)). Unmount backgrounds that aren't visible.

> [!TIP]
> WebGL-based components clean up their GL context on unmount. If you mount and unmount many of them rapidly, you may hit the browser's WebGL context limit — keep the number of simultaneously mounted WebGL components small.

---

## 11. Component Catalog

React Bits ships **130+ components** across four categories, growing regularly. The lists below reflect the components in the current source. Component names are shown in PascalCase (the form you use when installing). Combine a name with a variant suffix to install it, e.g. `SplitText-TS-TW`.

### 11.1 Text Animations

| Component | What it does |
|-----------|--------------|
| `SplitText` | Splits text into characters/words for staggered entrance animation. |
| `BlurText` | Text starts blurred then crisply resolves. |
| `CircularText` | Lays out characters around a circle with optional rotation. |
| `TextType` | Typewriter effect with blinking cursor. |
| `Shuffle` | Characters shuffle before settling into the final text. |
| `ShinyText` | A metallic sheen sweeps across the text. |
| `TextPressure` | Characters scale/warp based on pointer pressure zone. |
| `CurvedLoop` | Looping text along a customizable curve with drag interaction. |
| `FuzzyText` | Vibrating fuzzy text with hover intensity control. |
| `GradientText` | Animated gradient sweep across live text. |
| `FallingText` | Characters fall with gravity and bounce. |
| `TextCursor` | Text follows the cursor, leaving a trail of copies. |
| `DecryptedText` | Hacker-style decryption cycling random glyphs. |
| `TrueFocus` | Dynamic blur/clarity moving across a series of words. |
| `ScrollFloat` | Text floats / parallax shifts on scroll. |
| `ScrollReveal` | Text unblurs and reveals on scroll. |
| `ASCIIText` | Renders text with an animated ASCII background. |
| `ScrambledText` | Cursor-driven distortion applied to text. |
| `RotatingText` | Cycles phrases with 3D rotate/flip transitions. |
| `GlitchText` | RGB split and distortion glitch effect. |
| `ScrollVelocity` | Marquee whose speed/distortion scales with scroll velocity. |
| `VariableProximity` | Letter styling changes with pointer distance. |
| `CountUp` | Animated number counter with formatting and decimals. |

### 11.2 Animations

| Component | What it does |
|-----------|--------------|
| `AnimatedContent` | Wrapper that animates children on scroll or mount. |
| `FadeContent` | Directional fade/slide entrance/exit wrapper. |
| `ElectricBorder` | Jittery electric energy border with animated arcs. |
| `OrbitImages` | SVG-path customizable orbiting images. |
| `PixelTransition` | Pixel dissolve transition on hover. |
| `GlareHover` | Moving glare highlight on hover. |
| `Antigravity` | 3D particle field that repels from the cursor. |
| `LogoLoop` | Looping marquee of brand/tech logos with hover pause. |
| `TargetCursor` | Cursor with four corners that lock onto targets. |
| `MagicRings` | Interactive magic rings effect. |
| `LaserFlow` | Dynamic laser light that flows onto a surface. |
| `MagnetLines` | Field lines that bend toward the cursor. |
| `GhostCursor` | Semi-transparent ghost cursor with trailing effect. |
| `GradualBlur` | Progressively un-blurs content for a cinematic reveal. |
| `ClickSpark` | Particle spark bursts at the click position. |
| `Magnet` | Elements magnetically ease toward the cursor. |
| `StickerPeel` | Sticker corner lift + peel interaction. |
| `PixelTrail` | Pixelated cursor trail of fading squares. |
| `Cubes` | 3D rotating cube cluster (auto-rotate or hover). |
| `MetallicPaint` | Liquid metallic paint shader for SVGs. |
| `Noise` | Animated film-grain / noise overlay. |
| `ShapeBlur` | Morphing blurred geometric shape on hover. |
| `Crosshair` | Custom crosshair cursor with tracking and hover effects. |
| `ImageTrail` | Cursor-based image trail with several variants. |
| `Ribbons` | Flowing physics-driven ribbons / cursor trail. |
| `SplashCursor` | Liquid splash burst at the cursor. |
| `MetaBalls` | Merging/separating liquid metaball blobs. |
| `BlobCursor` | Organic blob cursor with inertia and morphing. |
| `StarBorder` | Animated star/sparkle border orbiting content. |

### 11.3 Components

| Component | What it does |
|-----------|--------------|
| `AnimatedList` | List items enter with staggered motion. |
| `ScrollStack` | Overlapping card stack revealed on scroll. |
| `BubbleMenu` | Floating circular expanding menu. |
| `MagicBento` | Interactive bento grid with animated tiles. |
| `CircularGallery` | Circular orbit gallery of rotating images. |
| `ReflectiveCard` | Card with webcam reflection and cursor-driven glare. |
| `CardNav` | Expandable nav bar with card panels of nested links. |
| `Stack` | Layered stack with swipe animations and autoplay. |
| `FluidGlass` | Glassmorphism container with liquid distortion. |
| `PillNav` | Minimal pill nav with sliding active highlight. |
| `TiltedCard` | 3D perspective tilt card reacting to pointer. |
| `Masonry` | Responsive masonry layout with animated reflow. |
| `GlassSurface` | Apple-style glass surface with distortion + lighting. |
| `DomeGallery` | Immersive 3D dome gallery on a hemispheric surface. |
| `ChromaGrid` | Grayscale tile grid that reveals color on hover. |
| `Folder` | Interactive folder that opens to reveal content. |
| `StaggeredMenu` | Menu with staggered open/close item animations. |
| `ModelViewer` | Three.js model viewer with orbit controls and lighting. |
| `Lanyard` | Swinging 3D lanyard/badge card with inertial motion. |
| `ProfileCard` | Animated profile card with 3D hover and glare. |
| `Dock` | macOS-style magnifying dock with proximity scaling. |
| `GooeyNav` | Nav indicator that morphs with gooey blob transitions. |
| `PixelCard` | Card content revealed via pixel expansion. |
| `Carousel` | Responsive carousel with touch gestures and looping. |
| `SpotlightCard` | Cursor-following spotlight casting gradient light. |
| `BorderGlow` | Glowing mesh-gradient border that follows the cursor. |
| `FlyingPosters` | 3D posters that rotate on scroll infinitely. |
| `CardSwap` | Cards animate position swapping with layout transitions. |
| `GlassIcons` | Icon set styled with frosted glass blur. |
| `DecayCard` | Hover parallax that disintegrates card content. |
| `FlowingMenu` | Liquid flowing active indicator between menu items. |
| `ElasticSlider` | Slider handle that stretches elastically with spring physics. |
| `Counter` | Flexible animated counter with increments and easing. |
| `InfiniteMenu` | Horizontally looping menu that scrolls endlessly. |
| `Stepper` | Animated multi-step progress indicator. |
| `BounceCards` | Cards that bounce in on mount. |

### 11.4 Backgrounds

| Component | What it does |
|-----------|--------------|
| `Ferrofluid` | Churning magnetic fluid traced by glowing contours, with a cursor magnet. |
| `Lightfall` | Light streaks raining down a glowing tunnel with a cursor light. |
| `LiquidEther` | Interactive liquid shader with flowing distortion. |
| `Prism` | Rotating prism with configurable intensity, size, colors. |
| `DarkVeil` | Subtle dark background with smooth postprocessed animation. |
| `LightPillar` | Vertical pillar of light with glow effects. |
| `Silk` | Smooth waves with soft lighting. |
| `FloatingLines` | 3D floating lines reacting to the cursor. |
| `SideRays` | Animated light rays from the side. |
| `LightRays` | Volumetric light rays/beams with direction control. |
| `PixelBlast` | Exploding pixel bursts with optional liquid postprocessing. |
| `ColorBends` | Vibrant color bends with smooth flow. |
| `EvilEye` | Procedural evil-eye shader with animated iris and glow. |
| `LineWaves` | Animated line-wave pattern with warped distortion. |
| `Radar` | Radar sweep with rings, spokes, and a rotating beam. |
| `SoftAurora` | Soft aurora shader with 3D Perlin noise gradients. |
| `Aurora` | Flowing aurora gradient background. |
| `Plasma` | Organic plasma gradients with turbulence. |
| `PlasmaWave` | Raymarched plasma waves with dual-wave interference (OGL). |
| `Particles` | Configurable particle system. |
| `GradientBlinds` | Layered gradient blinds with spotlight and noise. |
| `Grainient` | Grainy gradient swirls with soft wave distortion. |
| `GridScan` | Animated 3D grid-room scan effect. |
| `Beams` | Crossing animated ribbons. |
| `PixelSnow` | Falling pixelated snow with density/speed control. |
| `Lightning` | Procedural lightning bolts with branching and glow. |
| `PrismaticBurst` | Burst of light rays with color/distortion control. |
| `Galaxy` | Parallax realistic starfield with pointer interaction. |
| `Dither` | Retro dithered-noise shader background. |
| `FaultyTerminal` | CRT scanline effect with flicker and noise. |
| `RippleGrid` | Grid that animates with a continuous ripple. |
| `DotField` | Interactive dot grid with cursor bulge, glow, sparkle, waves. |
| `DotGrid` | Animated dot grid with cursor interactions. |
| `Threads` | Animated line pattern with fabric-like motion. |
| `Hyperspeed` | Hyperspace-travel lines on click-hold. |
| `Iridescence` | Iridescent shader with shifting waves. |
| `Waves` | Layered lines forming smooth animated waves. |
| `GridDistortion` | Warped grid mesh reacting to the cursor. |
| `Ballpit` | Physics ball-pit simulation with bouncing spheres. |
| `Orb` | Floating energy orb with hover effect. |
| `LetterGlitch` | Matrix-style letter animation. |
| `GridMotion` | Perspective moving grid lines driven by cursor position. |
| `ShapeGrid` | Animated grid with shape variants and direction control. |
| `LiquidChrome` | Liquid metallic chrome shader. |
| `Balatro` | The Balatro shader, fully customizable and interactive. |

> [!NOTE]
> The catalog grows over time. The live, always-current list — with previews and per-component prop references — is at [reactbits.dev](https://reactbits.dev). Components marked **New** in the sidebar are the most recent additions.

---

## 12. Troubleshooting

Troubleshooting entries below are drawn from the project's source behavior and community-reported issues. Each lists the cause, the fix, and how to prevent it.

### Error: `Unexpected character ''. (1:4)` during `shadcn add`

**Cause:** Certain components (notably the **Lanyard** variants) bundle non-text assets (such as a 3D `.glb` model). Older registry/shadcn handling could choke on these binary files during install (issue [#960](https://github.com/DavidHDev/react-bits/issues/960)).

**Solution:** Update your installer to the latest version (`shadcn@latest` / `jsrepo@latest`). If the install still fails, use the **Manual** method from the component's Code tab and copy the files (including assets) by hand.

**Prevention:** Always pin `@latest` for the CLI, and prefer manual install for asset-heavy components like `Lanyard`, `ModelViewer`, and `FluidGlass`.

### Background renders as a blank black or transparent screen

**Cause:** The component's parent container has zero width/height, or the WebGL context failed to initialize. A blank "Browse All Components" page was also reported when a single component error broke the page (issue [#964](https://github.com/DavidHDev/react-bits/issues/964)).

**Solution:** Give the background's parent an explicit size (e.g. `height: 100vh` and `position: relative`). Check the browser console for WebGL errors. Ensure only one heavy WebGL background is mounted.

**Prevention:** Wrap background components in a sized, positioned container, and lazy-mount them only when visible.

### Error: WebGL `Context Lost`

**Cause:** The browser dropped the WebGL context — usually because too many WebGL components were mounted at once or the GPU was overloaded (issue [#728](https://github.com/DavidHDev/react-bits/issues/728)).

**Solution:** Reduce the number of simultaneously mounted WebGL components (shader backgrounds, 3D components). Unmount off-screen backgrounds. Reload the page to recreate the context.

**Prevention:** Follow the [performance guidance](#10-performance-best-practices) — 2–3 animated components per page maximum.

### CPU usage spikes to ~100% when using a component as a background

**Cause:** Continuous shader/physics animation loops run every frame. Several at once, or one left mounted off-screen, keep the CPU/GPU busy (issue [#953](https://github.com/DavidHDev/react-bits/issues/953)).

**Solution:** Use only one background at a time, unmount it when not visible, and consider a static image fallback on low-power devices and mobile.

**Prevention:** Test on representative hardware; gate heavy effects behind a device/perf check.

### Effect breaks or distorts on browser zoom

**Cause:** Some effects compute sizes from pixel measurements that shift when the browser zoom changes, so the layer can misalign (reported for `ElectricBorder`, issue [#962](https://github.com/DavidHDev/react-bits/issues/962)).

**Solution:** Reset the browser zoom to 100%, or remount the component after a zoom change so it re-measures its container.

**Prevention:** Avoid relying on these effects at non-default zoom levels in critical UI.

### A shader/3D background doesn't appear at all

**Cause:** Missing WebGL support, a missing per-component dependency (e.g. `ogl`, `three`), or a TypeScript type mismatch in newer dependency versions (reported for `Ballpit`, issue [#975](https://github.com/DavidHDev/react-bits/issues/975)).

**Solution:** Install the dependency the component requires (shown on its Code tab under **Manual**). For TS variants, ensure your `three`/`ogl` versions match the component's expectations; update the import if an API (e.g. `THREE.Clock` → `THREE.Timer`) changed.

**Prevention:** Install exactly the dependencies the component lists, and keep them aligned with the versions React Bits targets.

### A customization prop "doesn't work"

**Cause:** Passing a prop the component doesn't accept, or a documentation/prop mismatch (reported for `ShinyText`, issue [#950](https://github.com/DavidHDev/react-bits/issues/950)).

**Solution:** Open the installed component source and read the exact prop names and defaults at the top of the function. The source is the source of truth once installed.

**Prevention:** Use the Preview tab to confirm a prop exists before relying on it.

### Component is not keyboard accessible

**Cause:** Some interactive components are pointer-first and may not expose full keyboard navigation (reported for `Carousel` indicators, issue [#976](https://github.com/DavidHDev/react-bits/issues/976)).

**Solution:** Because you own the code, add `tabIndex`, `role`, and key handlers as needed for your accessibility requirements.

**Prevention:** Audit interactive components for keyboard and screen-reader support before shipping to production.

---

## 13. FAQ

**Q: Do I need to `npm install react-bits`?**
No. React Bits is not published as an npm package. You copy each component's source into your project, either with the CLI or manually.

**Q: Will I get updates automatically?**
No — and that's by design. Once a component is in your repo, it's yours. To pull a newer version of a component, re-run the install command or re-copy the code, then re-apply any local edits.

**Q: Is it free? Can I use it commercially?**
Yes. React Bits is licensed under **MIT + Commons Clause** — free for personal and commercial use. You own the code you install.

**Q: JavaScript or TypeScript? Tailwind or plain CSS?**
Your choice. Every component ships in all four combinations: `JS-CSS`, `JS-TW`, `TS-CSS`, `TS-TW`.

**Q: What's the difference between the shadcn and jsrepo installers?**
None in terms of the code you get — both fetch the same component source. Use whichever CLI you already have or prefer.

**Q: How many components can I safely put on one page?**
The project recommends no more than 2–3 animated components per page to avoid performance issues.

**Q: Can an AI assistant install components for me?**
Yes. React Bits supports the shadcn MCP server for Claude Code, Cursor, and VS Code. See [section 8](#8-ai-assisted-install-mcp-server).

**Q: Where do I find every prop for a component?**
Use the **Preview** tab on the component's page at [reactbits.dev](https://reactbits.dev), or read the installed source file — the props and their defaults are right at the top of the component function.

**Q: Can I contribute a new component?**
New community components are **not currently accepted** — only enhancements and bug fixes to existing components. See the [contribution guide](https://github.com/DavidHDev/react-bits/blob/main/CONTRIBUTING.md).

**Q: Does React Bits work with Next.js / Remix / CRA?**
Yes. Components are plain React files and work with any modern React setup. For server-rendered frameworks, mount WebGL/canvas backgrounds on the client (e.g. behind a dynamic import or an `useEffect` mount guard).

**Q: Is there a Vue or Svelte version?**
Yes — official ports at [vue-bits.dev](https://vue-bits.dev/) and [sveltebits.xyz](https://sveltebits.xyz/).

**Q: What is "React Bits Pro"?**
A separate paid offering ([pro.reactbits.dev](https://pro.reactbits.dev)) with additional components, UI blocks, and full templates. The components in this guide are the free, open-source library.

---

## 14. Reference

### 14.1 Install command cheat sheet

```bash
# shadcn (registry shorthand — requires components.json registry entry)
npx shadcn@latest add @react-bits/<Component>-<LANG>-<STYLE>

# shadcn (full URL — no config needed)
npx shadcn@latest add https://reactbits.dev/r/<Component>-<LANG>-<STYLE>

# jsrepo (URL)
npx jsrepo@latest add https://reactbits.dev/r/<Component>-<LANG>-<STYLE>

# jsrepo (from GitHub)
npx jsrepo@latest add github/davidhaz/react-bits <Component>-<LANG>-<STYLE>
```

### 14.2 Variant codes

| `<LANG>` | `<STYLE>` | Combined suffix | jsrepo path |
|----------|-----------|-----------------|-------------|
| `JS` | `CSS` | `JS-CSS` | `default` |
| `JS` | `TW` | `JS-TW` | `tailwind` |
| `TS` | `CSS` | `TS-CSS` | `ts/default` |
| `TS` | `TW` | `TS-TW` | `ts/tailwind` |

### 14.3 Package-manager runners

| Manager | Runner prefix |
|---------|---------------|
| npm | `npx` |
| pnpm | `pnpm dlx` |
| Bun | `bunx --bun` |
| Yarn | `yarn dlx` |

### 14.4 MCP registry config

```json
{
  "registries": {
    "@react-bits": "https://reactbits.dev/r/{name}.json"
  }
}
```

```bash
npx shadcn@latest mcp init --client <claude|cursor|vscode>
```

### 14.5 Links

| Resource | URL |
|----------|-----|
| Documentation & catalog | [reactbits.dev](https://reactbits.dev) |
| Quick Start | [reactbits.dev/get-started/installation](https://reactbits.dev/get-started/installation) |
| Creative Tools | [reactbits.dev/tools](https://reactbits.dev/tools) |
| GitHub repository | [github.com/DavidHDev/react-bits](https://github.com/DavidHDev/react-bits) |
| Issues / feature requests | [github.com/DavidHDev/react-bits/issues](https://github.com/DavidHDev/react-bits/issues) |
| shadcn MCP docs | [ui.shadcn.com/docs/mcp](https://ui.shadcn.com/docs/mcp) |
| Vue port | [vue-bits.dev](https://vue-bits.dev/) |
| Svelte port | [sveltebits.xyz](https://sveltebits.xyz/) |

### 14.6 License

**MIT + Commons Clause** — free for personal and commercial use. Maintained by **[David Haz](https://github.com/DavidHDev)**.

---

_Generated June 2026 from DavidHDev/react-bits at 9d0137e. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._