Installation

Start building with ZenBlocks — a high-performance, ownership-based UI library for modern web applications.

Overview

ZenBlocks is a collection of sophisticated, physics-enabled UI components designed to vary from utility-first primitives to complex, interactive blocks.

It is not a traditional dependency-based library. Instead, it leverages the shadcn/ui CLI to distribute code directly into your project.

Why ZenBlocks?

Ownership First: Code is scaffolded into your components/zenblocks directory. You own it, you modify it.
Zero Runtime Lock-in: Remove or refactor any part of the library without breaking external dependencies.
Modern Stack: Built for Tailwind CSS v4 and React Server Components by default.
Motion Centric: Deep integrations with framer-motion and gsap for premium interactions.

1. Prerequisites

Ensure your project is set up with the following:

React 18+ or Next.js 14+ (App Router recommended)
Tailwind CSS v4 (or v3 with appropriate configuration)
TypeScript (Recommended)

2. Initialize shadcn/ui

ZenBlocks is built on top of the shadcn/ui architecture. You must have shadcn/ui initialized in your project first.

If you haven't done this yet, run the following command:

npx shadcn@latest init

pnpm dlx shadcn@latest init

bunx shadcn@latest init

[!NOTE] During initialization, you can choose your preferred style, base color, and CSS variables. ZenBlocks will automatically adapt to your components.json configuration.

3. Initialize ZenBlocks Utils

Some ZenBlocks components rely on a shared set of utilities (like clsx and tailwind-merge wrappers). Run this command once to set up the necessary infrastructure.

npx shadcn@latest add https://zenblocks-three.vercel.app/r/utils.json

pnpm dlx shadcn@latest add https://zenblocks-three.vercel.app/r/utils.json

bunx shadcn@latest add https://zenblocks-three.vercel.app/r/utils.json

4. Configure Themes

Some ZenBlocks components rely on next-themes for dark mode support. The CLI cannot automatically wrap your application layout, so you must add this manually.

Install next-themes
```
npm install next-themes
```

Create Custom Theme Provider

Add this file to components/providers/theme-provider.tsx:

"use client"

import * as React from "react"
import { ThemeProvider as NextThemesProvider } from "next-themes"

export function ThemeProvider({
  children,
  ...props
}: React.ComponentProps<typeof NextThemesProvider>) {
  return <NextThemesProvider {...props}>{children}</NextThemesProvider>
}

Wrap Your Root Layout

Update your app/layout.tsx to include the provider:

import { ThemeProvider } from "@/components/providers/theme-provider"

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

5. Install Components

Components can be installed individually using the CLI. This automatically handles dependencies and file placement.

Example: Installing the Animated Clock

npx shadcn@latest add https://zenblocks-three.vercel.app/r/animated-clock.json

pnpm dlx shadcn@latest add https://zenblocks-three.vercel.app/r/animated-clock.json

bunx shadcn@latest add https://zenblocks-three.vercel.app/r/animated-clock.json

Just like that, animated-clock.tsx is now part of your codebase in components/zenblocks/.

6. Usage

Import standard components directly from your components folder:

import { AnimatedClock } from "@/components/zenblocks/animated-clock";

export default function Layout() {
  return <AnimatedClock />;
}

7. Advanced Configuration

Monorepo Support

If you are working inside a monorepo, use the -c flag to specify your workspace path.

npx shadcn@latest add https://zenblocks-three.vercel.app/r/animated-clock.json -c ./apps/web

Install the robust default.
Adapt it to your brand.
Ship with confidence.