@danixts/liquid-gooey

Zero-dependency liquid UI effects for native browser APIs, Astro, and Vue.

Playground · npm · Source

npm install @danixts/liquid-gooey

Native API

import { createLiquidGroup } from '@danixts/liquid-gooey'

const group = createLiquidGroup(document.querySelector('[data-liquid]'), {
  blur: 8,
  contrast: 18,
  fill: '#8b5cf6',
})

const item = group.add(document.querySelector('[data-liquid-item]'), {
  effect: 'move',
  move: { springiness: 0.7, wobble: 0.65, stretch: 0.6 },
})

item.update({ x: 120, transition: 'bouncy' })
group.destroy()

Each group owns an isolated SVG surface, observer engine, and item registry. Multiple accounts, widgets, or groups can run on the same page without shared state.

Effects

• Morph: merge nearby items and tune speed, bounce, content blur, and bridge growth
• Shape: evolve bounds and corner radii through a spring
• Move: springiness, wobble, stretch, trail, and advanced motion values
• Dissolve: noise style, warp, pull, gravity, flow, detail, strength, fade, and release
• Group surface: blur, contrast, fill, shadow, and filter padding

Vue 3

<script setup lang="ts">
import { LiquidGroup, LiquidItem } from '@danixts/liquid-gooey/vue'
</script>

<template>
  <LiquidGroup :blur="8" :contrast="18" fill="#8b5cf6">
    <LiquidItem as="button" :x="-52" transition="bouncy">One</LiquidItem>
    <LiquidItem as="button" :x="52" transition="bouncy">Two</LiquidItem>
  </LiquidGroup>
</template>

LiquidGroup and LiquidItem map reactive props to isolated native controllers and clean them up automatically. Vue remains an optional peer dependency.

Astro

---
import { LiquidGroup, LiquidItem } from '@danixts/liquid-gooey/astro'
---

<LiquidGroup class="group" blur={8} contrast={18} fill="#8b5cf6">
  <LiquidItem as="button" x={-52} transition="bouncy" type="button">
    One
  </LiquidItem>
  <LiquidItem as="button" x={52} transition="bouncy" type="button">
    Two
  </LiquidItem>
</LiquidGroup>

The Astro group discovers its declarative items, creates one isolated native controller, and cleans up automatically during view transitions.

Interactive Astro UI

Astro components stay declarative while typed client helpers update their native controllers. No framework island is required.

---
import { LiquidGroup, LiquidItem } from '@danixts/liquid-gooey/astro'
---

<LiquidGroup class="menu" blur={7} contrast={19} fill="#fff">
  <LiquidItem as="button" id="action" transition="bouncy">Add</LiquidItem>
  <LiquidItem as="button" id="trigger">Toggle</LiquidItem>
</LiquidGroup>

<script>
  import { updateLiquidItem } from '@danixts/liquid-gooey/astro/client'

  const action = document.querySelector<HTMLElement>('#action')
  const trigger = document.querySelector<HTMLButtonElement>('#trigger')
  let open = false

  trigger?.addEventListener('click', () => {
    open = !open
    if (action)
      updateLiquidItem(action, {
        x: open ? 72 : 0,
        y: open ? -48 : 0,
        transition: 'bouncy',
      })
  })
</script>

The @danixts/liquid-gooey/astro/client subpath exports:

• updateLiquidItem(element, options)
• updateLiquidGroup(element, options)
• wakeLiquidGroup(element)

These helpers use bubbling typed events, so multiple groups can coexist without shared state or controller lookups in application code.

UI recipes

The playground includes production-shaped Astro and Vue examples for an action menu, email composer, notification switch, styled slider, and quantity stepper. Each example uses real buttons, inputs, labels, outputs, keyboard focus, and native form validation rather than decorative-only elements.

Credits

Independent native port of Liquid Gooey by Jakub Antalik. It is not an official fork or endorsed by the original author. The original MIT copyright and license are preserved in this package.