Liquid Fill

Installation

Requires React 18 or newer. Works with Next.js (App and Pages Router), Vite, Remix and any other React setup. It ships no CSS file and has no dependencies.

npm install react-liquid-fill

Quick start

Give LiquidFill a base that is always visible and a fill to pour over it. Hover and keyboard focus work straight away.

import { LiquidFill } from "react-liquid-fill";

export function Logo() {
  return (
    <LiquidFill
      base={<img src="/logo-outline.svg" alt="" width={48} height={48} />}
      fill={<img src="/logo.svg" alt="" width={48} height={48} />}
      aria-label="Acme"
      role="img"
    />
  );
}

On hover

The default, and what the strip at the top uses. The liquid pours in from whichever side the pointer enters and drains when it leaves. Each logo is two image files: an outline and the full-colour logo. The strip itself is a small marquee from the example project; it slows to a stop under the mouse.

import { LiquidFill } from "react-liquid-fill";

const icons = [{ name: "TypeScript", slug: "typescript" } /* … */];

<Marquee>
  {icons.map(({ name, slug }) => (
    <LiquidFill
      key={slug}
      className="tech"
      role="img"
      aria-label={name}
      tabIndex={0}
      base={<img src={`/icons/outline/${slug}.svg`} alt="" width={48} height={48} />}
      fill={<img src={`/icons/filled/${slug}.svg`} alt="" width={48} height={48} />}
    >
      <span className="tech-name">{name}</span>
    </LiquidFill>
  ))}
</Marquee>

On scroll

Set trigger="inView" and each item fills as it scrolls into view, rising from the bottom. Scroll back up and they drain. Use inView.delay to stagger a grid, or inView.once to keep them full.

TypeScriptJavaScriptPythonReactNext.jsAngularVueRustTailwind CSSNode.jsBunViteDockerPostgreSQLSupabaseRedisFastAPIDjangoLangChainPyTorchVitestPlaywrightGitHub ActionsVercel

Show code

tsxCopy

<LiquidFill
  trigger="inView"
  inView={{ delay: index * 70 }}   // stagger a grid
  base={<img src={outline} alt="" />}
  fill={<img src={filled} alt="" />}
/>

On anything

Nothing is tied to icons. The heading uses the hook with trigger="manual" and calls setProgress() as you scroll. The button is LiquidFill rendered as a button with two copies of its label.

import { useEffect, useRef } from "react";
import { useLiquidFill } from "react-liquid-fill";

export function ScrubbedHeading({ children }: { children: string }) {
  const el = useRef<HTMLHeadingElement>(null);
  const liquid = useLiquidFill({ ref: el, trigger: "manual", direction: "right" });

  useEffect(() => {
    const onScroll = () => {
      const top = el.current!.getBoundingClientRect().top;
      const vh = window.innerHeight;
      liquid.setProgress((vh * 0.85 - top) / (vh * 0.5));
    };
    onScroll();
    addEventListener("scroll", onScroll, { passive: true });
    return () => removeEventListener("scroll", onScroll);
  }, [liquid.setProgress]);

  return (
    <h2 ref={liquid.ref} className="stack">
      <span className="outlined">{children}</span>
      <span style={{ clipPath: "var(--liquid-clip, inset(0 100% 0 0))" }}>{children}</span>
    </h2>
  );
}

<LiquidFill
  as="button"
  type="button"
  touch="tap-toggle"
  base={<span className="btn">Get in touch ↗</span>}
  fill={<span className="btn btn-inverted">Get in touch ↗</span>}
/>

Use it with any icon set

react-liquid-fill doesn't ship icons and doesn't care where yours come from. You need two renderings of the same thing: a quiet base and a coloured fill. How you make them depends on the set. Hover each example.

Image files

Two artworks per icon: an outline and a full-colour version. This is what the strip above uses, with Devicon logos.

tsxCopy

