Add and tune animated liquid-metal WebGL borders with the React `metal-fx` package. Use when buttons, icon controls, chips, tabs, cards, or selected surfaces need a metallic active, selected, hover, focus, or premium border; when implementing the MetalFx component from metal.jakubantalik.com; or when troubleshooting its presets, themes, strength, glow, reflections, sizing, radius, animation, accessibility, SSR, or performance.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Add and tune animated liquid-metal WebGL borders with the React `metal-fx` package. Use when buttons, icon controls, chips, tabs, cards, or selected surfaces need a metallic active, selected, hover, focus, or premium border; when implementing the MetalFx component from metal.jakubantalik.com; or when troubleshooting its presets, themes, strength, glow, reflections, sizing, radius, animation, accessibility, SSR, or performance.
Liquid Metal Border
Core Contract
Use metal-fx in React 18 or newer.
Wrap exactly one real host element such as a button, a, div, or article.
Keep the host semantic and interactive. MetalFx is visual framing, not the control.
Reserve the animated border for active, selected, focused, hovered, or primary surfaces. Do not put it around every control.
Keep a static CSS border or focus outline as the fallback. WebGL decoration must never carry essential state by itself.
Pause non-active instances and reduced-motion experiences.
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.
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:
The wrapper measures the child, paints the metal ring on top, and keeps the child interactive. Size the child normally with CSS, Tailwind, or inline styles.
Active-State Pattern
Keep one mounted instance and drive its intensity from real component state. Use aria-pressed, aria-selected, or the native selected-state mechanism so the visual effect is not the only signal.
Use paused to stop non-active canvas updates; it freezes the last frame without hiding the ring. strength changes rendered opacity from 0 to 1 but does not slow the shader.
Static Border and Card Pattern
Use the wrapper as the surface when the child must remain transparent:
Keep the article background transparent so it does not cover the ring. Use the child for content layout and the MetalFx wrapper for the visible surface.
Complete Customization Surface
Prop
Values and default
Use
children
One React host element; required
Preserve the real button, link, chip, card, or icon control.
variant
"button" default, "circle"
Choose a 1 px pill-style baseline at shader scale 1.6, or a 2 px compact-circle baseline at scale 1.3. The measured child still controls the rendered size.
preset
"chromatic" default, "silver", "gold"
Choose iridescent rainbow, cool steel, or warm gold. Each includes dark and light tuning.
theme
"auto" default, "dark", "light"
Follow live prefers-color-scheme changes or pin the effect to the app theme. SSR starts dark, then resolves on the client.
strength
Number 0..1; default 1
Scale canvas and glow opacity. Use lower values for idle states and stronger values for active states.
paused
Boolean; default false
Freeze this instance on its current shader frame while keeping the silhouette visible.
borderRadius
Number in CSS pixels; optional
Override the radius. When omitted, read the child's computed radius on resize.
normalizeHostStyles
Boolean; default true
Remove the child's background, border, outline, and shadow so they do not fight the ring. Set false when preserving a custom focus outline or fallback border.
reflectionTargets
Array of React element refs; optional
Cast a soft mirrored reflection onto selected neighbouring elements. Dark mode only.
disableGlow
Boolean; default false
Remove the wandering halo while retaining the shader ring.
shaderScale
Number; variant baseline by default
Increase to zoom into larger metal pattern features; decrease to zoom out.
ringCssPx
Number; variant baseline by default
Override the visible ring thickness in CSS pixels.
scale
Number; default 1
Scale every absolute-pixel engine constant together for CSS zoom or deliberately enlarged UI systems.
className
String; optional
Style the MetalFx wrapper, not the child.
style
React CSS properties; optional
Size or style the wrapper surface directly.
ref
React ref; optional
Access the forwarded wrapper HTMLDivElement.
Other valid HTMLDivElement attributes are forwarded to the wrapper.
Omit reflectionTargets to disable reflection work. In light mode, reflections are skipped automatically.
Accessibility and Motion
Preserve native button, a, and form semantics inside the wrapper.
Keep active state in aria-pressed, aria-selected, checked state, or current-route state.
Do not rely on hue or animation alone. Retain text, icon, position, weight, or a static edge change.
Be careful with normalizeHostStyles. Its default removes the child's outline; set it to false and define transparent chrome plus :focus-visible when the control needs its own focus ring.
Set paused for reduced motion. Also disable the wandering glow when its movement is unnecessary.
Keep the effect pointer-transparent and verify the child remains clickable and keyboard-operable.
Retain a plain CSS border or surface treatment for WebGL failure.
Performance
metal-fx reuses one shared WebGL context, one compiled shader, and one animation loop across mounted instances. It also pauses offscreen copies with IntersectionObserver and debounces resize work through animation frames.
Still keep the effect selective:
Mount it on primary or stateful surfaces, not whole grids of idle controls.
Pause non-active instances.
Omit reflections unless they add visible depth.
Do not animate the wrapped element's dimensions continuously.
Prefer disableGlow for restrained cards and dense toolbars.
Verification
Run the project's lint, typecheck, production build, tests, and git diff --check. Then verify in the Codex browser:
Confirm the package is present in the manifest and lockfile.
Confirm one .metal-fx-root wraps one semantic host.
Test hover, pointer-down, selected, keyboard focus, and disabled states.
Confirm the active state is exposed semantically and remains clear with the effect hidden.
Confirm the focus ring is visible when normalizeHostStyles is enabled or disabled.
Check the measured size and radius at every responsive breakpoint.
Test the app's real light and dark themes; do not assume auto matches a manual toggle.
Enable reduced motion and confirm the shader stops moving.
Scroll the control offscreen and back; confirm the effect resumes without a blank frame.
Check console output for WebGL, hydration, resize, or ref errors.
Confirm neighbouring controls receive reflections only when explicitly targeted in dark mode.
Failure Diagnosis
The ring is covered: the child has an opaque background above the canvas. Use default normalization or make the child transparent and style the wrapper.
The focus ring disappeared:normalizeHostStyles removed the child outline. Set it to false and reset only background, border, and shadow in project CSS.
The radius is wrong: use a real computed radius on the child or pass borderRadius explicitly.
A circle looks soft or thin: use variant="circle" and explicit square dimensions before increasing ringCssPx.
The pattern is too busy: lower strength, disable glow, or use silver; do not immediately thicken the ring.
Reflections are missing in light mode: expected behavior; reflections are dark-mode only.
The effect is the wrong physical size after zooming: set scale to the UI scale instead of tuning each pixel constant independently.
The page crashes in a server component: move the usage behind the framework's client-component boundary.
The border is blank on unsupported hardware: keep the semantic control and CSS fallback complete; treat the WebGL ring as enhancement.
Handoff
Report the installed metal-fx version, wrapped control, active-state source, preset, theme strategy, fallback border, reduced-motion behavior, build/test results, and Codex-browser verification. Distinguish local readiness from a deployed result.
