Theming

Customize FivUI components with CSS variables and Tailwind CSS 4.x theming. Create beautiful, consistent designs that match your brand.

Theming Approach

You can choose between using CSS variables (recommended) or utility classes for theming. FivUI leverages Tailwind CSS 4.x's powerful @theme directive for optimal performance and flexibility.

CSS Variables (Recommended)

CSS variables provide the most flexible theming approach, allowing dynamic color changes and seamless dark mode support.

Usage Example

tsx

<div className="bg-background text-foreground" />
<div className="bg-primary text-primary-foreground" />
<div className="border-border bg-card text-card-foreground" />

Configuration

To use CSS variables for theming, ensure cssVariables is set to true in your fivui.json file:

fivui.json

{
  "$schema": "https://ui.fivexlabs.com/schema.json",
  "style": "default",
  "tsx": true,
  "rsc": true,
  "tailwind": {
    "config": "",
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "version": "4"
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "hooks": "@/hooks",
    "lib": "@/lib"
  }
}

Tailwind 4.x Integration: FivUI uses Tailwind CSS 4.x's @theme directive, which provides better performance and more intuitive CSS variable management compared to traditional approaches.

Utility Classes

For projects that prefer explicit utility classes, you can disable CSS variables and use Tailwind's standard color utilities.

Usage Example

tsx

<div className="bg-zinc-950 dark:bg-white" />
<div className="bg-slate-900 text-slate-50 dark:bg-slate-50 dark:text-slate-900" />
<div className="border-zinc-200 dark:border-zinc-800" />

Configuration

To use utility classes for theming, set cssVariables to false in your fivui.json file:

fivui.json

{
  "$schema": "https://ui.fivexlabs.com/schema.json",
  "style": "default",
  "tsx": true,
  "rsc": true,
  "tailwind": {
    "config": "",
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": false,
    "version": "4"
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "hooks": "@/hooks",
    "lib": "@/lib"
  }
}

Color Convention

FivUI follows a simple background and foreground convention for colors. The background variable is used for the background color of the component and the foreground variable is used for the text color.

Convention Rules

Background Suffix Omission

The background suffix is omitted when the variable is used for the background color of the component.

Foreground Pairing

Every background color has a corresponding foreground color for optimal contrast.

Example

Given the following CSS variables:

css

--color-primary: oklch(0.205 0 0);
--color-primary-foreground: oklch(0.985 0 0);

The background color of the following component will be var(--color-primary) and the foreground color will be var(--color-primary-foreground):

tsx

<div className="bg-primary text-primary-foreground">Hello FivUI</div>

Complete CSS Variables List

Here's the complete list of CSS variables available for customization in FivUI, using Tailwind CSS 4.x's @theme directive:

src/app/globals.css

@import "tailwindcss";

@theme {
  --radius: 0.625rem;
  
  /* Light mode colors */
  --color-background: oklch(1 0 0);
  --color-foreground: oklch(0.145 0 0);
  --color-card: oklch(1 0 0);
  --color-card-foreground: oklch(0.145 0 0);
  --color-popover: oklch(1 0 0);
  --color-popover-foreground: oklch(0.145 0 0);
  --color-primary: oklch(0.205 0 0);
  --color-primary-foreground: oklch(0.985 0 0);
  --color-secondary: oklch(0.97 0 0);
  --color-secondary-foreground: oklch(0.205 0 0);
  --color-muted: oklch(0.97 0 0);
  --color-muted-foreground: oklch(0.556 0 0);
  --color-accent: oklch(0.97 0 0);
  --color-accent-foreground: oklch(0.205 0 0);
  --color-destructive: oklch(0.577 0.245 27.325);
  --color-border: oklch(0.922 0 0);
  --color-input: oklch(0.922 0 0);
  --color-ring: oklch(0.708 0 0);
  --color-chart-1: oklch(0.646 0.222 41.116);
  --color-chart-2: oklch(0.6 0.118 184.704);
  --color-chart-3: oklch(0.398 0.07 227.392);
  --color-chart-4: oklch(0.828 0.189 84.429);
  --color-chart-5: oklch(0.769 0.188 70.08);
  --color-sidebar: oklch(0.985 0 0);
  --color-sidebar-foreground: oklch(0.145 0 0);
  --color-sidebar-primary: oklch(0.205 0 0);
  --color-sidebar-primary-foreground: oklch(0.985 0 0);
  --color-sidebar-accent: oklch(0.97 0 0);
  --color-sidebar-accent-foreground: oklch(0.205 0 0);
  --color-sidebar-border: oklch(0.922 0 0);
  --color-sidebar-ring: oklch(0.708 0 0);
}

