Skip to content
Browse documentation

Tabs whose highlight has a little surface tension: it draws out and pinches for a moment, then it is a pill again.

Used forApp sectionsSite navigationFeed filtersChart ranges

Install with the shadcn CLI

$ npx shadcn@latest add https://hairlineui.com/r/liquid-tabs.json

Registered the namespace? Then it’s shadcn add @hairline/liquid-tabs. Set it up

Templates

Need the whole page?

61 Next.js landing pages, each designed from scratch. Try any of them live; one is $39, all of them $159, and 6 are free.

All 61 templates

Where it’s used

  • App sections

    Overview, activity, members and settings at the top of a page.

  • Site navigation

    Give each tab an href and it becomes a nav bar with aria-current.

  • Feed filters

    A colour per category, so the filter says which one you are in.

  • Chart ranges

    7, 30 and 90 days filling the width of a card.

What it handles for you

A highlight on a transition restarts from a standstill whenever it is interrupted, and its label jumps colour all at once. This one is drawn from springs that keep their speed, and it stays quiet enough for a control people click all day.

Instead of wiring upsliding tab indicatorgooey filter effectsframer-motion layoutId tabs
  1. Interruptions

    Click three tabs quickly and the highlight curves from one to the next. It keeps its speed, because the edges are springs and the outline is a pure function of them.

  2. Quiet on purpose

    About 0.3s with no overshoot, and a limit on how far it draws out, so a long jump is no louder than a short one.

  3. Letters that turn in place

    The same outline clips a second copy of the labels, so a word can be half one colour while the highlight crosses it.

  4. Tab and link semantics

    A tablist with arrow keys, Home, End and one tab stop; give tabs an href and they become links with aria-current.

  5. Narrow rows

    The row scrolls sideways inside its pill and brings the chosen tab into view, with the highlight in the same scroll.

  6. First paint

    Before anything is measured the chosen tab paints its own highlight, so a server render never shows a row with nothing selected.

  7. No cost at rest

    The springs share one frame loop that sleeps when they settle. Moving means writing one path, with no React render and no layout.

Overview

A tab highlight usually slides like a box on a rail. Here the edge in front leads and the edge behind follows a moment later, so the highlight draws out slightly and its middle pinches before it settles. It takes about 0.3s with no overshoot, so you can notice it the first time and use it all day without it getting in the way. Each label turns exactly where the highlight touches it, and with a colour per tab the new colour comes in from the front while the old one leaves with the tail.

States

pick
The front edge leads and the back follows. Both are critically damped, so it settles in about 0.3s without overshooting.
long jump
The highlight can draw out at most 0.45 of its height past its width, and the tail is carried behind the front, so distance adds speed but not shape.
pinch
The waist narrows by up to 20% while drawn out and fills back in as it closes.
reduced motion
The selection and the label colours change in place.

Usage

usage.tsx
import { LiquidTabs } from "@/components/liquid-tabs";<LiquidTabs label="Sections" defaultValue="overview" tabs={[  { value: "overview", label: "Overview" },  { value: "activity", label: "Activity" },  { value: "settings", label: "Settings" },]} />

Works with

As site navigation

Give each tab an href and the row becomes links. Pass the current path as value so it follows the route.

example.tsx
"use client";import { usePathname } from "next/navigation";import { LiquidTabs } from "@/components/liquid-tabs";export function SiteNav() {  const pathname = usePathname();  return (    <LiquidTabs      label="Main"      value={pathname}      tabs={[        { value: "/", label: "Home", href: "/" },        { value: "/pricing", label: "Pricing", href: "/pricing" },        { value: "/docs", label: "Docs", href: "/docs" },      ]}    />  );}

Props

tabs
LiquidTab[]
value, label, icon, ariaLabel, href, disabled, color, foreground, panelId.
value / defaultValue
string
The chosen tab.
onValueChange
(value: string) => void
Called when a tab is chosen.
label
string
Accessible name of the row.
size= "md"
"sm" | "md" | "lg"
32px, 40px or 48px tall.
block= false
boolean
Fill the parent with equal tabs.

Accessibility and motion

  • Reduced motion: the selection changes in place.
  • Colours come from your theme, or from each tab's color and foreground. The trough has a little real shading, so it still sits inside any screen.
  • Keep the labels the same weight: both copies of them have to lie exactly on top of each other.
  • Panels are yours: pass panelId and give the panel role="tabpanel".

Requirements

React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

Source

