React Bits Pro Integration

You are integrating React Bits Pro — a premium, shadcn-compatible registry of 101 animated components, 238 page-section blocks (21 categories), and 11 landing-page templates for React/Next.js apps. Items install as real source files into the user's project; the user owns and can edit them.

This document is the single source of truth. Follow it literally. Where it says "verify," verify — do not guess.

Golden rules (read first, never break these)

1. Never guess a block's import statement. Block files use a mix of export default and named export styles, and the identifier does not reliably follow the slug (404-3 exports NotFound3; cta-3 exports CTA3 but cta-4 exports Cta4). After installing a block, read its export line and import accordingly. See Importing installed items.
2. Components use a -tw or -css suffix; blocks use no suffix. silk-waves-tw is a component; hero-1 is a block. Mismatched names return 404.
3. The license key is a secret. Put it in .env.local, never commit it, never hardcode it.
4. Never delete the "use client" directive. Every component and block is a client component.
5. WebGL/shader components need an explicitly sized parent (a container with width and height).
6. Do not overwrite the user's existing components.json fields — only merge in registries.
7. Templates are downloads, not CLI installs. They come as .zip files from the website. See Templates.

TL;DR — fastest correct path

# 0. (once) Ensure the project is a shadcn project with the cn() helper.
npx shadcn@latest init            # only if components.json is missing

# 1. Add the license key to .env.local (never commit it):
#    REACTBITS_LICENSE_KEY=rbp...-your-key

# 2. Merge the two registries into components.json (see Step 3 below).

# 3. Install items (components take -tw/-css; blocks take no suffix):
npx shadcn@latest add @reactbits-starter/silk-waves-tw
npx shadcn@latest add @reactbits-pro/hero-1

# 4. Open the installed file, read its `export` line, then import it:
#    components/react-bits/silk-waves.tsx  -> export default  -> import SilkWaves from "@/components/react-bits/silk-waves"
#    components/blocks/hero-1.tsx          -> export function Hero1  -> import { Hero1 } from "@/components/blocks/hero-1"

If components.json already has the @reactbits-starter registry, you can also pull this skill into the project as a local file:

npx shadcn@latest add @reactbits-starter/skill   # writes ./SKILL.md to the project root

When to use this skill

Use it when the user wants to:

• Add React Bits Pro components, blocks, or templates to a project.
• Add animated UI (shaders, particles, 3D, WebGL, cursor effects, text/Motion/GSAP animations).
• Drop in pre-built page sections (hero, pricing, features, navigation, footer, FAQ, CTA, etc.).
• Assemble a landing page quickly from premium blocks.
• Mention "react bits", "reactbits", "@reactbits-starter", or "@reactbits-pro".

Do not use it to build generic shadcn/ui primitives (button, dialog, etc.) — those come from the standard shadcn registry, not React Bits Pro.

Architecture overview

React Bits Pro ships through the shadcn registry protocol over two license-authenticated registries:

This installation has the Ultimate tier, so every component, block, and template is available.

Items are written into the codebase as editable source files — they are not npm packages.

Three product types — do not confuse them

Component variants (-tw vs -css)

Every component exists in two functionally identical variants. Pick exactly one per install.

• -tw (Tailwind) — styles via Tailwind utility classes and the cn() helper. Default choice. Use this whenever the project uses Tailwind.
• -css (vanilla CSS) — ships a co-located .css file, no Tailwind required. Use only when the project does not use Tailwind.

Blocks have no variants — they are Tailwind-only, single-file.

Where files are installed

Paths follow the user's components.json aliases (and src/ dir if present). With defaults:

The shadcn CLI auto-installs each item's npm dependencies and any registry dependencies.

Step 1 — Verify prerequisites

Confirm the project has all of the following before installing:

1. components.json at the project root. If missing:

   npx shadcn@latest init

2. The cn() helper at lib/utils.ts (required by every -tw component):

   import { clsx, type ClassValue } from "clsx";
   import { twMerge } from "tailwind-merge";
   
   export function cn(...inputs: ClassValue[]) {
     return twMerge(clsx(inputs));
   }

   If missing: npm install clsx tailwind-merge, then create the file above.
3. Tailwind CSS configured (for -tw components and all blocks). Tailwind v4 is strongly recommended — many blocks use v4-renamed utilities such as bg-linear-to-br (the v3 name is bg-gradient-to-br).
4. A valid license key. The user must have purchased a React Bits Pro plan. If they have not set one up, ask them for it (or point them to https://pro.reactbits.dev/pricing).

Step 2 — Configure the license key

Add the key to .env.local at the project root:

REACTBITS_LICENSE_KEY=rbpu-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

• Never commit .env.local. Ensure .gitignore includes it (shadcn's init does this by default).
• The shadcn CLI reads this value to fill the ${REACTBITS_LICENSE_KEY} placeholder in components.json.
• If the CLI cannot find the variable, export it in the shell before running add:

  export REACTBITS_LICENSE_KEY=rbpu-...

• This license is the Ultimate tier (prefix rbpu-), which unlocks everything.

Step 3 — Configure components.json

Merge the registries object into the existing components.json. Add only this key — do not touch $schema, style, tailwind, aliases, or any other existing field.

{
  "registries": {
    "@reactbits-starter": {
      "url": "https://pro.reactbits.dev/api/r/starter/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REACTBITS_LICENSE_KEY}"
      }
    },
    "@reactbits-pro": {
      "url": "https://pro.reactbits.dev/api/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REACTBITS_LICENSE_KEY}"
      }
    }
  }
}

