Theming

Colors#

goopUI uses the shadcn CSS variables you already have. A component's goo is painted in its variant's background token. GoopButton's default variant drips --primary, the destructive one drips --destructive, and so on. Change those tokens and the goo follows, in light and dark mode.

Under the hood, the engine paints with --goop-color (falling back to currentColor). The components set it for you. If you use @goopui/core directly, set it yourself:

.my-button {
  --goop-color: var(--primary);
  color: var(--primary-foreground);
  background: transparent; /* the goo body paints the fill */
}

Presets#

Start from a preset, then adjust single variables. playful is the default. subtle is calm enough for a dense dashboard: one slow drip, small reactions, no flying goo. wild is for hero sections: bigger and faster, with splashes that escape across the page, gloss, puddles, and long taffy.

.dashboard { --goop-preset: subtle; }
.hero { --goop-preset: wild; }

In JS it's preset: 'wild'. A preset only changes defaults, so anything you set explicitly still wins. This is everything the presets change:

Features#

Every feature can be switched on or off by itself. A JS option takes true, false, or a strength; the CSS variable takes the strength, and 0 turns it off.

Hit effects#

A fast pointer hit is a hard entry, or a fast swipe across or out of the element. --goop-hit-effect decides what it does:

• shockwave (default): the same effect as a click, aimed along the motion and scaled by speed.
• splash: goo punches out of the far side.
• both, or none.

Splash reach#

--goop-splash decides where shockwave and splash particles go: near keeps them within about 70px of the element, escape flies them across the page in one shared overlay, and off has none. Click or swipe hard across the hero on the home page to see escape.

Oil finish#

--goop-finish: oil gives the goo a thin-film iridescent sheen, like oil on a puddle. It's light by default; raise --goop-oil-intensity for more. It uses the canvas renderer, and you can switch it on and off at runtime with update({ finish }). Under reduced motion the sheen holds still.

.crude-oil {
  --goop-color: oklch(0.17 0.01 60);
  --goop-finish: oil;
  --goop-oil-intensity: 0.6;
}

Every variable#

Each knob is a CSS custom property. The engine reads them from the element (so they inherit) when it mounts, and again whenever update() runs. This table comes straight from the engine's own metadata, so names, defaults, ranges, and descriptions always match:

Values are plain numbers: 6 and 6px both read as 6. Anything out of range is clamped, so a typo can't break the simulation.

Try it#

Pick a preset, flip features, and move sliders. Each slider sets a variable on the demo area, and every slider explains what it does. The CSS below the demo is what you'd paste into your stylesheet.

/* The playful preset, as is. Move something. */

Scope#

Variables cascade like any custom property, so you can scope them however you like:

/* Everywhere */
:root {
  --goop-thickness: 1.4;
}

/* Thicker goo, splashing across the page, in one section */
.hero {
  --goop-preset: wild;
  --goop-softness: 6;
  --goop-drip-size: 9;
}

/* One component, calmer */
.settings .goop-button {
  --goop-pointer-reaction: 0.4;
  --goop-shockwave: 0;
}

Every engine option is also a component prop, so for the common cases you don't need CSS at all. See the Button page for the full list. The smaller components (Switch, Slider, Progress, Toaster, ...) take a short list of effect toggles, plus speed, preset, and renderer.

App-wide defaults#

To set a preset or renderer for the whole app, use the goop options of @goopui/nuxt, or app.use(GoopPlugin, { preset: 'subtle' }) in plain Vue. See Installation. A prop on a component beats the app default.

Component colors#

Components with a fill take their color from a shadcn token. Override it with a variable on the component or an ancestor:

Popovers, menus, tooltips, and the Toaster paint the surface's own background, so change the shadcn token (--popover) instead.

Precedence#

For each knob the engine uses the first one it finds:

1. An option passed in JavaScript (attachGoop(el, { softness: 6 })).
2. The --goop-* variable on the element, which may be inherited.
3. The preset (--goop-preset or preset).
4. The built-in default.

Renamed variables#

Some variables got clearer names. The old names still work as deprecated aliases (with a one-time warning in development), but new code should use the new ones: