Using Components and UI Kit in Your Project

Froiden UI ships two different libraries under one roof, and they're used in slightly different ways. This guide walks you through both — from a blank project to a working component — and covers the pieces most people trip over along the way.

Components vs. UI Kit — Which Do I Use?

Before you copy anything, understand the split:

You will usually end up using both: UI Kit for the workaday layout, Components for the moments that need to pop.

Prerequisites

You need:

• Node 20+ and your package manager of choice (pnpm, npm, yarn, or bun)
• React 18 or 19 — all components are tested against React 19 but work on 18
• Tailwind CSS 4 — most code uses v4 syntax; v3 works with minor tweaks (more on this below)
• TypeScript (optional but recommended) — every component ships with types

You do not need:

• A package installation from npm — there is no @froiden/ui package. Components live in your repo, not in node_modules.
• A CLI tool or scaffolding script
• A theme provider or <FroidenProvider> wrapper — components are self-contained

Step 1 — Tailwind CSS 4 Setup

If your project already has Tailwind, skip to step 2. Otherwise, for a Next.js or Vite project:

npm install tailwindcss @tailwindcss/postcss

Create postcss.config.mjs:

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Then add Tailwind to your global CSS file (e.g. app/globals.css in Next.js):

@import "tailwindcss";

That's the entire Tailwind 4 setup — no tailwind.config.js, no content array. Tailwind 4 scans your source files automatically.

A note on theme tokens

Many Froiden UI components reference CSS custom properties like --foreground, --background, --muted, and --border. If your project doesn't have these defined, the component will still render, but with browser defaults.

The simplest way to add them is to paste this block into your global CSS once:

@theme {
  --color-background: oklch(1 0 0);
  --color-foreground: oklch(0.145 0 0);
  --color-muted: oklch(0.97 0 0);
  --color-muted-foreground: oklch(0.556 0 0);
  --color-border: oklch(0.922 0 0);
  --color-accent: oklch(0.97 0 0);
  --color-accent-foreground: oklch(0.145 0 0);
}

Adjust the values to match your brand. If you already use shadcn/ui or a similar system, its tokens map 1:1 and you don't need to do anything.

Step 2 — Organizing Your Files

Froiden UI follows the same convention as shadcn/ui: components live in your repo under components/ui/. We recommend splitting components and UI Kit into two folders so they don't compete for filenames:

src/
  components/
    ui/              ← UI Kit primitives
      button.tsx
      input.tsx
      dropdown.tsx
    animated/        ← Components (the animated stuff)
      typewriter-text.tsx
      aurora-background.tsx
      magnetic-button.tsx

This split is optional but it makes imports clearer — from "@/components/ui/button" reads differently from from "@/components/animated/typewriter-text", and you can tell at a glance which kind you're dealing with.

If you're using Next.js with the default @/* path alias, those imports work out of the box. If not, add this to tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Step 3 — Adding an Animated Component

Let's walk through the full flow with Typewriter Text as the example.

3a. Install the peer dependency

Every component page shows you an Install dependencies block at the top. For Typewriter Text it's:

npm install framer-motion

Run that once per project — you don't need to reinstall for every component that uses Framer Motion.

3b. Copy the source

On the component detail page (e.g. /components/typewriter-text), click the React tab and copy everything. Paste it into a new file at:

src/components/animated/typewriter-text.tsx

The file already has "use client" at the top, which matters for Next.js App Router — it tells React this component needs to run in the browser (Framer Motion uses useState and useEffect).

3c. Use it

import TypewriterText from "@/components/animated/typewriter-text";
 
export default function Hero() {
  return (
    <section className="py-24 text-center">
      <h1 className="text-5xl font-bold">
        <TypewriterText
          words={["Build faster.", "Ship sooner.", "Delight users."]}
          typingSpeed={80}
          deletingSpeed={50}
        />
      </h1>
    </section>
  );
}

That's the whole loop — prerequisite, copy, import, done. No providers, no config.

3d. Check the props table

