metal-fx
Animated WebGL liquid-metal effect for React buttons and UI components
What is it?
What it is
A React component that applies an animated WebGL liquid metal effect to UI elements like buttons or icons, featuring real-time animation, customizable variants, themes, and proximity reflections.
Why it exists
To enhance UI visual appeal with dynamic, interactive metal effects that adapt to user interactions and system themes while maintaining performance efficiency.
Who should use it
React developersUI/UX designersweb developers needing animated effectsprojects requiring WebGL visuals
Who should avoid it
non-React projectsdevelopers avoiding WebGL dependenciesapplications requiring minimal visual effects
How it works
A quick walkthrough in plain English
How metal-fx works
Step 1 of 3
You interact with it
Open metal-fx, send a request, or connect it to your stack.
Features
Advantages
- Seamless integration into existing React UI
- Interactive child remains fully clickable (pointer-events: none on overlay)
- Performance‑friendly: shared context, single animation loop, observer‑based throttling
- Automatic theme adaptation without extra code
- Lightweight API: simple props for variant, preset, strength, etc.
- SSR support prevents flash of broken effect
- Proximity reflection adds visual polish in dark mode
- Open‑source and MIT licensed
Disadvantages
- Requires WebGL support in the browser
- Performance impact on low‑end devices or many instances
- Only available as a React component (no vanilla JS wrapper)
- Reflection feature limited to dark mode only
- SSR placeholder may affect layout until hydration
- No built‑in accessibility features beyond native child element
Installation
FAQ
How do I install and get started with MetalFx?
Install via npm: `npm install metal-fx`. Then import the component and wrap any interactive element: ```tsx import { MetalFx } from 'metal-fx'; function App() { return ( <MetalFx variant="button"> <button className="upgrade-pill">Upgrade to Pro</button> </MetalFx> ); } ``` The wrapped child stays fully interactive while the metal ring is rendered on top.
What variants are available and what visual differences do they provide?
MetalFx offers two built‑in variants: - `variant="button"`: a pill silhouette with a 1 px ring and a 1.6× scale. - `variant="circle"`: a compact circle with a 2 px ring and a 1.3× scale. Choose the variant that best matches the shape of your element.
How can I control the color theme of the metal effect?
Use the `theme` prop: - `theme="auto"` (default) follows the OS `prefers-color-scheme` and updates live. - `theme="dark"` or `theme="light"` pins the effect to a specific mode. If your app has its own theme toggle, pass that value directly: `theme={appTheme}`.
How do I adjust the intensity of the metal effect?
Set the `strength` prop between 0 and 1. `0` hides the effect, `1` is full intensity (default). It scales the canvas and glow opacity without altering the shader animation.
Can I pause the metal animation?
Yes, add the `paused` prop: `<MetalFx paused>...</MetalFx>`. This freezes the shader on its current frame while keeping the metal silhouette visible.
How do I enable proximity reflection between elements?
Pass refs of neighboring elements to `reflectionTargets`: ```tsx 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> </> ``` Reflections are only active in dark mode and are skipped automatically in light mode.
Featured in Videos
YouTube tutorials and walkthroughs for metal-fx
Alternatives
Similar projects ranked by category, topics, and text overlap.
