liquid-metal-border

Liquid Metal Border

Core Contract

1. Use metal-fx in React 18 or newer.
2. Wrap exactly one real host element such as a button, a, div, or article.
3. Keep the host semantic and interactive. MetalFx is visual framing, not the control.
4. Reserve the animated border for active, selected, focused, hovered, or primary surfaces. Do not put it around every control.
5. Keep a static CSS border or focus outline as the fallback. WebGL decoration must never carry essential state by itself.
6. Pause non-active instances and reduced-motion experiences.
7. Test light and dark modes independently. Reflections intentionally render only in dark mode.

Inspect Before Editing

• Confirm the project uses React and has react and react-dom version 18 or newer.
• Find the real control, its dimensions, radius, background, border, outline, shadow, active-state source, and theme source.
• Decide whether the metal should be always visible or driven by active, selected, hover, or focus state.
• Check whether the project has a manual theme toggle. Use that state instead of theme="auto" when it does not follow the OS.
• Identify nearby elements that genuinely benefit from reflected light. Do not add reflections by default.
• Check the installed metal-fx version before relying on the prop surface below.

Install and Import

Install with the project's package manager:

npm install metal-fx
# pnpm add metal-fx
# yarn add metal-fx
# bun add metal-fx

Import the named React component:

import { MetalFx } from "metal-fx";

Do not import a stylesheet. The package injects its component styles. It supports ESM and CommonJS builds, is SSR-safe, and mounts the WebGL pipeline after hydration. In a Next.js App Router project, render it from a Client Component because the component uses client-side React hooks.

Baseline Button

Start with a restrained border before adding reflections or custom shader geometry:

import { MetalFx } from "metal-fx";

export function UpgradeButton() {
  return (
    <MetalFx
      variant="button"
      preset="chromatic"
      theme="auto"
      strength={0.85}
    >
      <button type="button">Upgrade to Pro</button>
    </MetalFx>
  );
}