Configuration

Configure Frutjam to match your project's exact needs. The Tailwind plugin exposes options for setting default themes, defining custom color tokens, toggling the prefix system, and controlling which components are included so your output stays lean and intentional.

Basic Setup

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

1
2

@import "tailwindcss";
@plugin "frutjam";

Plugin Options

Customize Frutjam by passing options inside the @plugin block:

1
2
3
4
5
6
7
8
9

@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.

1
2
3

@plugin "frutjam" {
  prefix: fj;
}

1

<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.

1
2
3
4

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

1

<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.

1
2

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

1

<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.

1
2
3
4

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

1

<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.

1
2
3

@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:

Default — global tokens

1
2
3

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

Shadow DOM / Web Components

1
2
3

@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.

1
2
3
4
5

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

1
2
3
4

<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.

1
2
3

@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.

1
2
3

@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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

@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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

@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.

1
2
3

<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.

1
2
3
4
5
6
7
8

<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>