Every component detail page has a Props section that lists every prop, its type, default, and what it does. Lean on it — most components expose 5–10 props for tuning speed, colors, sizes, and behavior.

Step 4 — Adding a UI Kit Primitive

UI Kit items are even simpler because most of them have zero dependencies — they're just Tailwind + React state.

4a. Pick a primitive

Browse /ui-kit and click into something like Tailwind Dropdown. The install block will either be empty (pure Tailwind) or show one small dep.

4b. Copy the source

Copy the React code into your project:

src/components/ui/dropdown.tsx

Most UI Kit files export several named components at once (the dropdown exports Dropdown, DropdownTrigger, DropdownMenu, DropdownItem, etc.) — that's the composable "sub-component" pattern shadcn popularized.

4c. Use the compound API

import {
  Dropdown,
  DropdownTrigger,
  DropdownMenu,
  DropdownItem,
} from "@/components/ui/dropdown";
 
export function UserMenu() {
  return (
    <Dropdown>
      <DropdownTrigger>Account</DropdownTrigger>
      <DropdownMenu>
        <DropdownItem onClick={() => {}}>Profile</DropdownItem>
        <DropdownItem onClick={() => {}}>Settings</DropdownItem>
        <DropdownItem onClick={() => {}}>Sign out</DropdownItem>
      </DropdownMenu>
    </Dropdown>
  );
}

Step 5 — Using the HTML Version

If you're not on React, every item ships a vanilla HTML version too. Click the HTML tab on any component or UI Kit page — you'll get a single block containing markup, inline <style>, and <script> tags (where needed). Drop it into any page:

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.tailwindcss.com"></script>
  </head>
  <body>
    <!-- Paste the HTML version here -->
  </body>
</html>

The HTML version has no React dependencies — useful for landing pages built with vanilla HTML, Astro islands, Eleventy, or any server-rendered framework.

Customizing a Component

Because the source is in your repo, customization is just editing the file.

Style overrides via className

Every component accepts a className prop that merges with its internal classes:

<TypewriterText
  words={["Hi"]}
  className="text-7xl font-black text-indigo-500"
/>

Changing internal markup

Want the typewriter cursor to be a block instead of a pipe? Open typewriter-text.tsx and change cursorChar = "|" to cursorChar = "▊". You own the file.

Swapping animation timing

Framer Motion transition objects are almost always inline in the JSX. Search for transition={{ and tune duration, ease, or type: "spring" stiffness/damping to taste.

Common Issues

"Module not found: framer-motion" You skipped the install step. Run npm install framer-motion and restart the dev server.

"useState is not a function" or React Server Component errors The "use client" directive got lost when copying. Make sure the very first line of the file is "use client"; (including the quotes).

Component renders but has no styles Tailwind isn't picking up the new file. In Tailwind 4 this should "just work," but if you're on v3, add the new path to your content array in tailwind.config.js. For Next.js, restart the dev server after creating new files.

Colors look wrong (everything black or washed out) Your project is missing the CSS theme tokens. See the "A note on theme tokens" block in step 1.

TypeScript errors about missing types Make sure @types/react is installed and your tsconfig.json has "jsx": "preserve" (Next.js) or "jsx": "react-jsx" (Vite).

Updating a Component Later

Because you copied the source, you're free to modify it — but that also means updates don't arrive automatically. When a component gets improved, the best workflow is:

1. Open the component page and diff the new code against yours
2. Copy the pieces you want (e.g. new props, bug fixes)
3. Keep any customizations you've made on top

This is the same tradeoff shadcn/ui makes: you own the code, at the cost of manual updates. In practice, components are small enough that merging changes takes a minute or two.

Next Steps

• Browse the Components catalog for animated pieces
• Explore the UI Kit for everyday primitives
• Read Scroll-Driven Animations with Framer Motion to get more out of the motion library
• Check the Changelog for new additions

Questions or stuck? The component detail page for each item has a working preview you can inspect — if your copy doesn't look the same, the detail page is the reference.