NAVIGATION

Expandable Dock.

Icon navigation that shows labels on hover or focus. A measured marker stays under the current destination.

Same component, different example content.
a↗AVERY STUDIO
FICTIONAL PORTFOLIO
Open for a good project
INDEPENDENT BY DESIGN

A different
kind of ordinary.

Digital things with a human touch.
Made carefully. Made to last.

01 / FORM & FEEL
AVERY STUDIO© 2026
REACT + TYPESCRIPT + CSSMIT LICENSE

Installation

In a project with React and shadcn configured, run:

npx shadcn@latest add https://aduneer.github.io/opalframe/r/expandable-dock.json

Copies the component and its stylesheet into components/ui. No additional runtime dependencies. Tailwind classes work through className.

For manual installation, copy both files from Source below. Keep the CSS import alongside the component.

Usage

"use client";

import { useState } from "react";
import { ExpandableDock } from "@/components/ui/expandable-dock";

export default function Example() {
  const [section, setSection] = useState("work");
  return (
    <>
      <ExpandableDock
        items={[
          { id: "work", label: "Work", icon: <span>W</span> },
          { id: "about", label: "About", icon: <span>A</span> },
          { id: "contact", label: "Contact", icon: <span>C</span> },
        ]}
        value={section}
        onValueChange={setSection}
      />
      <p>Selected section: {section}</p>
    </>
  );
}

Customize

Colors and sizes are scoped CSS variables. Override them on your own class.

const [section, setSection] = useState("work");

<ExpandableDock
  items={yourDestinations}
  value={section}
  onValueChange={setSection}
  label="Portfolio sections"
  className="your-dock"
/>

.your-dock {
  max-width: 420px;
  --dock-surface: #f4f6f8;
  --dock-text: #1b2027;
  --dock-muted: #596573;
  --dock-border: #d6dde4;
  --dock-selected: #e1e9f1;
  --dock-accent: #315f9e;
}

Props

PropTypeWhat it does
itemsDockItem[]Unique id, accessible label, your icon, optional href, and optional disabled flag. Use a short collection of destinations; four to six fits most mobile screens.
value / defaultValuestringControlled or initial current destination ID. Defaults to the first enabled item. For route navigation, derive value from the current route.
onValueChange(id: string) => voidCalled when a destination is activated. Hover and focus never change selection. Update value for controlled actions.
labelstringAccessible navigation name; defaults to Main navigation.
reducedMotionbooleanDisable transitions, in addition to the OS preference.
classNamestringRoot customization. Width, colors, and depth can be changed in your stylesheet.

Accessibility & motion

Destinations with href render native links and retain modifier-click behavior; current links use aria-current. Actions render buttons with a pressed state. Every enabled item remains in the Tab order. Arrow keys move focus without activating; Home and End reach the first and last enabled item. Disabled destinations are non-interactive buttons. Icons and visual labels are decorative; each control has its full accessible name even if its label is clipped. Touch activates in one tap. OS reduced motion and the preview toggle disable all dock transitions. No timers or animation loops run in the component. Use unique IDs and concise labels; provide sufficient width for at least 44 pixels per item.

Dependencies

React only. Styles live in a plain CSS file next to the component, and Tailwind utilities work through className.

Source

expandable-dock.tsx
"use client";

import {
  useEffect,
  useRef,
  useState,
  type KeyboardEvent,
  type MouseEvent,
  type PointerEvent,
  type ReactNode,
} from "react";
import "./expandable-dock.css";

export interface DockItem {
  id: string;
  label: string;
  icon: ReactNode;
  /** Omit href for an in-page action. Links retain native browser navigation. */
  href?: string;
  disabled?: boolean;
}

export interface ExpandableDockProps {
  items: DockItem[];
  value?: string;
  defaultValue?: string;
  onValueChange?: (id: string) => void;
  label?: string;
  className?: string;
  reducedMotion?: boolean;
}