The {name} token is replaced by the slug you pass to add. ${REACTBITS_LICENSE_KEY} is read from the environment / .env.local. Configure @reactbits-starter even if you only plan to use blocks — it is also how you install this skill file.

Step 4 — Install items

Components require a -tw or -css suffix. Blocks take no suffix.

# Component — Tailwind variant (default choice)
npx shadcn@latest add @reactbits-starter/silk-waves-tw

# Component — vanilla-CSS variant (non-Tailwind projects only)
npx shadcn@latest add @reactbits-starter/silk-waves-css

# Block
npx shadcn@latest add @reactbits-pro/hero-1

# Several at once (components + blocks can be mixed)
npx shadcn@latest add @reactbits-starter/silk-waves-tw @reactbits-starter/animated-list-tw @reactbits-pro/hero-1 @reactbits-pro/pricing-2

Optional — inspect an item before installing:

npx shadcn@latest view @reactbits-starter/silk-waves-tw

Importing installed items

This is the step agents most often get wrong. Get the export style right and the import follows.

Components — always a default export

Every @reactbits-starter component is export default. Import it with any local name you like (no braces):

import SilkWaves from "@/components/react-bits/silk-waves";
import AnimatedList from "@/components/react-bits/animated-list";

Blocks — mixed export styles, so verify every time

Block files are not consistent: some are export default function X() and some are export function X(). The identifier also does not reliably match the slug. Always confirm the export line, then import accordingly.

One reliable command to reveal it:

grep -E "^export (default )?function " components/blocks/<slug>.tsx

Apply this rule to the result:

Examples:

// hero-1.tsx contains:  export function Hero1()      -> NAMED import, exact identifier
import { Hero1 } from "@/components/blocks/hero-1";

// 404-3.tsx contains:   export default function NotFound3()  -> DEFAULT import, free name
import ErrorPage from "@/components/blocks/404-3";

// pricing-2.tsx contains: export default function Pricing2()  -> DEFAULT import
import Pricing from "@/components/blocks/pricing-2";

Block import reference (verified)

