@tsogtoodev/shingen-metal

Animated WebGL "liquid metal" effect for Vue 3.

Install

npm install @tsogtoodev/shingen-metal

Quick start

<script setup>
import { ShingenMetal } from '@tsogtoodev/shingen-metal';
</script>

<template>
  <ShingenMetal variant="button">
    <button class="upgrade-pill">Upgrade to Pro</button>
  </ShingenMetal>
</template>

The component wraps a single slotted host element, measures it, and paints an animated metal ring on top. The child stays fully interactive — overlays sit above it with pointer-events: none.

Variants

<ShingenMetal variant="button">  <!-- Pill silhouette, 1 px ring, scale 1.6 -->
  <button>Upgrade to Pro</button>
</ShingenMetal>

<ShingenMetal variant="circle">  <!-- Compact circle, 2 px ring, scale 1.3 -->
  <button>↑</button>
</ShingenMetal>

Presets

Three bundled palettes, each with a tuned dark and light mode block:

<ShingenMetal preset="chromatic" />  <!-- Iridescent rainbow (default) -->
<ShingenMetal preset="silver" />     <!-- Cool steel -->
<ShingenMetal preset="gold" />       <!-- Warm gold -->

Theme

<ShingenMetal theme="auto" />    <!-- Follows prefers-color-scheme (default) -->
<ShingenMetal theme="dark" />    <!-- Pin to dark backgrounds -->
<ShingenMetal theme="light" />   <!-- Pin to light backgrounds -->

auto reads the OS / browser theme on mount and subscribes to live changes via matchMedia('(prefers-color-scheme: dark)'), so the metal frame switches over instantly when the user toggles their system theme. SSR-safe — the initial render falls back to dark and rehydrates to the resolved theme on the client.

If your app has its own theme toggle that doesn't follow the OS, drive theme from your app state instead:

<ShingenMetal :theme="appTheme">...</ShingenMetal>

Strength

<ShingenMetal :strength="0.7">  <!-- 70% effect intensity -->
  <button>Upgrade to Pro</button>
</ShingenMetal>

strength runs from 0 (invisible) to 1 (full, default). It scales the canvas and glow opacity without changing the underlying shader animation.

Paused

<ShingenMetal paused>
  <button>Upgrade to Pro</button>
</ShingenMetal>

Freezes the shader on its current frame. The metal silhouette stays visible.

Proximity reflection (dark mode only)

Pass template refs to neighbouring elements and they receive a soft, mirrored reflection of the metal ring:

<script setup>
import { ref } from 'vue';
import { ShingenMetal } from '@tsogtoodev/shingen-metal';

const chipRef = ref(null);
</script>

<template>
  <button ref="chipRef">Tools</button>
  <ShingenMetal variant="circle" :reflection-targets="[chipRef]">
    <button aria-label="Send">↑</button>
  </ShingenMetal>
</template>

Reflections are skipped automatically when the resolved theme is light — no DOM scanning, no per-frame work in light mode.

Performance

• One shared WebGL context is reused across every mounted <ShingenMetal> on the page. The shader is compiled once.
• A single requestAnimationFrame loop drives every instance. Per-frame work for one mount: a gl.drawArrays plus N×drawImage copies (one per visible instance).
• IntersectionObserver pauses per-instance copies when the host scrolls offscreen. When every instance is offscreen the GL render is skipped too.
• ResizeObserver callbacks are debounced through RAF.
• The GL context, program, and buffer are released when the last <ShingenMetal> unmounts.

Server-side rendering

The component renders a transparent placeholder during SSR and only mounts the WebGL pipeline after hydration on the client. No flash of broken effect, no SSR errors.

Sizing

ShingenMetal does not force any dimensions onto the wrapped child — the wrapper sizes itself to whatever the child renders. Style your child the way you normally would (intrinsic content, CSS class, or inline style):

<!-- Pattern 1 (recommended): size the child. -->
<ShingenMetal variant="circle">
  <button style="width: 36px; height: 36px" aria-label="Send">↑</button>
</ShingenMetal>

<ShingenMetal>
  <button class="rounded-full px-6 h-10">Upgrade to Pro</button>
</ShingenMetal>

If you want a metal frame larger than the child (e.g. padding around an icon), size the wrapper instead and explicitly stretch the child to fill:

<!-- Pattern 2: size the wrapper, child fills. -->
<ShingenMetal style="width: 36px; height: 36px" variant="circle">
  <button style="width: 100%; height: 100%" aria-label="Send">↑</button>
</ShingenMetal>

Both patterns work; pick whichever fits your layout. The wrapper is display: inline-flex so it lays out inline like a button.

Custom border radius

By default ShingenMetal reads the computed border-radius of the wrapped child each resize. Pass an explicit override when needed:

<ShingenMetal :border-radius="20">
  <button>Upgrade to Pro</button>
</ShingenMetal>

Demo

npm install
npm run dev

License

MIT - See LICENSE.