.dark {
  --color-background: oklch(0.145 0 0);
  --color-foreground: oklch(0.985 0 0);
  --color-card: oklch(0.205 0 0);
  --color-card-foreground: oklch(0.985 0 0);
  --color-popover: oklch(0.269 0 0);
  --color-popover-foreground: oklch(0.985 0 0);
  --color-primary: oklch(0.922 0 0);
  --color-primary-foreground: oklch(0.205 0 0);
  --color-secondary: oklch(0.269 0 0);
  --color-secondary-foreground: oklch(0.985 0 0);
  --color-muted: oklch(0.269 0 0);
  --color-muted-foreground: oklch(0.708 0 0);
  --color-accent: oklch(0.371 0 0);
  --color-accent-foreground: oklch(0.985 0 0);
  --color-destructive: oklch(0.704 0.191 22.216);
  --color-border: oklch(1 0 0 / 10%);
  --color-input: oklch(1 0 0 / 15%);
  --color-ring: oklch(0.556 0 0);
  --color-chart-1: oklch(0.488 0.243 264.376);
  --color-chart-2: oklch(0.696 0.17 162.48);
  --color-chart-3: oklch(0.769 0.188 70.08);
  --color-chart-4: oklch(0.627 0.265 303.9);
  --color-chart-5: oklch(0.645 0.246 16.439);
  --color-sidebar: oklch(0.205 0 0);
  --color-sidebar-foreground: oklch(0.985 0 0);
  --color-sidebar-primary: oklch(0.488 0.243 264.376);
  --color-sidebar-primary-foreground: oklch(0.985 0 0);
  --color-sidebar-accent: oklch(0.269 0 0);
  --color-sidebar-accent-foreground: oklch(0.985 0 0);
  --color-sidebar-border: oklch(1 0 0 / 10%);
  --color-sidebar-ring: oklch(0.439 0 0);
}

@layer base {
  * {
    @apply border-border;
  }
  body {
    @apply bg-background text-foreground;
  }
}

Adding New Colors

You can easily add new colors to your theme by extending the CSS variables in your globals.css file.

Example: Adding a Brand Color

src/app/globals.css

@theme {
  /* Existing variables... */
  --color-brand: oklch(0.6 0.2 250);
  --color-brand-foreground: oklch(0.98 0.02 250);
  --color-success: oklch(0.7 0.15 145);
  --color-success-foreground: oklch(0.98 0.02 145);
  --color-warning: oklch(0.8 0.15 85);
  --color-warning-foreground: oklch(0.2 0.02 85);
}

.dark {
  /* Existing dark mode variables... */
  --color-brand: oklch(0.7 0.25 250);
  --color-brand-foreground: oklch(0.15 0.02 250);
  --color-success: oklch(0.6 0.18 145);
  --color-success-foreground: oklch(0.95 0.02 145);
  --color-warning: oklch(0.75 0.18 85);
  --color-warning-foreground: oklch(0.15 0.02 85);
}

Then use them in your components:

tsx

<button className="bg-brand text-brand-foreground">
  Brand Button
</button>

<div className="bg-success text-success-foreground">
  Success Message
</div>

<div className="bg-warning text-warning-foreground">
  Warning Alert
</div>

Custom Theme Generator

Want to create your own custom theme? Use our interactive Theme Generator to customize colors, preview changes in real-time, and generate ready-to-use CSS code.

Open Theme Generator

Interactive color picker with live preview

OKLCH Color Picker

Professional color selection with visual sliders

Live Preview

See changes instantly across all components

Export CSS

Generate ready-to-use theme code

Featured Themes

Don't want to create a theme from scratch? Explore our curated collection of beautiful themes inspired by Pakistani cities. Each theme tells a story through carefully crafted color palettes.

Browse Featured Themes

Islamabad

Cool cyan representing the modern capital

Lahore

Vibrant green inspired by the city's gardens

Karachi

Dynamic purple for the port city

Quetta

Deep burgundy from pomegranates

Peshawar

Earthy terracotta from historic architecture

OKLCH Color Format

FivUI uses the OKLCH color format, which provides better perceptual uniformity and more predictable color manipulation compared to traditional RGB or HSL formats.

OKLCH Benefits

Perceptually uniform color space
Better color consistency across devices
More predictable lightness adjustments
Future-proof color specification

OKLCH Format

css

/* OKLCH Format: oklch(lightness chroma hue) */
--color-primary: oklch(0.6 0.2 250);
/*                     │   │   │
/*                     │   │   └── Hue (0-360)
/*                     │   └────── Chroma (0-0.4)
/*                     └────────── Lightness (0-1)
*/

Lightness: 0 (black) to 1 (white)

Chroma: 0 (gray) to ~0.4 (vivid)

Hue: 0-360 degrees (color wheel)