"use client";import * as React from "react";import { INTERACTION_FOCUS, MATERIAL_RECESS, createSpring, rubberBand, useInteractionReducedMotion, type Spring } from "./ui-interaction-motion";/* ───────────────────────────────────────────────────────── * LIQUID TABS: a selection with a little surface tension * *   pick     the edge in front leads and the edge behind follows a *            moment later, so the highlight draws out slightly and *            its middle pinches, then it's a pill again. About 0.3s, *            with no overshoot: you can notice *            it, and you can use it all day without noticing it *   far      the same on a long jump: how far it can draw out has a *            limit, so the distance never makes it louder *   labels   each label turns exactly where the highlight touches *            it, because the same outline clips the light copy *   colour   with a colour per tab, the new one comes in from the *            front and the old one leaves with the tail * * The outline is one pure function of three springs, written to one * path per frame. No filter, no layout, no render while it moves. * ───────────────────────────────────────────────────────── */export interface LiquidTab {  value: string;  label: React.ReactNode;  icon?: React.ReactNode;  /** Required when `label` isn't text. */  ariaLabel?: string;  /** Renders a link and reports aria-current instead of a tab. */  href?: string;  disabled?: boolean;  /** The drop's colour on this tab, any CSS colour. Defaults to var(--primary). */  color?: string;  /** The label's colour on the drop. Defaults to var(--primary-foreground). */  foreground?: string;  /** The id of the panel this tab shows. */  panelId?: string;}export interface LiquidTabsProps {  tabs: LiquidTab[];  value?: string;  defaultValue?: string;  onValueChange?: (value: string) => void;  /** Accessible name of the row. */  label: string;  /** 32px, 40px or 48px tall. */  size?: "sm" | "md" | "lg";  /** Fill the parent with equal tabs. */  block?: boolean;  className?: string;}const SIZES = {  sm: { row: "h-8 p-[3px]", tab: "px-3 text-[12.5px] gap-1.5 [&_svg]:size-3.5" },  md: { row: "h-10 p-1", tab: "px-4 text-[13.5px] gap-2 [&_svg]:size-4" },  lg: { row: "h-12 p-[5px]", tab: "px-5 text-[15px] gap-2 [&_svg]:size-[18px]" },} as const;// Both critically damped, so nothing overshoots. The front is a touch quicker, and the difference is the whole effect.const FRONT = { stiffness: 620, damping: 49.8 };const BEHIND = { stiffness: 380, damping: 39 };const WIDTH = { stiffness: 450, damping: 42.4 };/** How far the highlight can draw out past its width, in heights, however far it's going. */const REACH = 0.45;/** The most the waist pinches, as a share of the height. */const PINCH = 0.2;const clamp = (n: number, low: number, high: number) => Math.min(high, Math.max(low, n));const n1 = (n: number) => Math.round(n * 100) / 100;/** One half's outline, end cap to waist: `tip` is the middle of the waist. */function half(capX: number, tipX: number, top: number, bottom: number, thin: number, side: 1 | -1) {  const cy = (top + bottom) / 2;  const r = Math.min((bottom - top) / 2, Math.abs(tipX - capX));  const start = capX + side * r;  const pull = (tipX - start) * 0.56;  const edge = (y: number, tipY: number) => `${n1(start + pull)} ${n1(y)} ${n1(tipX - pull)} ${n1(tipY)} ${n1(tipX)} ${n1(tipY)}`;  const sweep = side === 1 ? 1 : 0;  return {    start: { x: n1(start), top: n1(cy - r), bottom: n1(cy + r) },    r: n1(r),    sweep,    toTip: { top: edge(cy - r, cy - thin), bottom: edge(cy + r, cy + thin) },    tipTop: n1(cy - thin),    tipBottom: n1(cy + thin),    backTop: `${n1(tipX - pull)} ${n1(cy - thin)} ${n1(start + pull)} ${n1(cy - r)} ${n1(start)} ${n1(cy - r)}`,    backBottom: `${n1(tipX - pull)} ${n1(cy + thin)} ${n1(start + pull)} ${n1(cy + r)} ${n1(start)} ${n1(cy + r)}`,  };}/** * The outline from its left and right edges, its resting width, and its top and bottom. A pure function: any interruption * is just another pair of edges, so it never has to restart anything. */export function liquidPath(left: number, right: number, rest: number, top: number, bottom: number) {  const height = bottom - top;  const width = right - left;  const mid = (left + right) / 2;  const drawn = clamp((width - rest) / (height * REACH), 0, 1);  const thin = (height / 2) * (1 - PINCH * drawn * (2 - drawn));  const a = half(left, mid, top, bottom, thin, 1);  const c = half(right, mid, top, bottom, thin, -1);  return (    `M${a.start.x} ${a.start.top}C${a.toTip.top}C${c.backTop}` +    `A${c.r} ${c.r} 0 0 1 ${c.start.x} ${c.start.bottom}` +    `C${c.toTip.bottom}C${a.backBottom}` +    `A${a.r} ${a.r} 0 0 1 ${a.start.x} ${a.start.top}Z`  );}const colorOf = (tab?: LiquidTab) => tab?.color ?? "var(--primary)";type Mark = { x: number; w: number };export function LiquidTabs({ tabs, value, defaultValue, onValueChange, label, size = "md", block, className = "" }: LiquidTabsProps) {  const reduced = useInteractionReducedMotion();  const [own, setOwn] = React.useState(defaultValue ?? tabs[0]?.value);  const current = value !== undefined ? value : own;  const [measured, setMeasured] = React.useState(false);  const [hovered, setHovered] = React.useState<string | null>(null);  const rowRef = React.useRef<HTMLDivElement>(null);  const pathRef = React.useRef<SVGPathElement>(null);  const sheenRef = React.useRef<SVGPathElement>(null);  const lightRef = React.useRef<HTMLDivElement>(null);  const flowRef = React.useRef<SVGLinearGradientElement>(null);  const fromStopRef = React.useRef<SVGStopElement>(null);  const toStopRef = React.useRef<SVGStopElement>(null);  const flowId = React.useId();  const sheenId = React.useId();  const springs = React.useRef<{ left: Spring; right: Spring; rest: Spring } | null>(null);  const motion = React.useRef({ top: 0, bottom: 0, heading: 1, target: 0, flowing: false, frontFrom: 0, tailFrom: 0, tailTo: 0 });  const marks = React.useRef(new Map<string, Mark>());  const paint = React.useCallback(() => {    const s = springs.current;    if (!s) return;    const m = motion.current;    const rest = s.rest.get();    const height = m.bottom - m.top;    const most = rest + height * REACH;    let left = s.left.get();    let right = s.right.get();    // On a long jump the tail is carried along behind the front, so the distance never makes the shape any bigger.    const over = right - left - most;    if (over > 0) {      const kept = rubberBand(over, height * 0.3);      if (m.heading > 0) left = right - most - kept;      else right = left + most + kept;    }    const d = liquidPath(left, right, rest, m.top, m.bottom);    pathRef.current?.setAttribute("d", d);    sheenRef.current?.setAttribute("d", d);    if (lightRef.current) lightRef.current.style.clipPath = `path("${d}")`;    // The new colour starts at the front of the drop and the old one leaves with its tail: where the two meet follows how    // far both edges have got. Before the first frame of a flight the drop is all old colour, and after the last all new.    const flow = flowRef.current;    if (m.flowing && flow) {      const front = m.heading > 0 ? right : left;      const tail = m.heading > 0 ? left : right;      const done = (now: number, from: number, to: number) => clamp((now - from) / (Math.abs(to - from) < 1 ? 1 : to - from), 0, 1);      const through = (done(front, m.frontFrom, m.target) + done(tail, m.tailFrom, m.tailTo)) / 2;      const soft = Math.min(20, Math.abs(front - tail) * 0.25);      const a = front + m.heading * soft;      const seam = a + (tail - m.heading * soft - a) * through;      flow.setAttribute("x1", `${n1(seam - m.heading * soft)}`);      flow.setAttribute("x2", `${n1(seam + m.heading * soft)}`);      if (through > 0.995) m.flowing = false;    } else if (flow) {      flow.setAttribute("x1", "0");      flow.setAttribute("x2", "0");    }  }, []);  const measure = React.useCallback(() => {    const row = rowRef.current;    if (!row) return false;    marks.current.clear();    row.querySelectorAll<HTMLElement>("[data-liquid-tab]").forEach((el) => {      // Offsets count from the controls' own layer, which sits inside the row's padding.      const layer = el.offsetParent as HTMLElement;      marks.current.set(el.dataset.liquidTab!, { x: layer.offsetLeft + el.offsetLeft, w: el.offsetWidth });      motion.current.top = layer.offsetTop + el.offsetTop;      motion.current.bottom = motion.current.top + el.offsetHeight;    });    return true;  }, []);  const aim = React.useCallback(    (next: string | undefined, instant: boolean) => {      const s = springs.current;      const mark = next ? marks.current.get(next) : undefined;      if (!s || !mark) return;      const m = motion.current;      const end = mark.x + mark.w;      if (instant) {        m.flowing = false;        s.left.jump(mark.x);        s.right.jump(end);        s.rest.jump(mark.w);        return;      }      const heading = mark.x + mark.w / 2 >= (s.left.get() + s.right.get()) / 2 ? 1 : -1;      m.heading = heading;      m.target = heading > 0 ? end : mark.x;      m.frontFrom = heading > 0 ? s.right.get() : s.left.get();      m.tailFrom = heading > 0 ? s.left.get() : s.right.get();      m.tailTo = heading > 0 ? mark.x : end;      m.flowing = true;      (heading > 0 ? s.right : s.left).configure(FRONT);      (heading > 0 ? s.left : s.right).configure(BEHIND);      s.left.set(mark.x);      s.right.set(end);      s.rest.set(mark.w);      // Now, not next frame: the stops have already changed, and the drop must still be all old colour when it next paints.      paint();    },    [paint],  );  // The first placement, and again whenever the row changes size: fonts arriving, a label changing, a narrower parent.  React.useLayoutEffect(() => {    const row = rowRef.current;    if (!row || !measure()) return;    const start = current ? marks.current.get(current) : undefined;    const s = {      left: createSpring(start?.x ?? 0, FRONT, paint),      right: createSpring(start ? start.x + start.w : 0, BEHIND, paint),      rest: createSpring(start?.w ?? 0, WIDTH, paint),    };    springs.current = s;    paint();    setMeasured(true);    let first = true;    const observer = new ResizeObserver(() => {      if (first) return void (first = false);      measure();      aim(row.dataset.current, true);    });    observer.observe(row);    document.fonts?.ready.then(() => {      if (springs.current !== s) return;      measure();      aim(row.dataset.current, true);    });    return () => {      observer.disconnect();      s.left.stop();      s.right.stop();      s.rest.stop();      springs.current = null;    };    // Mount only: `current` is read from the row's data attribute from then on, and changes go through the effect below.    // eslint-disable-next-line react-hooks/exhaustive-deps  }, [measure, aim, paint, tabs.length]);  // A new choice: the colour first, so its stops are right from the first frame of the flight.  const shownRef = React.useRef(current);  React.useLayoutEffect(() => {    if (shownRef.current === current) return;    const before = tabs.find((t) => t.value === shownRef.current);    const after = tabs.find((t) => t.value === current);    shownRef.current = current;    fromStopRef.current?.setAttribute("stop-color", colorOf(before));    toStopRef.current?.setAttribute("stop-color", colorOf(after));    aim(current, reduced);    const row = rowRef.current;    const el = row?.querySelector<HTMLElement>(`[data-liquid-tab="${CSS.escape(current ?? "")}"]`);    const scroller = row?.parentElement;    if (el && scroller && scroller.scrollWidth > scroller.clientWidth) {      scroller.scrollTo({ left: el.offsetLeft - (scroller.clientWidth - el.offsetWidth) / 2, behavior: reduced ? "auto" : "smooth" });    }  }, [current, tabs, aim, reduced]);  const pick = (next: string) => {    if (value === undefined) setOwn(next);    onValueChange?.(next);  };  const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {    const enabled = tabs.filter((t) => !t.disabled);    const index = enabled.findIndex((t) => t.value === current);    let next = -1;    if (event.key === "ArrowRight" || event.key === "ArrowDown") next = (index + 1) % enabled.length;    else if (event.key === "ArrowLeft" || event.key === "ArrowUp") next = (index - 1 + enabled.length) % enabled.length;    else if (event.key === "Home") next = 0;    else if (event.key === "End") next = enabled.length - 1;    if (next < 0) return;    event.preventDefault();    const tab = enabled[next];    pick(tab.value);    rowRef.current?.querySelector<HTMLElement>(`[data-liquid-tab="${CSS.escape(tab.value)}"]`)?.focus();  };  const sizes = SIZES[size];  const isNav = tabs.some((t) => t.href);  const row = `flex items-stretch ${block ? "w-full" : "w-max"}`;  const cell = `flex min-w-0 items-center justify-center whitespace-nowrap rounded-full font-medium ${sizes.tab} ${block ? "flex-1 basis-0" : ""}`;  const activeTab = tabs.find((t) => t.value === current);  return (    <div className={`relative isolate rounded-full bg-background outline outline-1 -outline-offset-1 outline-border ${MATERIAL_RECESS} ${block ? "w-full" : "w-fit max-w-full"} ${className}`}>      <div className="overflow-x-auto overflow-y-clip rounded-full [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">        <div          ref={rowRef}          data-current={current}          role={isNav ? undefined : "tablist"}          aria-label={isNav ? undefined : label}          onKeyDown={isNav ? undefined : onKeyDown}          className={`relative grid select-none ${sizes.row} ${block ? "w-full grid-cols-[minmax(0,1fr)]" : "w-max"}`}        >          {/* What's under the highlight: the dark copy of the labels. Before the first measure the chosen tab paints its own drop. */}          <div aria-hidden="true" className={`${row} [grid-area:1/1]`}>            {tabs.map((tab) => {              const on = tab.value === current;              const lit = on && !measured;              return (                <span                  key={tab.value}                  className={`${cell} transition-colors duration-200 motion-reduce:transition-none ${tab.disabled ? "opacity-40" : ""} ${hovered === tab.value && !on ? "text-foreground" : "text-muted-foreground"}`}                  style={lit ? { background: colorOf(tab), color: tab.foreground ?? "var(--primary-foreground)" } : undefined}                >                  {tab.icon}                  {tab.label}                </span>              );            })}          </div>          <svg aria-hidden="true" className="pointer-events-none absolute inset-0 size-full overflow-visible [contain:layout]" style={{ opacity: measured ? 1 : 0 }}>            <defs>              <linearGradient ref={flowRef} id={flowId} gradientUnits="userSpaceOnUse" x1="0" x2="0" y1="0" y2="0">                <stop ref={fromStopRef} offset="0" stopColor={colorOf(activeTab)} />                <stop ref={toStopRef} offset="1" stopColor={colorOf(activeTab)} />              </linearGradient>              <linearGradient id={sheenId} x1="0" x2="0" y1="0" y2="1">                <stop offset="0" stopColor="white" stopOpacity="0.12" />                <stop offset="0.5" stopColor="white" stopOpacity="0" />              </linearGradient>            </defs>            <path ref={pathRef} fill={`url(#${flowId})`} />            <path ref={sheenRef} fill={`url(#${sheenId})`} />          </svg>          {/* The same labels in the drop's text colour, cut to the drop's outline, so a letter turns exactly where the highlight reaches it. */}          <div ref={lightRef} aria-hidden="true" className={`${row} pointer-events-none absolute inset-0 ${sizes.row}`} style={{ visibility: measured ? "visible" : "hidden" }}>            {tabs.map((tab) => (              <span key={tab.value} className={cell} style={{ color: tab.foreground ?? "var(--primary-foreground)" }}>                {tab.icon}                {tab.label}              </span>            ))}          </div>          {/* The real controls, on top, invisible: their own text keeps the sizes and the names, and their focus ring shows over the highlight. */}          <div className={`${row} relative [grid-area:1/1]`}>            {tabs.map((tab) => {              const on = tab.value === current;              const shared = {                "data-liquid-tab": tab.value,                onPointerMove: (event: React.PointerEvent) => {                  if (event.pointerType === "mouse" && !tab.disabled && hovered !== tab.value) setHovered(tab.value);                },                onPointerLeave: () => setHovered(null),                className: `${cell} cursor-pointer text-transparent aria-disabled:cursor-default ${INTERACTION_FOCUS} [&_svg]:opacity-0`,              };              return tab.href ? (                <a key={tab.value} {...shared} href={tab.disabled ? undefined : tab.href} aria-current={on ? "page" : undefined} aria-label={tab.ariaLabel} aria-disabled={tab.disabled || undefined} onClick={() => !tab.disabled && pick(tab.value)}>                  {tab.icon}                  {tab.label}                </a>              ) : (                <button                  key={tab.value}                  {...shared}                  type="button"                  role="tab"                  aria-selected={on}                  aria-label={tab.ariaLabel}                  aria-controls={tab.panelId}                  aria-disabled={tab.disabled || undefined}                  tabIndex={on ? 0 : -1}                  onClick={() => !tab.disabled && pick(tab.value)}                >                  {tab.icon}                  {tab.label}                </button>              );            })}          </div>        </div>      </div>    </div>  );}export default LiquidTabs;

Registry item: /r/liquid-tabs.json