---
title: "Configuration"
type: guide
version: "2.0.4"
doc_version: "2.0.4"
status: stable
date: 2026-04-21
library: Frutjam
stack: tailwind_css
compatibility: universal
framework_agnostic: true
runtime_requirement: none
description: "Set up Frutjam your way. Configure default themes, custom color tokens, component inclusion, and prefix options directly in your Tailwind config file."
url: https://frutjam.com/docs/configuration
---

# Configuration

## Basic Setup

Add Frutjam to your CSS file using the `@plugin` directive. No options are required — everything works out of the box.

```css
@import "tailwindcss";
@plugin "frutjam";
```


## Plugin Options

Customize Frutjam by passing options inside the `@plugin` block:

```css
@import "tailwindcss";
@plugin "frutjam" {
  prefix: fj;
  reset: true;
  root: :host;
  include: button, card, alert;
  /* or: */
  exclude: table, timeline;
}
```


### prefix

Adds a prefix to all Frutjam class names to avoid conflicts with your own CSS.

```css
@plugin "frutjam" {
  prefix: fj;
}
```

```html
<button class="fj-btn fj-btn-primary">Send mail</button>
```
How prefix behaves depends on whether you also use Tailwind's `prefix()` option:

#### Frutjam prefix only

Frutjam class names are prefixed. Use them directly in HTML.

```css
@import "tailwindcss";
@plugin "frutjam" {
  prefix: fj;
}
```

```html
<button class="fj-btn">Button</button>
```


#### Tailwind prefix only

Tailwind's `prefix()` works as a variant — all utilities (including Frutjam's) require the prefix as a variant selector in HTML.

```css
@import "tailwindcss" prefix(tw);
@plugin "frutjam";
```

```html
<button class="tw:btn">Button</button>
```


#### Both prefixes

Frutjam renames its classes (e.g. `fj-btn`), and Tailwind's variant prefix is required on top.

```css
@import "tailwindcss" prefix(tw);
@plugin "frutjam" {
  prefix: fj;
}
```

```html
<button class="tw:fj-btn">Button</button>
```


### reset

Controls whether Frutjam injects base element resets (reboot styles). Defaults to `true`.

When `true`, Frutjam resets box model, typography, lists, media, and form elements — similar to Tailwind's preflight. When `false`, only the CSS variable tokens are injected; raw element styles are skipped entirely.

Set to `false` when you are already using another CSS framework (Bootstrap, Bulma, etc.) or your own reset, to avoid conflicts on elements like `*`, `html`, `body`, `h1–h6`, and `button`.

```css
@plugin "frutjam" {
  reset: false;
}
```


### root

The CSS selector where Frutjam registers its design token variables (`--color-primary`, `--color-base`, etc.). Defaults to `:root`.

There are three useful values:

| Value                      | When to use                                                                                                        |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `:root`                    | Default. Tokens are available globally across the whole page.                                                      |
| `:host`                    | Shadow DOM / Web Components. Scopes tokens inside the component so they don't leak out.                            |
| Any selector (e.g. `#app`) | Scopes tokens to a specific wrapper element. Useful when Frutjam coexists with another framework on the same page. |


#### Default — global tokens

```css
@plugin "frutjam" {
  root: :root;
}
```


#### Shadow DOM / Web Components

```css
@plugin "frutjam" {
  root: :host;
}
```


#### Scoped to a wrapper element

If another framework already controls `:root` (e.g. Bootstrap sets its own `--bs-*` variables and body colors), point Frutjam at a container element instead. This moves `color`, `background-color`, and all CSS variables off `:root` so they only apply inside that wrapper.

```css
@plugin "frutjam" {
  prefix: fj;
  reset: false;
  root: #my-app;
}
```

```html
<div id="my-app" data-theme="blueberry">
  <!-- Frutjam components here, Bootstrap outside -->
  <button class="fj-btn fj-btn-primary">Send</button>
</div>
```


### include

Load only specific components instead of the full library. Useful for reducing output size in production.

```css
@plugin "frutjam" {
  include: button, card, alert, badge;
}
```


### exclude

Load all components except the ones listed. Use when you only need to drop a few components from the full build.

```css
@plugin "frutjam" {
  exclude: table, timeline, chat;
}
```


## Create a custom theme

To create your own theme, just assign your color values to the provided CSS variables within a `[data-theme="your-theme-name"]` selector

### 1. The "Automatic" Approach (Minimal)

In this version, we omit the `--color-on-*` variables. Frutjam detects the missing variables and calculates the optimal text color—usually flipping between a very light or very dark `OKLCH` value—to ensure the component remains accessible and readable.

```css
@layer theme {
    :is([data-theme="your-theme-name"]) {
        --scheme-color: light;
        --border-radius: 0.25rem;
        --color-base: oklch(1 0 0);
        --color-neutral: oklch(0.15 0 0);
        --color-primary: oklch(51.1% 0.262 276.966);
        --color-secondary: oklch(0.591 0.293 322.896);
        --color-accent: oklch(0.541 0.281 293.009);
        --color-info: oklch(0.685 0.169 237.323);
        --color-success: oklch(0.792 0.209 151.711);
        --color-warning: oklch(0.852 0.199 91.936);
        --color-error: oklch(0.577 0.245 27.325);
    }
}
```


### 2. The "Manual" Approach (Full Control)

In this version, we explicitly define the `--color-on-*` variables. This is ideal when you have specific brand guidelines (like using a tinted off-white instead of pure white) or when you want to achieve a specific "vibe," such as a low-contrast sophisticated look that still passes accessibility checks.

```css
@layer theme {
    :is([data-theme="your-theme-name"]) {
        --scheme-color: light;
        --border-radius: 0.25rem;
        --color-base: oklch(1 0 0);
        --color-on-base:oklch(0.22 0 0);
        --color-neutral: oklch(0.15 0 0);
        --color-on-neutral: oklch(1 0 0);
        --color-primary: oklch(51.1% 0.262 276.966);
        --color-on-primary: oklch(96.2% 0.018 272.314);
        --color-secondary: oklch(0.591 0.293 322.896);
        --color-on-secondary: oklch(1 0 0);
        --color-accent: oklch(0.541 0.281 293.009);
        --color-on-accent: oklch(1 0 0);
        --color-info: oklch(0.685 0.169 237.323);
        --color-on-info: oklch(0.15 0 0);
        --color-success: oklch(0.792 0.209 151.711);
        --color-on-success: oklch(0.15 0 0);
        --color-warning: oklch(0.852 0.199 91.936);
        --color-on-warning: oklch(0.15 0 0);
        --color-error: oklch(0.577 0.245 27.325);
        --color-on-error: oklch(1 0 0);
    }
}
```
To apply your custom theme to your project in your HTML, use `data-theme="your-theme-name"` to an HTML element.

```html
<html data-theme="your-theme-name">
 ...
</html>
```
Themes can be nested—you can apply a specific theme to any section of your HTML, overriding the global theme for that area.

```html
<html data-theme="light">
  <div data-theme="dark">
    This div uses the dark theme.
    <span data-theme="your-custom-theme">
      This span uses the your-custom-theme
    </span>
  </div>
</html>
```