// Two files per icon, e.g. from Devicon or your designer
<LiquidFill
  base={<img src="/icons/outline/python.svg" alt="" width={48} height={48} />}
  fill={<img src="/icons/filled/python.svg" alt="" width={48} height={48} />}
/>

SVG icon components

react-icons, Simple Icons, MUI icons: render the same component twice with a muted and a brand colour.

tsxCopy

// Any SVG icon component that takes a colour
import { SiReact } from "react-icons/si";

<LiquidFill
  base={<SiReact size={48} color="#c9c9c4" />}
  fill={<SiReact size={48} color="#149ECA" />}
/>

Stroke icon sets

Lucide, Heroicons, Phosphor: keep the outline as the base and add a fill colour to the top layer.

tsxCopy

// Stroke icon sets (Lucide, Heroicons, Phosphor…)
import { Heart } from "lucide-react";

<LiquidFill
  direction="up"
  base={<Heart size={48} strokeWidth={1.5} color="#9a9a93" />}
  fill={<Heart size={48} strokeWidth={1.5} color="#e5484d" fill="#e5484d" />}
/>

🔥🔥

Emoji and text

Anything that renders works. Here the base is a greyed-out copy made with a CSS filter.

tsxCopy

// Emoji, text, or anything else that renders
<LiquidFill
  base={<span style={{ fontSize: 44, filter: "grayscale(1)", opacity: 0.4 }}>🔥</span>}
  fill={<span style={{ fontSize: 44 }}>🔥</span>}
/>

Need outline and colour versions of brand logos? The demo strip uses Devicon's full-colour logos, with the outline generated from the same file by re-styling every shape to a white fill and a thin stroke. The script that does this is in the example project.

Using the hook

LiquidFill is a thin wrapper. When you need your own markup, use useLiquidFill directly: attach ref and bind to an element, and clip whatever should be revealed with the --liquid-clip variable the hook animates.

import { useLiquidFill } from "react-liquid-fill";

export function NavLink({ href, children }) {
  const liquid = useLiquidFill(); // hover + keyboard focus

  return (
    <a href={href} ref={liquid.ref} {...liquid.bind} className="stack">
      <span>{children}</span>
      <span className="inverted" style={{ clipPath: "var(--liquid-clip, inset(0 100% 0 0))" }}>
        {children}
      </span>
    </a>
  );
}

Styling and dark mode

There is no stylesheet to import and no theme provider. The library only writes one CSS variable and two data attributes, so you style everything with your own CSS, Tailwind or CSS-in-JS.

/* The hook writes --liquid-clip on the host; clip whatever should be revealed */
.my-fill-layer {
  clip-path: var(--liquid-clip, inset(0 100% 0 0));
}

/* React to the finished state */
.my-icon[data-filled] .caption { color: var(--text-strong); }

/* Dark mode: invert a white outline artwork */
@media (prefers-color-scheme: dark) {
  [data-liquid-layer="base"] img { filter: invert(0.9); }
}

Accessibility

• The fill layer is rendered with aria-hidden, so screen readers announce the content once.
• The default triggers include keyboard focus. Add tabIndex={0} to non-interactive elements you want reachable.
• Users who turn on reduced motion get an instant change instead of the animation. Set reducedMotion="ignore" to opt out.
• Touch screens have no hover, so nothing happens by default. Set touch="tap-toggle" to fill on tap.

<LiquidFill />

import { LiquidFill } from "react-liquid-fill";

useLiquidFill(options)

import { useLiquidFill } from "react-liquid-fill";

Options

Returns

liquidPolygon(input)

The geometry on its own, with no React. Returns a CSS polygon() string, or inset() at 0 and 1. Use it with vanilla JS, canvas clipping, or another framework.

import { liquidPolygon } from "react-liquid-fill";

el.style.clipPath = liquidPolygon({
  progress: 0.5,
  direction: { x: 0, y: -1 },
  width: el.offsetWidth,
  height: el.offsetHeight,
});

Attributes and CSS