@goopui/core API

@goopui/core is plain TypeScript and DOM. It has no framework and no dependencies, and it never touches document or window at import time, so it's safe to import during SSR. The Vue, React, and Svelte packages are thin wrappers around it. You only need it directly to put goo on something that isn't a goopUI component, or to build an adapter.

attachGoop#

function attachGoop(host: HTMLElement, options?: GoopOptions): GoopHandle

This turns host into a goo body. It adds an aria-hidden goo layer inside the host at z-index: -1 and sets isolation: isolate on the host (plus position: relative if it was static). Your content paints above the goo, unfiltered. Give the host a transparent background and set --goop-color:

import { attachGoop } from '@goopui/core'

const button = document.querySelector<HTMLButtonElement>('.save')!
button.style.setProperty('--goop-color', 'var(--primary)')

const goop = attachGoop(button, { dripCount: 2, splash: 'escape' })

// later
goop.update() // re-read --goop-* variables
goop.destroy()

Out of the box an attached element:

• drips on hover, more and faster the harder the pointer comes in;
• leans, wobbles, and carries momentum as the pointer moves (inertia), and its hanging drips creep toward the cursor (flow);
• swells a lump or two toward an approaching pointer before it even touches (reach);
• fires a click-like shockwave, aimed along the motion, when the pointer hits it fast: a hard entry or a fast swipe across or out (hitEffect, splashMinSpeed);
• squishes on press, and on release adds goo (clickGoop) and fires a shockwave from the click point (shockwave);
• pulls a stretchy taffy string when you press and drag off it (taffy);
• does the same press from the keyboard: Space or Enter squishes from the top (keyboard);
• sloshes when the page scrolls (scrollSlosh), and its resting drips breathe slowly (idle).

preset: 'subtle' | 'playful' | 'wild' sets the starting point for all of it. See Theming.

Old option and variable names (blur, viscosity, --goop-threshold, ...) still work as deprecated aliases. See renamed variables.

In Vue, attach on mount and destroy on unmount. This site's demos use a wrapper like this one:

<script setup lang="ts">
import { attachGoop, type GoopHandle, type GoopOptions } from '@goopui/core'
import { onMounted, onUnmounted, ref, watch } from 'vue'

const props = defineProps<{ options?: GoopOptions }>()
const el = ref<HTMLElement | null>(null)
let handle: GoopHandle | null = null

onMounted(() => {
  if (el.value) handle = attachGoop(el.value, { ...props.options })
})
watch(() => props.options, (o) => handle?.update({ ...o }), { deep: true })
onUnmounted(() => handle?.destroy())
</script>

<template>
  <button ref="el" class="goop-button"><slot /></button>
</template>

GoopOptions#

GoopOptions takes every tuning knob as an optional number (softness, dripCount, inertia, shockwave, and so on), plus:

Tuning precedence: a JS option, then the --goop-* variable on the host, then the default. Values are clamped to GOOP_LIMITS.

GoopHandle#

Driving a goo body by hand, for an element that can't take pointer events itself (a decorative strip, a layer under other content):

const edge = attachGoop(strip, {
  interactive: false,
  restingDrips: [{ x: 0.25, size: 1.2, length: 1.4 }, { x: 0.7, size: 1.5, length: 2 }],
  splash: 'escape',
})

area.addEventListener('pointerenter', () => edge.hover(true))
area.addEventListener('pointerleave', () => edge.hover(false))
area.addEventListener('pointermove', (e) => edge.feedPointer(e))
area.addEventListener('click', (e) => {
  const r = strip.getBoundingClientRect()
  // Aim the ring along the pointer's last motion.
  edge.shockwave(e.clientX - r.left, r.height / 2, 1.5, { vx: 1200, vy: 300 })
})

The hero on the home page doesn't need any of this: the whole panel is one interactive goo body on the canvas renderer.

Tuning#

These are the per-element knobs. Each one maps to a --goop-* variable:

Renderers#

Two renderers draw the same simulation, so a knob means the same thing in both:

attachGoop(el)                          // 'svg' (default): SVG goo filter on DOM spans
attachGoop(el, { renderer: 'canvas' })  // WebGL2 metaballs, Canvas 2D fallback
attachGoop(el, { renderer: makeCanvasRenderer({ backend: '2d' }) })
attachGoop(el, { finish: 'oil' })       // picks 'canvas' for you

• SVG draws plain <span>s (valid inside a <button>) in a filtered layer and only changes transform and opacity each frame.
• Canvas gives each element its own small <canvas> in the same layer, so scrolling, clipping, and stacking don't change. One shared WebGL2 context per document draws every element in a single batch. Without WebGL2, or after a context loss, it falls back to Canvas 2D with the same filter and switches back when the context returns. It reads --goop-color from computed style and repaints on theme and class changes; call update() after any other color change made while the goo is idle.

Escape splashes fly in one shared, fixed, full-viewport overlay (acquireGoopOverlay). You can use it too, for goo that has to leave its component.

Component engines#

attachGoop is the engine behind Button. Every other component has its own attach* function in core, with the same shape: pass the root element and options, get a handle with update(opts?) and destroy(). The Vue components call these on mount, so you only need them to build your own component or an adapter for another framework.

import { attachSlider } from '@goopui/core'

const slider = attachSlider(rootEl, { jelly: true, preset: 'wild' })
slider.update({ speed: 0.5 })
slider.destroy()

Most of them take the same few options: speed, preset, renderer, and reducedMotion, plus a boolean or 0 to 2 strength for each of the component's effects (listed in its *_EFFECTS export, such as SLIDER_EFFECTS or TOASTER_EFFECTS). Each also exports its per-preset feel table (SLIDER_FEEL, PROGRESS_FEEL, TOAST_FEEL, ...), its pure pose functions (sliderPose, progressPose, toastDropPose, ...), and its option, handle, and pose types.

The ones with a color variable paint with it: --goop-slider-color, --goop-progress-color, --goop-switch-fill, --goop-switch-thumb, --goop-checkbox-fill, --goop-radio-fill.

Slider, progress, and toaster#

attachSlider(root, options?: SliderOptions): SliderHandle
attachProgress(root, options?: ProgressOptions): ProgressHandle
attachToaster(root, options?: ToasterOptions): ToasterHandle

attachSlider and attachProgress add one aria-hidden goo layer to the root and measure the real range, thumbs, or indicator, which you make see-through. attachToaster is different: it keeps one shared layer in document.body behind the whole stack, and moves each toast's background, border, and shadow onto it (TOAST_SELECTOR, TOAST_GOO_ATTR). The toasts stay real DOM.

Shared pieces#

Reduced motion#

Under reduced motion every element switches to a still mode, whatever the preset. The body shape and resting drips stay (without breathing). The drip simulation, wobble, momentum, flow, reach, taffy, label ride, scroll slosh, splashes, shockwaves, and puddles stop, and the oil sheen holds still. Each variable's own behavior is in its reducedMotion note in GOOP_VAR_META. The engine watches the setting live, so turning it on mid-session clears anything in flight.

Animation loop and input#

Every instance shares one requestAnimationFrame loop. It stops when nothing is moving, and a single frame step is capped, so switching tabs doesn't make things jump.

Filter#

The SVG renderer keeps one hidden <svg> per document, holding a <filter> for each distinct parameter set. Each filter is ref-counted and removed when its last user goes away. The pipeline blurs the source, crushes the alpha into a hard edge, and draws the original pixels on top so colors come from the source.

Low-level physics#

These are exported for adapters and tests. Most apps never need them.