Metal Button

Installation

pnpm
npmyarnbun
Copy
pnpm dlx shadcn@latest add https://cult-ui.com/r/metal-button.json

Usage

MetalButton wraps the standard shadcn Button with MetalFx from the metal-fx package. All visible instances on a page share one WebGL renderer, so multiple buttons stay efficient.

• className — styles the inner Button (padding, gap, typography).
• metalFxClassName / metalFxStyle — styles the MetalFx wrapper (surface fill when normalizeHostStyles is on).
• MetalIconButton — same API with size="icon-sm" and metalVariant="circle" by default.

Copy
import {
  MetalButton,
  MetalIconButton,
} from "@/components/ui/metal-button"
import { Sparkles } from "lucide-react"

Copy
<MetalButton type="button" variant="outline" preset="chromatic">
  Continue
</MetalButton>
 
<MetalIconButton
  type="button"
  variant="outline"
  aria-label="Sparkles"
  preset="gold"
>
  <Sparkles className="size-3.5" />
</MetalIconButton>

Presets and theme

Pick a bundled palette with preset: "chromatic" (default), "silver", or "gold". Each preset includes dark and light tunings; theme ("auto" | "dark" | "light") selects which side to use. Because metal-fx shares one palette per page, changing preset on any instance updates every visible ring.

Copy
<MetalButton preset="gold" theme="dark" variant="default">
  Upgrade
</MetalButton>

Ring shape and intensity

• metalVariant — "button" (pill ring, default) or "circle" (thicker ring for compact controls).
• strength — 0–1; scales shader opacity and glow while the animation keeps running (default 0.9).
• paused — freezes the ring on the last frame; the button stays fully clickable.

Copy
<MetalButton
  metalVariant="circle"
  strength={0.75}
  paused={isPaused}
  variant="outline"
>
  Settings
</MetalButton>

Styling split: button vs wrapper

With normalizeHostStyles (default true), variant fills and hover colors apply on the MetalFx wrapper so the inner button stays transparent and the liquid ring stays visible. Pass normalizeHostStyles={false} if you want full shadcn chrome on the button itself (filled variants will cover most of the metal).

Copy
<MetalButton
  className="gap-2 pl-6 pr-5"
  metalFxClassName="shadow-sm"
  variant="outline"
>
  Get started
</MetalButton>

Reflections and glow

In dark theme, pass reflectionTargets — an array of refs to sibling elements — for a soft proximity reflection on nearby chips or labels. Use disableGlow to turn off the wandering halo while keeping the shader ring.

Copy
const chipRef = useRef<HTMLButtonElement>(null)
 
<>
  <button ref={chipRef} type="button" className="...">
    Tools
  </button>
  <MetalButton
    reflectionTargets={[chipRef]}
    variant="outline"
  >
    Send
  </MetalButton>
</>

API Reference

Exports

MetalButton accepts all Button props plus MetalFx shell props below. The ref attaches to the MetalFx wrapper (HTMLDivElement).

MetalFx props (forwarded)

See the MetalFx documentation for shader behavior, performance notes, and advanced tuning.

Accessibility

• Prefer MetalIconButton with a visible aria-label (and optional title) for icon-only actions.
• Respect prefers-reduced-motion: pause the effect when users request reduced motion so the ring does not animate unnecessarily.
• The inner control remains a native button (or your polymorphic choice via Button props); keyboard activation works as usual.

Performance

• One shared WebGL canvas drives every MetalFx instance on the page — prefer a single preset per view when possible.
• Reflection scanning runs only in dark mode and only for refs you pass in reflectionTargets.
• Use paused on off-screen or inactive controls to avoid painting frames users cannot see.

Credits

The liquid metal shader and metal-fx React wrapper are by Jakub Antalík. Documentation, live demos, and the underlying effect are at metal.jakubantalik.com.