/** Navigation with transient label expansion and a persistent current destination. */
export function ExpandableDock({
  items,
  value,
  defaultValue,
  onValueChange,
  label = "Main navigation",
  className = "",
  reducedMotion = false,
}: ExpandableDockProps) {
  const [internal, setInternal] = useState(defaultValue);
  const selected =
    items.find((item) => item.id === (value ?? internal) && !item.disabled) ??
    items.find((item) => !item.disabled);
  const [hovered, setHovered] = useState<string>();
  const [focused, setFocused] = useState<string>();
  const expanded = hovered ?? focused ?? selected?.id;
  const track = useRef<HTMLDivElement>(null);
  const controls = useRef(
    new Map<string, HTMLAnchorElement | HTMLButtonElement>(),
  );
  const [marker, setMarker] = useState<{ left: number; width: number }>();
  const selectedId = selected?.id;

  useEffect(() => {
    const element = track.current;
    const current = selectedId && controls.current.get(selectedId);
    if (!element || !current) return;
    const measure = () => {
      const next = { left: current.offsetLeft, width: current.offsetWidth };
      setMarker((previous) =>
        previous?.left === next.left && previous.width === next.width
          ? previous
          : next,
      );
    };
    const observer = new ResizeObserver(measure);
    observer.observe(element);
    // Expansion can move the current item without resizing it.
    for (const control of controls.current.values()) observer.observe(control);
    const frame = requestAnimationFrame(measure);
    return () => {
      observer.disconnect();
      cancelAnimationFrame(frame);
    };
  }, [selectedId, items]);

  function select(item: DockItem) {
    if (value === undefined) setInternal(item.id);
    onValueChange?.(item.id);
  }

  function navigate(event: KeyboardEvent, id: string) {
    const available = items.filter((item) => !item.disabled);
    const index = available.findIndex((item) => item.id === id);
    let next: number;
    if (event.key === "ArrowRight" || event.key === "ArrowDown")
      next = (index + 1) % available.length;
    else if (event.key === "ArrowLeft" || event.key === "ArrowUp")
      next = (index - 1 + available.length) % available.length;
    else if (event.key === "Home") next = 0;
    else if (event.key === "End") next = available.length - 1;
    else return;
    event.preventDefault();
    controls.current.get(available[next].id)?.focus();
  }

  if (!items.length) return null;
  return (
    <nav
      className={`is-dock ${className}`}
      aria-label={label}
      data-reduced-motion={reducedMotion || undefined}
    >
      <div
        className="is-dock-track"
        ref={track}
        onPointerLeave={() => setHovered(undefined)}
        onBlur={(event) => {
          if (!event.currentTarget.contains(event.relatedTarget))
            setFocused(undefined);
        }}
      >
        {marker && selected && (
          <span
            className="is-dock-marker"
            aria-hidden="true"
            style={{ left: marker.left, width: marker.width }}
          />
        )}
        {items.map((item) => {
          const active = item.id === selectedId;
          const attributes = {
            className: "is-dock-item",
            "aria-label": item.label,
            "data-expanded": item.id === expanded,
            "data-active": active,
            "data-disabled": item.disabled || undefined,
            onFocus: () => {
              setHovered(undefined);
              setFocused(item.id);
            },
            onPointerEnter: (event: PointerEvent) => {
              if (event.pointerType !== "touch" && !item.disabled)
                setHovered(item.id);
            },
            onKeyDown: (event: KeyboardEvent) => navigate(event, item.id),
            onClick: (event: MouseEvent) => {
              // Opening a link in another tab should not change this page's destination.
              if (
                item.href &&
                (event.metaKey ||
                  event.ctrlKey ||
                  event.shiftKey ||
                  event.altKey)
              )
                return;
              select(item);
            },
            ref: (node: HTMLAnchorElement | HTMLButtonElement | null) => {
              if (node) controls.current.set(item.id, node);
              else controls.current.delete(item.id);
            },
          };
          const content = (
            <>
              <span className="is-dock-icon" aria-hidden="true">
                {item.icon}
              </span>
              <span className="is-dock-label" aria-hidden="true">
                <span>{item.label}</span>
              </span>
            </>
          );
          // Disabled destinations are buttons, so there is no navigable disabled link.
          return item.href && !item.disabled ? (
            <a
              key={item.id}
              {...attributes}
              href={item.href}
              aria-current={active ? "page" : undefined}
            >
              {content}
            </a>
          ) : (
            <button
              key={item.id}
              {...attributes}
              type="button"
              disabled={item.disabled}
              aria-pressed={active}
            >
              {content}
            </button>
          );
        })}
      </div>
    </nav>
  );
}
expandable-dock.css
.is-dock {
  --dock-surface: var(--surface, #18181b);
  --dock-text: var(--text, #f4f4f5);
  --dock-muted: var(--muted, #a7a7af);
  --dock-border: var(--line, #34343b);
  --dock-selected: var(--raised, #29292e);
  --dock-accent: var(--accent, #b2cfff);
  box-sizing: border-box;
  width: 100%;
  max-width: 430px;
  padding: 6px;
  border: 1px solid var(--dock-border);
  border-radius: 22px;
  background: var(--dock-surface);
  color: var(--dock-text);
  box-shadow:
    0 8px 24px #00000012,
    inset 0 1px 0 #ffffff08;
}
.is-dock *,
.is-dock *::before,
.is-dock *::after {
  box-sizing: border-box;
}
.is-dock-track {
  display: flex;
  gap: 4px;
  position: relative;
}
.is-dock-item {
  position: relative;
  z-index: 1;
  flex: 1 1 0px;
  min-width: 44px;
  height: 48px;
  border: 0;
  border-radius: 16px;
  padding: 0 12px;
  display: flex;
  justify-content: center;
  align-items: center;
  color: var(--dock-muted);
  background: transparent;
  text-decoration: none;
  font-size: 13px;
  font-weight: 500;
  line-height: 1.2;
  font-family: inherit;
  cursor: pointer;
  -webkit-tap-highlight-color: transparent;
  transition:
    flex-grow 280ms cubic-bezier(0.22, 1, 0.36, 1),
    color 160ms;
}
.is-dock-item[data-expanded="true"] {
  flex-grow: 3;
  color: var(--dock-text);
}
.is-dock-item[data-active="true"] {
  color: var(--dock-text);
}
.is-dock-item[data-disabled] {
  opacity: 0.45;
  cursor: not-allowed;
}
.is-dock-item:focus-visible {
  outline: 2px solid var(--dock-accent);
  outline-offset: 2px;
}
.is-dock-icon {
  display: grid;
  place-items: center;
  flex: 0 0 20px;
  width: 20px;
  height: 20px;
}
.is-dock-icon > svg {
  width: 20px;
  height: 20px;
}
.is-dock-label {
  display: grid;
  grid-template-columns: 0fr;
  opacity: 0;
  min-width: 0;
  transition:
    grid-template-columns 280ms cubic-bezier(0.22, 1, 0.36, 1),
    opacity 160ms;
}
.is-dock-label > span {
  overflow: hidden;
  white-space: nowrap;
  text-overflow: ellipsis;
  min-width: 0;
  max-width: 130px;
}
.is-dock-item[data-expanded="true"] .is-dock-label {
  grid-template-columns: 1fr;
  opacity: 1;
  margin-left: 9px;
}
.is-dock-marker {
  position: absolute;
  top: 0;
  height: 48px;
  border-radius: 16px;
  background: var(--dock-selected);
  box-shadow: inset 0 1px 0 #ffffff0c;
  pointer-events: none;
  transition:
    left 220ms cubic-bezier(0.22, 1, 0.36, 1),
    width 220ms cubic-bezier(0.22, 1, 0.36, 1);
}
.is-dock-marker::after {
  content: "";
  position: absolute;
  width: 14px;
  height: 2px;
  border-radius: 2px;
  background: var(--dock-accent);
  bottom: 5px;
  left: calc(50% - 7px);
}
.is-dock[data-reduced-motion] .is-dock-item,
.is-dock[data-reduced-motion] .is-dock-label,
.is-dock[data-reduced-motion] .is-dock-marker {
  transition: none;
}
@media (prefers-reduced-motion: reduce) {
  .is-dock .is-dock-item,
  .is-dock .is-dock-label,
  .is-dock .is-dock-marker {
    transition: none;
  }
}
@media (max-width: 360px) {
  .is-dock-item {
    padding: 0 7px;
  }
  .is-dock-item[data-expanded="true"] .is-dock-label {
    margin-left: 7px;
  }
}