If you cannot open the file, use this table. Named-export blocks must be imported with the exact identifier in braces. Default-export blocks can be imported with any name (the listed identifier is the file's own name, shown for reference). Watch the irregular casing.

Named exports → import { Identifier } from "@/components/blocks/<slug>":

Default exports → import AnyName from "@/components/blocks/<slug>":

If this table ever disagrees with the installed file, trust the file and re-run the grep check above.

Using an installed component

import SilkWaves from "@/components/react-bits/silk-waves";

export default function Page() {
  return (
    // WebGL/shader components require a sized parent:
    <div className="h-screen w-full">
      <SilkWaves
        speed={1}
        scale={2}
        colors={["#0d1326", "#162a52", "#1e407e", "#2657aa", "#2e6ed5", "#3785ff", "#5092ff", "#69a0ff"]}
      />
    </div>
  );
}

Using an installed block

import { Hero1 } from "@/components/blocks/hero-1";   // named export → braces

export default function LandingPage() {
  return (
    <main>
      <Hero1 />
    </main>
  );
}

Blocks render full-width sections and take no props — customize them by editing the source file.

Composing a landing page from blocks

npx shadcn@latest add \
  @reactbits-pro/navigation-1 \
  @reactbits-pro/hero-1 \
  @reactbits-pro/features-1 \
  @reactbits-pro/social-proof-1 \
  @reactbits-pro/pricing-1 \
  @reactbits-pro/faq-1 \
  @reactbits-pro/cta-1 \
  @reactbits-pro/footer-1

// Imports below mix default and named — verified per the reference table above.
import Navigation1 from "@/components/blocks/navigation-1";      // default export
import { Hero1 } from "@/components/blocks/hero-1";              // named export
import { Features1 } from "@/components/blocks/features-1";      // named export
import SocialProof1 from "@/components/blocks/social-proof-1";   // default export
import Pricing1 from "@/components/blocks/pricing-1";            // default export
import Faq1 from "@/components/blocks/faq-1";                    // default export (file identifier: FAQ1)
import CTA1 from "@/components/blocks/cta-1";                    // default export (file identifier: CTA1)
import Footer1 from "@/components/blocks/footer-1";              // default export

export default function LandingPage() {
  return (
    <>
      <Navigation1 />
      <Hero1 />
      <Features1 />
      <SocialProof1 />
      <Pricing1 />
      <Faq1 />
      <CTA1 />
      <Footer1 />
    </>
  );
}

Then edit each block's source to replace placeholder copy, images (/svg/placeholder.svg), and links; adjust colors/spacing; and wire up forms and buttons.

Combining components with blocks

Standalone components can sit behind or alongside blocks (e.g. an animated background):

import SilkWaves from "@/components/react-bits/silk-waves";
import { Hero1 } from "@/components/blocks/hero-1";

export default function LandingPage() {
  return (
    <div className="relative">
      <div className="absolute inset-0 -z-10">
        <SilkWaves speed={0.5} opacity={0.3} />
      </div>
      <Hero1 />
    </div>
  );
}

Customizing

Everything installs as editable source — customize freely.

Components accept rich props. Example (SilkWaves):

<SilkWaves
  speed={1.5}
  scale={3}
  distortion={0.8}
  curve={1.2}
  contrast={1}
  colors={["#1a0533", "#2d1b69", "#4a2c8a", "#6b3fa0", "#8b52b8", "#ab65d0", "#cb78e8", "#eb8bff"]}
  rotation={45}
  brightness={1.2}
  opacity={0.9}
  complexity={1.5}
  frequency={1.2}
  className="absolute inset-0"
/>

For deeper changes, edit the installed .tsx directly: animation timing, breakpoints, new props, color schemes, data/state wiring, API integration. Blocks are designed to be edited — they take no props, so all customization happens in the file.

Dark mode

Blocks and most components support dark mode via Tailwind's dark: class strategy. Ensure a theme provider toggles a dark class on <html> (e.g. next-themes):

// app/layout.tsx
import { ThemeProvider } from "next-themes";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

A few components read the active theme via next-themes and adapt their defaults automatically.

Dependencies

The shadcn CLI installs each item's npm dependencies automatically. Know them for troubleshooting:

There is no d3 or framer-motion dependency in the distributed items — always use motion/react.

Edge case: a few blocks load a package via a dynamic import() (e.g. about-5 → lenis). The CLI may not auto-install these. If a block throws "module not found" at runtime, install the named package manually (e.g. npm install lenis).

"use client" is required

Every component and block begins with "use client". In the Next.js App Router you can import them directly into Server Components — Next.js handles the client boundary. Never remove "use client".

Templates

Templates are full landing-page projects delivered as .zip downloads — they are not installed through the shadcn CLI. There is no @reactbits-pro/<template> install command.

To obtain a template, the user must:

1. Be logged in at https://pro.reactbits.dev.
2. Download the .zip from the template's page.
3. Unzip it and follow its own README to install and run.

The Ultimate license (as configured here) unlocks all of these templates.

Troubleshooting

The registry API returns clear JSON errors. Map them as follows:

Alternative auth (if env substitution is unavailable): the API also accepts an X-License-Key: <key> header or a ?license_key=<key> query parameter.

Best practices

1. Verify the export line before importing a block — this is the #1 source of breakage.
2. Pick one component variant project-wide — use -tw for Tailwind projects (smaller, better integrated); reserve -css for non-Tailwind projects.
3. Wrap WebGL components in a sized container, and lazy-load heavy ones below the fold:

   import dynamic from "next/dynamic";
   const SilkWaves = dynamic(() => import("@/components/react-bits/silk-waves"), { ssr: false });

4. Treat blocks as starting points — edit copy, images, links, and styles directly in the source.
5. Keep the license key in env vars — never hardcode or commit it.
6. Prefer Tailwind v4 so block utilities render correctly out of the box.
7. Install this skill locally for offline reference: npx shadcn@latest add @reactbits-starter/skill.

Appendix A — Component catalog (@reactbits-starter, 101)

Install any of these as @reactbits-starter/<slug>-tw (Tailwind) or <slug>-css (vanilla CSS). All are export default. Components described as shader/WebGL/3D/particle render to a canvas — give them a sized parent and consider ssr: false.

Text & typography (8)

Cursor effects (7)

Cards & interactive (9)

Backgrounds, shaders & visual effects (57)

Galleries, carousels & layout (10)

Images & reveals (5)

Other / utility (5)

Appendix B — Block catalog (@reactbits-pro, 238)

Install as @reactbits-pro/<slug> (no suffix). Slugs are sequential within each category starting at 1. See Block import reference for the per-slug export style.

Quick reference

• Install component: npx shadcn@latest add @reactbits-starter/<slug>-tw (or -css)
• Install block: npx shadcn@latest add @reactbits-pro/<slug>
• Install this skill: npx shadcn@latest add @reactbits-starter/skill
• Component import: import AnyName from "@/components/react-bits/<slug>" (always default)
• Block import: open the file → export default ⇒ default import · export function X ⇒ import { X }
• Reveal a block's export: grep -E "^export (default )?function " components/blocks/<slug>.tsx
• License: Ultimate — every component, block, and template is available
• Live catalogs: https://pro.reactbits.dev/components · /blocks · /templates