Installation

Getting started with Emerald UI

Emerald UI provides a seamless way to integrate beautifully crafted components directly into your application. Rather than installing a bloated npm package, you embed exactly what you need.

1. Initialize Configuration

The components.json file manages your project's component architecture, allowing the standard CLI to automatically configure paths and dependencies.

Optional Configuration

While the CLI relies on components.json for automatic installation, it's not strictly required. You can always copy and paste the component source code manually!

If you prefer the streamlined CLI experience, initialize your setup by running:

bunx --bun shadcn@latest init
npx shadcn@latest init
pnpm dlx shadcn@latest init

Next, connect the Emerald UI registry by appending this block to your components.json:

{
  "registries": {
    "@emerald-ui": "https://emerald-ui.com/r/{name}.json"
  }
}

2. Add Base Utilities

Our component designs leverage Tailwind CSS v4. Please ensure your environment is configured for it. Additionally, most components depend on our core utility function cn. You can effortlessly add it via:

bunx --bun shadcn@latest add https://emerald-ui.com/r/utils.json 
npx shadcn@latest add https://emerald-ui.com/r/utils.json
pnpm dlx shadcn@latest add https://emerald-ui.com/r/utils.json

3. Start Adding Components 🎉

Emerald UI components often incorporate elegant lucide-icons and occasionally build upon existing shadcn/ui primitives. Relying on the CLI takes the guesswork out of installation by fetching all required dependencies automatically.

For example, to drop the 3D Marquee into your project:

bunx --bun shadcn@latest add @emerald-ui/3d-marquee
npx shadcn@latest add @emerald-ui/3d-marquee
pnpm dlx shadcn@latest add @emerald-ui/3d-marquee

Tip: Although copying and pasting source files works fine, using the CLI guarantees all related internal files, styles, and animation utilities are correctly linked.

You are now ready to render your sleek new component!

import 3DMarquee from "@/components/ui/3d-marquee";

export default function Page() {
    return <3DMarquee />;
}

4. Optional Dependencies

Certain interactive or visually rich components may depend on external libraries (like framer-motion or gsap). These prerequisites are always prominently listed on the component's documentation page. Be sure to install them to prevent runtime errors.