Installation

Set up your project to use uiblox components. This guide covers everything you need to get started.

Prerequisites

uiblox components are designed for React projects using Tailwind CSS. You'll need:

React 18 or later (React 19 recommended)
Tailwind CSS 3.4 or later
TypeScript (recommended but optional)

New Project Setup

Step 1: Create a Next.js project

npx create-next-app@latest my-app --typescript --tailwind --eslint
cd my-app

Step 2: Install dependencies

uiblox uses these packages for styling utilities:

npm install class-variance-authority clsx tailwind-merge

Package breakdown:

class-variance-authority - Component variant management
clsx - Conditional class name joining
tailwind-merge - Intelligent Tailwind class merging

Step 3: Create the utility function

Create src/lib/utils.ts:

src/lib/utils.ts

ReactTailwind

TYPESCRIPT

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Step 4: Configure path aliases (optional)

Add path aliases to your tsconfig.json:

tsconfig.json

ReactTailwind

JSON

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

Step 5: Set up your component folder

Create the folder structure for your components:

mkdir -p src/components/ui

Create an index file for barrel exports at src/components/ui/index.ts:

src/components/ui/index.ts

ReactTailwind

TYPESCRIPT

// Export all your components from here
export { Button } from "./button";
export { Input } from "./input";
export { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from "./card";
// Add more as you copy components

Adding Design Tokens (Optional)

For a consistent design system, add CSS custom properties. Create src/styles/tokens.css:

src/styles/tokens.css

ReactTailwind

CSS

:root {
  /* Primary colors */
  --color-primary-50: #eff6ff;
  --color-primary-100: #dbeafe;
  --color-primary-200: #bfdbfe;
  --color-primary-300: #93c5fd;
  --color-primary-400: #60a5fa;
  --color-primary-500: #3b82f6;
  --color-primary-600: #2563eb;
  --color-primary-700: #1d4ed8;
  --color-primary-800: #1e40af;
  --color-primary-900: #1e3a8a;
  --color-primary-950: #172554;

  /* Semantic colors */
  --color-background: #ffffff;
  --color-foreground: #0f172a;
  --color-muted: #f1f5f9;
  --color-muted-foreground: #64748b;
  --color-border: #e2e8f0;

  /* Spacing scale */
  --spacing-1: 0.25rem;
  --spacing-2: 0.5rem;
  --spacing-3: 0.75rem;
  --spacing-4: 1rem;
  --spacing-6: 1.5rem;
  --spacing-8: 2rem;

  /* Border radius */
  --radius-sm: 0.25rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
  --radius-xl: 0.75rem;
}

/* Dark mode */
@media(prefers-color-scheme: dark) {
  :root {
    --color-background: #0f172a;
    --color-foreground: #f8fafc;
    --color-muted: #1e293b;
    --color-muted-foreground: #94a3b8;
    --color-border: #334155;
  }
}

Import this in your globals.css:

@import "./tokens.css";
@tailwind base;
@tailwind components;
@tailwind utilities;

Using Components

Once set up, using components is simple:

Browse the Components section
Click "Show code" to see the component source
Click the copy button to copy the code
Paste into your src/components/ui/ folder
Export from your index file
Import and use in your app!

app/page.tsx

ReactTailwind

TSX

import { Button, Card, CardHeader, CardTitle, CardContent } from "@/components/ui";

export default function MyPage() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Welcome</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Get Started</Button>
      </CardContent>
    </Card>
  );
}

Next Steps

Theming →

Learn how to customize colors and create your own theme

Components →

Browse all available components

Best Practices →

Learn design patterns for building great UIs