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
2. What React Bits Is (and Isn't)
3. Requirements
4. Installation
5. Choosing a Variant
6. Everyday Usage
7. Customizing Components with Props
8. AI-Assisted Install (MCP Server)
9. Creative Tools
10. Performance Best Practices
11. Component Catalog
12. Troubleshooting
13. FAQ
14. Reference

1. Quick Start

Add your first component in seconds. The example below pulls the Aurora background into your project using the shadcn CLI in the TypeScript + Tailwind variant:

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

Then use it like any other React component:

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 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.

Note

Official ports exist for other frameworks: Vue at vue-bits.dev and Svelte at 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.

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 and jsrepo. Both fetch the same component source; pick whichever you prefer.

shadcn

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). You can also use the full URL form, which needs no configuration:

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

jsrepo

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

jsrepo can also pull directly from the GitHub repository:

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:

# 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 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:

   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:

   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 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.

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.

The full list is in the 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:

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:

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:

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 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:

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

Aurora (Backgrounds) — a WebGL aurora gradient:

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) 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:

{
  "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

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

npx shadcn@latest mcp init --client cursor

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

VS Code

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.

9. Creative Tools

Beyond components, React Bits offers free creative tools at reactbits.dev/tools to speed up your workflow.

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). 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

11.2 Animations

11.3 Components

11.4 Backgrounds

Note

The catalog grows over time. The live, always-current list — with previews and per-component prop references — is at 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).

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).

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).

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 — 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).

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).

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).

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).

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).

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.

Q: Where do I find every prop for a component? Use the Preview tab on the component's page at 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.

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 and sveltebits.xyz.

Q: What is "React Bits Pro"? A separate paid offering (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

# 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

14.3 Package-manager runners

14.4 MCP registry config

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

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

14.5 Links

14.6 License

MIT + Commons Clause — free for personal and commercial use. Maintained by David Haz.