Skip to content

Getting started

Your first component in four steps

Frictionborn components arrive through the shadcn CLI as source code. They live in your project under components/ui, build with your app, and are yours to read and change.

  1. Point shadcn at the registry

    Add the @frictionborn namespace to components.json, so the shadcn CLI knows where to fetch the components:

    components.json
    {
      "registries": {
        "@frictionborn": "https://frictionborn.com/r/{name}.json"
      }
    }
  2. Add a component

    One command copies the component into your project and installs what it needs, @frictionborn/runtime included. The commands pin shadcn@4.21.1, the version our install tests run against.

    Install
    pnpm dlx shadcn@4.21.1 add @frictionborn/ambient-hero
    
  3. Turn on the reveal gate

    Components that reveal on entry (TextReveal, ScrollReveal, AmbientHero and others) hide their content only once the page says motion is ready, so the server HTML is always complete and nothing flashes.

    Next.js (App Router)

    Render <MotionReadyScript /> in the <head> of app/layout.tsx. It is a small Server Component that sets data-motion="ok" when hydration starts.

    app/layout.tsx
    import { MotionReadyScript } from "@frictionborn/runtime";
    
    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <head>
            <MotionReadyScript />
          </head>
          <body>{children}</body>
        </html>
      );
    }

    Vite and single-page apps

    Call initMotionReady() once in your entry file, before React mounts:

    src/main.tsx
    import { createRoot } from "react-dom/client";
    import { initMotionReady } from "@frictionborn/runtime";
    import App from "./App";
    
    initMotionReady();
    
    createRoot(document.getElementById("root")!).render(<App />);
  4. Use your design tokens

    The components read your design tokens: --background, --foreground, --primary, --border and --muted-foreground. In WebGL canvases they are resolved to real colours for you, so the motion matches the rest of your site in light and dark.

What next