metal-fx

Performance

• Shared Context: Uses a single shared WebGL context across all mounted instances.
• Single Loop: A single requestAnimationFrame loop drives all instances.
• Visibility Optimization: Uses IntersectionObserver to pause per-instance copies when offscreen. If all instances are offscreen, the GL render loop is skipped.
• Resource Management: The GL context, program, and buffer are released automatically when the last instance unmounts.

Server-Side Rendering (SSR)

MetalFx is SSR-safe. It renders a transparent placeholder during SSR and only mounts the WebGL pipeline after client-side hydration, preventing flashes of broken effects or SSR errors.

To use the animated WebGL liquid metal effect in your React project, install the package using npm:

npm install metal-fx

The MetalFx component wraps a single child host element (like a button, chip, or icon). It measures the child and paints an animated metal ring on top. The child remains fully interactive because the overlay uses pointer-events: none.

import { MetalFx } from 'metal-fx';

function App() {
  return (
    <MetalFx variant="button">
      <button className="upgrade-pill">Upgrade to Pro</button>
    </MetalFx>
  );
}

MetalFx is an inline-flex wrapper that sizes itself to its child. You have two patterns for controlling dimensions:

Pattern 1: Size the child (Recommended) Style the child element directly using CSS or inline styles. The wrapper will expand to fit it.

Pattern 2: Size the wrapper If you want the metal frame to be larger than the child (e.g., to add padding), apply styles to the MetalFx component and set the child to fill the container (width: 100%, height: 100%).

// Pattern 1: size the child
<MetalFx variant="circle">
  <button style={{ width: 36, height: 36 }} aria-label="Send">↑</button>
</MetalFx>

// Pattern 2: size the wrapper, child fills
<MetalFx style={{ width: 36, height: 36 }} variant="circle">
  <button style={{ width: '100%', height: '100%' }} aria-label="Send">↑</button>
</MetalFx>

MetalFx uses a shared WebGL renderer to drive multiple visual instances efficiently. The architecture follows these steps:

1. Shared GL Canvas: A single offscreen WebGL canvas renders a plasma shader.
2. Visible Instances: Each MetalFxInstance owns its own visible 2D canvas. This canvas receives a cropped and scaled copy of the shared GL output, applying an inner "hole punch" mask to create a ring effect.
3. Glow Sampling: To optimize performance, glow sampling reads from a shared pixel buffer (gl.readPixels) that is refreshed at most every 200ms, preventing frequent GPU pipeline flushes.
4. Animation Loop: The animation loop is capped at approximately 30fps, as the slow plasma motion and blur effects make higher frame rates imperceptible.

This design allows many high-quality visual elements to coexist without the overhead of multiple heavy WebGL contexts.

The reflectionTargets prop allows you to pass an array of RefObject<HTMLElement> representing sibling elements. These elements will receive a soft proximity reflection of the metal effect.

Important constraints:

• Reflections only render when the resolved theme is 'dark'. In 'light' mode, this prop is a no-op (no DOM scanning or per-frame work occurs).
• This is useful for elements like chips next to a button or a search field next to an upgrade pill.

const siblingRef = useRef<HTMLElement>(null);

<MetalFx 
  reflectionTargets={[siblingRef]} 
>
  <button>Action</button>
</MetalFx>

<div ref={siblingRef}>I will receive a reflection in dark mode</div>

To enable proximity reflections, you must be in dark mode (or auto when the system is in dark mode) and provide an array of reflectionTargets. These targets are elements that will reflect the metallic effect as the user interacts with the page.

Note: Reflections are a dark-mode only feature.

import { useRef } from 'react';
import { MetalFx } from './MetalFx';

function App() {
  const targetRef = useRef<HTMLDivElement>(null);

  return (
    <div>
      <div ref={targetRef} style={{ width: 100, height: 100, background: 'black' }} />
      
      <MetalFx 
        theme="dark" 
        reflectionTargets={[targetRef]} 
      >
        <button>Reflective Button</button>
      </MetalFx>
    </div>
  );
}

Use strength to control the intensity and paused to freeze the animation:

• strength: A number from 0 (invisible) to 1 (full intensity, default). It scales the canvas and glow opacity without altering the shader animation.
• paused: A boolean prop. When present, it freezes the shader on its current frame while keeping the metal silhouette visible.

// 70% effect intensity
<MetalFx strength={0.7}>
  <button>Upgrade to Pro</button>
</MetalFx>

// Freeze the shader
<MetalFx paused>
  <button>Upgrade to Pro</button>
</MetalFx>

By default, MetalFx automatically detects and reads the computed border-radius of the wrapped child. If you need to force a specific radius, use the borderRadius prop.

<MetalFx borderRadius={20}>
  <button>Upgrade to Pro</button>
</MetalFx>

Use the preset prop to choose from three bundled color palettes. Each preset includes tuned dark and light mode versions:

• preset="chromatic": Iridescent rainbow (default).
• preset="silver": Cool steel.
• preset="gold": Warm gold.

<MetalFx preset="chromatic" />
<MetalFx preset="silver" />
<MetalFx preset="gold" />

In dark mode, you can pass an array of React refs to the reflectionTargets prop. The elements referenced will receive a soft, mirrored reflection of the MetalFx ring.

Note: Reflections are automatically skipped when the resolved theme is light to save performance.

const sendRef = useRef<HTMLButtonElement>(null);
const chipRef = useRef<HTMLButtonElement>(null);

<>
  <button ref={chipRef}>Tools</button>
  <MetalFx variant="circle" reflectionTargets={[chipRef]}>
    <button ref={sendRef} aria-label="Send">↑</button>
  </MetalFx>
</>