Dock Rails Components
Create a dock menu with icons and labels, get a drop-up menu on mobile, set up shortcuts.
Installation
1. Stimulus Controller Setup
Start by adding the following controller to your project:
import { Controller } from "@hotwired/stimulus";
import { animate, stagger, spring, transform } from "motion";
const ICON_REST_SIZE = 40;
const ICON_MAX_SIZE = 80;
const MAGNIFY_RANGE = 150; // px from an icon's center where it starts to grow
// Maps the pointer's distance from an icon to that icon's size.
const iconSizeFor = transform([-MAGNIFY_RANGE, 0, MAGNIFY_RANGE], [ICON_REST_SIZE, ICON_MAX_SIZE, ICON_REST_SIZE]);
const TOOLTIP_BASE_CLASSES =
"pointer-events-none absolute left-1/2 z-50 -translate-x-1/2 whitespace-nowrap px-1.5 py-1 text-xs font-medium text-neutral-900 bg-white border border-neutral-200/70 rounded-md shadow-sm opacity-0 dark:bg-neutral-800 dark:border-neutral-600/50 dark:text-neutral-100";
const TOOLTIP_PLACEMENT_CLASSES = {
top: "bottom-full mb-2",
bottom: "top-full mt-2",
};
const TOOLTIP_HOTKEY_CLASSES =
"capitalize text-[10px] font-semibold ml-0.5 px-1 py-px bg-neutral-200 dark:bg-neutral-700 text-neutral-800 dark:text-neutral-200 rounded";
const DESKTOP_ACTIVE_CLASSES =
"text-neutral-50 dark:text-neutral-800 bg-neutral-800 dark:bg-neutral-100 active:bg-neutral-700 dark:active:bg-neutral-200";
const DESKTOP_INACTIVE_CLASSES =
"text-neutral-500 dark:text-neutral-300 bg-neutral-200 dark:bg-neutral-800 active:bg-neutral-300 dark:active:bg-neutral-700";
const MOBILE_ACTIVE_CLASSES =
"text-neutral-50 dark:text-neutral-800 hover:text-neutral-50 dark:hover:text-neutral-800 bg-neutral-800 dark:bg-neutral-100 active:bg-neutral-700 dark:active:bg-neutral-200";
const MOBILE_INACTIVE_CLASSES =
"text-neutral-500 dark:text-neutral-300 hover:text-neutral-500 dark:hover:text-neutral-300 bg-neutral-50 dark:bg-neutral-800 active:bg-neutral-100 dark:active:bg-neutral-700";
export default class extends Controller {
static targets = ["icon", "mobileMenu", "mobileButton", "mobileGlow"];
// A dock is often marked data-turbo-permanent, so Turbo moves it into each new page and
// disconnects/reconnects this controller on every visit. One-time setup lives here so it
// runs once and the element listeners aren't stacked on each reconnect.
initialize() {
this.isToggling = false;
this.initDesktopHover();
this.initTooltips();
}
connect() {
this.updateActiveMenu();
this.updateActiveMenuBound = () => this.updateActiveMenu();
document.addEventListener("turbo:load", this.updateActiveMenuBound);
// Highlight the destination right away instead of waiting for the page to arrive.
this.highlightVisitBound = (event) => this.updateActiveMenu(new URL(event.detail.url, window.location.origin));
document.addEventListener("turbo:visit", this.highlightVisitBound);
// On a permanent dock, a clicked icon keeps focus across pages and shows a focus ring
// on the next keypress. Drop it like a full page load would.
this.releaseFocusBound = () => {
if (this.element.contains(document.activeElement)) document.activeElement.blur();
};
document.addEventListener("turbo:load", this.releaseFocusBound);
}
disconnect() {
document.removeEventListener("turbo:load", this.updateActiveMenuBound);
document.removeEventListener("turbo:visit", this.highlightVisitBound);
document.removeEventListener("turbo:load", this.releaseFocusBound);
}
// Desktop magnification
initDesktopHover() {
this.mouseX = Infinity;
this.iconSizes = this.iconTargets.map(() => ICON_REST_SIZE);
this.reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
let frameRequest = null;
// At most one update per frame, however often mousemove fires.
const scheduleUpdate = () => {
frameRequest ??= requestAnimationFrame(() => {
frameRequest = null;
this.updateIconAnimations();
});
};
this.element.addEventListener("mouseenter", () => this.measureRestCenters());
this.element.addEventListener("mousemove", (event) => {
this.mouseX = event.clientX;
scheduleUpdate();
});
this.element.addEventListener("mouseleave", () => {
this.mouseX = Infinity;
scheduleUpdate();
});
}
// Where each icon's center sits when nothing is magnified. The row stays centered while it
// grows, so these hold during a hover and the per-frame update never has to read layout.
measureRestCenters() {
const icons = this.iconTargets;
const row = icons[0]?.parentElement;
if (!row) return;
const rowRect = row.getBoundingClientRect();
const rowCenter = rowRect.left + rowRect.width / 2;
const step = ICON_REST_SIZE + (parseFloat(getComputedStyle(row).columnGap) || 0);
this.restCenters = icons.map((_, index) => rowCenter + (index - (icons.length - 1) / 2) * step);
}
updateIconAnimations() {
if (!this.restCenters) this.measureRestCenters();
if (!this.restCenters) return;
const magnify = !this.reducedMotion.matches;
this.iconTargets.forEach((icon, index) => {
const targetSize = magnify ? Math.round(iconSizeFor(this.mouseX - this.restCenters[index])) : ICON_REST_SIZE;
// Skip icons whose target hasn't changed, so the spring isn't restarted every frame.
if (this.iconSizes[index] === targetSize) return;
this.iconSizes[index] = targetSize;
const iconElement = icon.firstElementChild;
if (!iconElement) return;
animate(
iconElement,
{ width: `${targetSize}px`, height: `${targetSize}px` },
{ type: spring, stiffness: 950, damping: 120, mass: 0.7, restDelta: 0.1 },
);
});
}
// Mobile menu
async toggleMobile(event) {
if (this.isToggling || !this.hasMobileMenuTarget) return;
this.isToggling = true;
// A tap shouldn't leave a focus ring behind once a key is pressed.
if (event?.detail && this.hasMobileButtonTarget) this.mobileButtonTarget.blur();
const isOpening = this.mobileMenuTarget.classList.contains("hidden");
if (this.hasMobileButtonTarget) this.mobileButtonTarget.setAttribute("aria-expanded", isOpening);
if (isOpening) {
this.mobileMenuTarget.classList.remove("hidden");
if (this.hasMobileGlowTarget) this.mobileGlowTarget.classList.remove("hidden");
this.mobileMenuTarget.style.pointerEvents = "auto";
} else {
// Disable pointer events right away so items can't be hovered while they fade out.
this.mobileMenuTarget.style.pointerEvents = "none";
}
await new Promise((resolve) => requestAnimationFrame(resolve));
await Promise.all([
this.animateMobileMenu(isOpening),
this.rotateMobileButton(isOpening),
this.animateMobileGlow(isOpening),
]);
if (!isOpening) {
this.mobileMenuTarget.classList.add("hidden");
if (this.hasMobileGlowTarget) this.mobileGlowTarget.classList.add("hidden");
}
this.isToggling = false;
}
animateMobileMenu(isOpening) {
const menuItems = Array.from(this.mobileMenuTarget.children);
const properties = {
opacity: [isOpening ? 0 : 1, isOpening ? 1 : 0],
y: [isOpening ? 20 : 0, isOpening ? 0 : 10],
scale: [isOpening ? 0.9 : 1, isOpening ? 1 : 0.95],
};
const options = isOpening
? { delay: stagger(0.01, { start: 0.1, from: "first" }), duration: 0.3, type: spring, stiffness: 500, damping: 25, mass: 1.5 }
: { delay: stagger(0.01, { from: "last" }), duration: 0.1, type: spring, stiffness: 400, damping: 45, mass: 1.5 };
const animations = animate(menuItems, properties, options);
return Array.isArray(animations) ? Promise.all(animations.map((a) => a.finished)) : animations.finished;
}
// The glow blooms out of the button corner on open and sinks back into it on close.
animateMobileGlow(isOpening) {
if (!this.hasMobileGlowTarget) return Promise.resolve();
return animate(
this.mobileGlowTarget,
{ opacity: isOpening ? 1 : 0, scale: isOpening ? [0.4, 1] : 0.6 },
isOpening ? { type: spring, stiffness: 260, damping: 26, mass: 1 } : { duration: 0.18, ease: "easeIn" },
).finished;
}
rotateMobileButton(isOpening) {
const buttonIcon = this.hasMobileButtonTarget && this.mobileButtonTarget.querySelector("svg");
if (!buttonIcon) return Promise.resolve();
return animate(
buttonIcon,
{ rotate: isOpening ? "180deg" : "0deg" },
{ type: spring, stiffness: 1150, damping: 80, mass: 5, restDelta: 0.1 },
).finished;
}
// One shared tooltip that moves into whichever icon is hovered. CSS anchors it above (or
// below) the icon, so it follows the icon as it grows without any per-frame positioning.
//
// It shows while an icon is hovered or keyboard-focused. Turbo moving the permanent dock into the next
// page blurs and refocuses the clicked icon, and turbo:load then blurs it for good. The pointer
// never left, so those don't count: events during the swap are ignored, and a blur only hides
// the tooltip once the icon isn't hovered either.
initTooltips() {
this.tooltip = document.createElement("div");
this.tooltip.setAttribute("role", "tooltip");
this.hoveredIcon = null;
this.focusedIcon = null;
this.tooltipIcon = null;
this.isRendering = false;
const track = (icon, key, value) => {
if (this.isRendering) return;
this[key] = value ? icon : this[key] === icon ? null : this[key];
this.syncTooltip();
};
this.iconTargets.forEach((icon) => {
icon.addEventListener("mouseenter", () => track(icon, "hoveredIcon", true));
icon.addEventListener("mouseleave", () => track(icon, "hoveredIcon", false));
// Keyboard focus only: a click focuses the link too, and that shouldn't hold the tooltip open.
icon.addEventListener("focus", () => track(icon, "focusedIcon", icon.matches(":focus-visible")));
icon.addEventListener("blur", () => track(icon, "focusedIcon", false));
});
document.addEventListener("turbo:before-render", () => (this.isRendering = true));
document.addEventListener("turbo:render", () => (this.isRendering = false));
}
syncTooltip() {
const icon = this.hoveredIcon || this.focusedIcon;
if (icon) {
this.showTooltip(icon);
} else {
this.hideTooltip();
}
}
showTooltip(icon) {
if (this.tooltipIcon === icon) return;
this.tooltipIcon = icon;
const label = icon.dataset.tooltip;
if (!label) return;
const placement = icon.dataset.tooltipPlacement === "bottom" ? "bottom" : "top";
this.tooltip.className = `${TOOLTIP_BASE_CLASSES} ${TOOLTIP_PLACEMENT_CLASSES[placement]}`;
this.tooltip.replaceChildren(document.createTextNode(label));
const hotkey = icon.dataset.tooltipHotkey?.trim();
if (hotkey) {
const hotkeyBadge = document.createElement("span");
hotkeyBadge.className = TOOLTIP_HOTKEY_CLASSES;
hotkeyBadge.textContent = hotkey;
this.tooltip.append(" ", hotkeyBadge);
}
icon.appendChild(this.tooltip);
animate(this.tooltip, { opacity: 1 }, { duration: 0.3 });
}
hideTooltip() {
if (!this.tooltipIcon) return;
this.tooltipIcon = null;
animate(this.tooltip, { opacity: 0 }, { duration: 0.1 });
}
// Highlights the item matching the given URL (the current location by default).
// Items without search params match on pathname; items with them must match exactly.
updateActiveMenu(location = window.location) {
const matches = (anchor) => {
try {
const anchorUrl = new URL(anchor.getAttribute("href"), window.location.origin);
if (anchorUrl.pathname !== location.pathname) return false;
return anchorUrl.search === "" || anchorUrl.search === location.search;
} catch {
return false;
}
};
const setState = (element, isActive, activeClasses, inactiveClasses) => {
element.classList.remove(...(isActive ? inactiveClasses : activeClasses).split(" "));
element.classList.add(...(isActive ? activeClasses : inactiveClasses).split(" "));
if (isActive) {
element.closest("a")?.setAttribute("aria-current", "page");
} else {
element.closest("a")?.removeAttribute("aria-current");
}
};
this.iconTargets.forEach((anchor) => {
const iconBox = anchor.firstElementChild;
if (iconBox) setState(iconBox, matches(anchor), DESKTOP_ACTIVE_CLASSES, DESKTOP_INACTIVE_CLASSES);
});
if (this.hasMobileMenuTarget) {
this.mobileMenuTarget.querySelectorAll("a").forEach((anchor) => {
setState(anchor, matches(anchor), MOBILE_ACTIVE_CLASSES, MOBILE_INACTIVE_CLASSES);
});
}
}
}
2. Motion.dev Installation
pin "motion", to: "https://cdn.jsdelivr.net/npm/motion@14.14.0/+esm"
Terminal
npm install motion
Terminal
yarn add motion
Examples
Basic Dock
2 examples dock menus with icons, hotkeys and tooltips.
Desktop version - with hotkeys - tooltip above icons
Mobile version
Desktop version - with hotkeys - tooltip below icons
Mobile version
<div class="w-full max-w-md">
<% menu_items = [
{ url: "#", tooltip: "Home", hotkey: "h", svg: '<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M14.855,6.2l-5.25-3.99c-.358-.272-.853-.272-1.21,0L3.145,6.2c-.249,.189-.395,.484-.395,.797v7.254c0,1.105,.895,2,2,2h2.5v-4c0-.552,.448-1,1-1h1.5c.552,0,1,.448,1,1v4h2.5c1.105,0,2-.895,2-2V6.996c0-.313-.146-.607-.395-.797Z"></path></g></svg>' },
{ url: "#", tooltip: "Articles", hotkey: "a", svg: '<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M14.25,12.25v2c0,1.105-.895,2-2,2H3.75c-1.105,0-2-.895-2-2V3.75c0-1.105,.895-2,2-2H12.25c1.105,0,2,.895,2,2v1.5"></path><line x1="4.75" y1="5.75" x2="9.25" y2="5.75"></line><line x1="4.75" y1="8.75" x2="7" y2="8.75"></line><line x1="4.75" y1="11.75" x2="6.25" y2="11.75"></line><path d="M12.375,10.625c.444-.444,2.948-2.948,4.216-4.216,.483-.483,.478-1.261-.005-1.745h0c-.483-.483-1.261-.489-1.745-.005-1.268,1.268-3.772,3.772-4.216,4.216-.625,.625-1.125,2.875-1.125,2.875,0,0,2.25-.5,2.875-1.125Z"></path></g></svg>' },
{ url: "#", tooltip: "Projects", hotkey: "p", svg: '<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><circle cx="8" cy="5.5" r="3.75"></circle><path d="M1.953,15c1.298-1.958,3.522-3.25,6.047-3.25"></path><path d="M14.925,16.25h-6.175l1.868-4.203c.08-.181,.259-.297,.457-.297h5.406c.362,0,.604,.372,.457,.703l-1.556,3.5c-.08,.181-.259,.297-.457,.297Z"></path><line x1="8.75" y1="16.25" x2="5.75" y2="16.25"></line></g></svg>' },
{ url: "#", tooltip: "Courses", hotkey: "c", svg: '<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M13.25,9.75c.361,0,.705-.077,1.015-.214"></path><path d="M12.961,5.962c.336-.393,.539-.904,.539-1.462"></path><path d="M12.221,12.965c.301,.181,.653,.285,1.029,.285,.076,0,.15-.004,.224-.012"></path><path d="M9,4.5c0-1.243,1.007-2.25,2.25-2.25,1.243,0,2.25,1.007,2.25,2.25,0,.093-.016,.182-.027,.272,1.275,.114,2.277,1.173,2.277,2.478,0,1.02-.613,1.895-1.489,2.283,.589,.348,.989,.983,.989,1.717,0,1.028-.779,1.865-1.777,1.978,.011,.09,.027,.179,.027,.272,0,1.243-1.007,2.25-2.25,2.25-1.243,0-2.25-1.007-2.25-2.25"></path><path d="M4.75,9.75c-.361,0-.705-.077-1.015-.214"></path><path d="M5.039,5.962c-.336-.393-.539-.904-.539-1.462"></path><path d="M5.779,12.965c-.301,.181-.653,.285-1.029,.285-.076,0-.15-.004-.224-.012"></path><path d="M9,4.5c0-1.243-1.007-2.25-2.25-2.25s-2.25,1.007-2.25,2.25c0,.093,.016,.182,.027,.272-1.275,.114-2.277,1.173-2.277,2.478,0,1.02,.613,1.895,1.489,2.283-.589,.348-.989,.983-.989,1.717,0,1.028,.779,1.865,1.777,1.978-.011,.09-.027,.179-.027,.272,0,1.243,1.007,2.25,2.25,2.25s2.25-1.007,2.25-2.25"></path><line x1="9" y1="13.5" x2="9" y2="4.5"></line></g></svg>' },
{ url: "#", tooltip: "Books", hotkey: "b", svg: '<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><title>books</title><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M16,6.75c-.171-.387-.419-1.083-.422-1.984-.003-.918,.25-1.626,.422-2.016"></path><path d="M16.75,2.75H6.25c-1.105,0-2,.895-2,2h0c0,1.105,.895,2,2,2h10.5"></path><path d="M16,14.75c-.171-.387-.419-1.083-.422-1.984-.003-.918,.25-1.626,.422-2.016"></path><line x1="13.75" y1="14.75" x2="16.75" y2="14.75"></line><path d="M16.75,10.75H6.25c-1.105,0-2,.895-2,2h0c0,1.105,.895,2,2,2"></path><path d="M2,10.75c.171-.387,.419-1.083,.422-1.984,.003-.918-.25-1.626-.422-2.016"></path><path d="M1.25,6.75H11.75c1.105,0,2,.895,2,2h0c0,1.105-.895,2-2,2H1.25"></path><path d="M12,13h-4v3.5c0,.202,.122,.385,.309,.462,.187,.079,.401,.035,.545-.108l1.146-1.146,1.146,1.146c.096,.096,.224,.146,.354,.146,.064,0,.13-.012,.191-.038,.187-.077,.309-.26,.309-.462v-3.5Z" fill="currentColor" data-stroke="none" stroke="none"></path></g></svg>' },
{ url: "#", tooltip: "Timeline", hotkey: "t", svg: '<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><rect x="13.25" y="2.75" width="3.5" height="3.5" rx="1" ry="1"></rect><rect x="13.25" y="11.75" width="3.5" height="3.5" rx="1" ry="1"></rect><rect x="1.25" y="6.75" width="3.5" height="3.5" rx="1" ry="1"></rect><line x1="9" y1="1.75" x2="9" y2="16.25"></line><line x1="10.75" y1="4.75" x2="9" y2="4.75"></line><line x1="9" y1="8.25" x2="7.25" y2="8.25"></line><line x1="10.75" y1="13.25" x2="9" y2="13.25"></line></g></svg>' },
{ url: "#", tooltip: "Newsletter", hotkey: "n", svg: '<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M1.75,5.75l6.767,3.733c.301,.166,.665,.166,.966,0l6.767-3.733"></path><path d="M16.25,9.79V5.25c0-1.104-.895-2-2-2H3.75c-1.105,0-2,.896-2,2v7.5c0,1.104,.895,2,2,2h5.07"></path><polygon points="14.25 11.25 15.25 13.25 17.25 14.25 15.25 15.25 14.25 17.25 13.25 15.25 11.25 14.25 13.25 13.25 14.25 11.25"></polygon></g></svg>' }
] %>
<%# Frosted glow behind the open mobile menu, fading out from the bottom-right corner. %>
<% glow_classes = "pointer-events-none absolute -right-8 -bottom-8 hidden md:hidden w-[calc(min(34rem,120vw)+2rem)] h-[calc(min(40rem,85dvh)+2rem)] origin-bottom-right opacity-0 will-change-transform backdrop-blur-[6px] bg-[radial-gradient(farthest-side_at_100%_100%,rgb(250_250_250/0.94)_0%,rgb(250_250_250/0.8)_55%,rgb(250_250_250/0)_100%)] dark:bg-[radial-gradient(farthest-side_at_100%_100%,rgb(23_23_23/0.94)_0%,rgb(23_23_23/0.8)_55%,rgb(23_23_23/0)_100%)] [mask-image:radial-gradient(farthest-side_at_100%_100%,#000_55%,transparent_100%)]" %>
<%# Mobile toggle: a soft resting shadow that deepens while the menu is open. %>
<% fab_classes = "flex size-10 items-center justify-center rounded-full border border-neutral-400/50 dark:border-neutral-500/50 text-neutral-500 dark:text-neutral-400 bg-neutral-50 dark:bg-neutral-950 shadow-[0_1px_2px_rgb(0_0_0/0.06),0_4px_12px_-2px_rgb(0_0_0/0.14)] aria-expanded:shadow-[0_2px_4px_rgb(0_0_0/0.08),0_14px_32px_-6px_rgb(0_0_0/0.3)] dark:shadow-[0_1px_2px_rgb(0_0_0/0.4),0_8px_20px_-6px_rgb(0_0_0/0.6)] dark:aria-expanded:shadow-[0_2px_4px_rgb(0_0_0/0.5),0_14px_32px_-6px_rgb(0_0_0/0.8)] transition-[box-shadow,scale] duration-300 ease-out active:scale-92 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-neutral-600 dark:focus-visible:outline-neutral-300" %>
<% pill_classes = "will-change-transform opacity-0 px-3 no-underline gap-2 w-fit size-10 flex items-center justify-center rounded-full border border-neutral-400/50 dark:border-neutral-500/50 shadow-[0_1px_2px_rgb(0_0_0/0.06),0_8px_20px_-6px_rgb(0_0_0/0.22)] dark:shadow-[0_1px_2px_rgb(0_0_0/0.4),0_8px_20px_-6px_rgb(0_0_0/0.6)]" %>
<% icon_link_classes = "relative rounded-full focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-neutral-600 dark:focus-visible:outline-neutral-300" %>
<div class="relative max-md:overflow-hidden border border-neutral-200 rounded-xl p-4 bg-white dark:bg-neutral-800/50 dark:border-neutral-600">
<p class="hidden md:block text-sm text-neutral-600 dark:text-neutral-300 text-center">Desktop version - with hotkeys - tooltip above icons</p>
<p class="text-sm md:hidden text-neutral-600 dark:text-neutral-300 text-center">Mobile version</p>
<div class="rounded-xl h-[26rem] md:h-[16rem] flex items-end justify-center">
<div class="flex w-fit mx-auto items-center justify-center" data-controller="dock">
<nav aria-label="Dock" class="mx-auto hidden h-16 items-end gap-4 rounded-2xl bg-neutral-50 px-4 pb-3 md:flex dark:bg-neutral-950 border border-neutral-200/50 dark:border-neutral-600/50 shadow-sm">
<% menu_items.each do |item| %>
<% active = current_page?(item[:url]) %>
<a href="<%= item[:url] %>" class="<%= icon_link_classes %>" aria-label="<%= item[:tooltip] %>" data-dock-target="icon" data-tooltip-hotkey="<%= item[:hotkey] %>" data-tooltip="<%= item[:tooltip] %>" data-tooltip-placement="top" <%= "data-controller=hotkey data-action=keydown.#{item[:hotkey]}@document->hotkey#click" if item[:hotkey].present? %>>
<div class="size-10 relative flex aspect-square items-center justify-center rounded-full border border-neutral-200/50 dark:border-neutral-600/50 <%= active ? 'text-neutral-50 dark:text-neutral-800 bg-neutral-800 dark:bg-neutral-100 active:bg-neutral-700 dark:active:bg-neutral-200' : 'text-neutral-500 dark:text-neutral-300 bg-neutral-200 dark:bg-neutral-800 active:bg-neutral-300 dark:active:bg-neutral-700' %>">
<div class="flex items-center justify-center *:size-full" style="width: 50%; height: 50%" aria-hidden="true">
<%= raw(item[:svg]) %>
</div>
</div>
</a>
<% end %>
</nav>
<div class="<%= glow_classes %>" data-dock-target="mobileGlow"></div>
<nav aria-label="Dock" class="absolute right-5 bottom-17 flex items-end flex-col gap-2 hidden md:hidden" data-dock-target="mobileMenu">
<% menu_items.each do |item| %>
<% active = current_page?(item[:url]) %>
<a href="<%= item[:url] %>" data-tooltip="<%= item[:tooltip] %>" class="<%= pill_classes %> <%= active ? 'text-neutral-50 dark:text-neutral-800 hover:text-neutral-50 dark:hover:text-neutral-800 bg-neutral-800 dark:bg-neutral-100 active:bg-neutral-700 dark:active:bg-neutral-200' : 'text-neutral-500 dark:text-neutral-300 hover:text-neutral-500 dark:hover:text-neutral-300 bg-neutral-50 dark:bg-neutral-800 active:bg-neutral-100 dark:active:bg-neutral-700' %>">
<span class="text-sm"><%= item[:tooltip] %></span>
<span class="*:size-5" aria-hidden="true"><%= raw(item[:svg]) %></span>
</a>
<% end %>
</nav>
<div class="absolute right-5 bottom-5 block md:hidden">
<button type="button" data-dock-target="mobileButton" data-action="click->dock#toggleMobile" aria-expanded="false" aria-label="Menu" class="<%= fab_classes %>">
<svg class="size-5 rotate-0" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><polyline points="2.75 11.5 9 5.25 15.25 11.5"></polyline></g></svg>
</button>
</div>
</div>
</div>
</div>
<div class="mt-10 relative max-md:overflow-hidden border border-neutral-200 rounded-xl p-4 bg-white dark:bg-neutral-800/50 dark:border-neutral-600">
<div class="rounded-xl h-[26rem] md:h-[16rem] flex items-start justify-center">
<div class="flex w-fit mx-auto items-center justify-center" data-controller="dock">
<nav aria-label="Dock" class="mx-auto hidden h-16 items-start gap-4 rounded-2xl bg-neutral-50 px-4 pt-3 md:flex dark:bg-neutral-950 border border-neutral-200/50 dark:border-neutral-600/50 shadow-sm">
<% menu_items.each do |item| %>
<% active = current_page?(item[:url]) %>
<a href="<%= item[:url] %>" class="<%= icon_link_classes %>" aria-label="<%= item[:tooltip] %>" data-dock-target="icon" data-tooltip-hotkey="<%= item[:hotkey] %>" data-tooltip="<%= item[:tooltip] %>" data-tooltip-placement="bottom" <%= "data-controller=hotkey data-action=keydown.#{item[:hotkey]}@document->hotkey#click" if item[:hotkey].present? %>>
<div class="size-10 relative flex aspect-square items-center justify-center rounded-full border border-neutral-200/50 dark:border-neutral-600/50 <%= active ? 'text-neutral-50 dark:text-neutral-800 bg-neutral-800 dark:bg-neutral-100 active:bg-neutral-700 dark:active:bg-neutral-200' : 'text-neutral-500 dark:text-neutral-300 bg-neutral-200 dark:bg-neutral-800 active:bg-neutral-300 dark:active:bg-neutral-700' %>">
<div class="flex items-center justify-center *:size-full" style="width: 50%; height: 50%" aria-hidden="true">
<%= raw(item[:svg]) %>
</div>
</div>
</a>
<% end %>
</nav>
<div class="<%= glow_classes %>" data-dock-target="mobileGlow"></div>
<nav aria-label="Dock" class="absolute right-5 bottom-17 flex items-end flex-col gap-2 hidden md:hidden" data-dock-target="mobileMenu">
<% menu_items.each do |item| %>
<% active = current_page?(item[:url]) %>
<a href="<%= item[:url] %>" data-tooltip="<%= item[:tooltip] %>" class="<%= pill_classes %> <%= active ? 'text-neutral-50 dark:text-neutral-800 hover:text-neutral-50 dark:hover:text-neutral-800 bg-neutral-800 dark:bg-neutral-100 active:bg-neutral-700 dark:active:bg-neutral-200' : 'text-neutral-500 dark:text-neutral-300 hover:text-neutral-500 dark:hover:text-neutral-300 bg-neutral-50 dark:bg-neutral-800 active:bg-neutral-100 dark:active:bg-neutral-700' %>">
<span class="text-sm"><%= item[:tooltip] %></span>
<span class="*:size-5" aria-hidden="true"><%= raw(item[:svg]) %></span>
</a>
<% end %>
</nav>
<div class="absolute right-5 bottom-5 block md:hidden">
<button type="button" data-dock-target="mobileButton" data-action="click->dock#toggleMobile" aria-expanded="false" aria-label="Menu" class="<%= fab_classes %>">
<svg class="size-5 rotate-0" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><polyline points="2.75 11.5 9 5.25 15.25 11.5"></polyline></g></svg>
</button>
</div>
</div>
</div>
<p class="hidden md:block text-sm text-neutral-600 dark:text-neutral-300 text-center">Desktop version - with hotkeys - tooltip below icons</p>
<p class="text-sm md:hidden text-neutral-600 dark:text-neutral-300 text-center">Mobile version</p>
</div>
</div>
Configuration
The dock component is powered by a Stimulus controller that provides smooth hover animations, tooltips with hotkeys, mobile menu functionality, and automatic active state management based on the current URL.
Controller Setup
Basic dock structure with required data attributes:
<div class="flex w-fit mx-auto items-center justify-center" data-controller="dock">
<div class="mx-auto hidden h-16 items-end gap-4 rounded-2xl bg-neutral-50 px-4 pb-3 md:flex dark:bg-neutral-950 border border-neutral-200/50 dark:border-neutral-600/50">
<a href="/dashboard" class="relative rounded-full" aria-label="Dashboard" data-dock-target="icon" data-tooltip="Dashboard" data-tooltip-hotkey="d" data-tooltip-placement="top">
<div class="size-10 relative flex aspect-square items-center justify-center rounded-full border border-neutral-200/50 dark:border-neutral-600/50 text-neutral-500 dark:text-neutral-300 bg-neutral-200 dark:bg-neutral-800">
<div class="flex items-center justify-center *:size-full" style="width: 50%; height: 50%">
<!-- Icon SVG -->
</div>
</div>
</a>
</div>
</div>
Targets
Actions
Data Attributes
Animation Features
- Spring Physics: Dock icons use Motion's spring animations for natural, responsive hover effects
- Smart Scaling: Icons grow based on mouse proximity, updated at most once per frame and without layout reads while hovering. Disabled when the user prefers reduced motion
- Staggered Mobile Menu: Menu items animate in sequence with configurable stagger delays
- Smooth Transitions: Button rotations and menu visibility changes use optimized spring physics
Tooltip Features
- CSS Anchored: One shared tooltip moves into the hovered icon and is anchored above or below it with CSS, so no positioning library is needed
- Hotkey Display: Optional keyboard shortcuts shown in styled badges within tooltips
- Follows Magnification: The tooltip rides along as the icon grows, without any per-frame positioning work
- Keyboard Friendly: Tooltips also show when an icon receives keyboard focus
Active State Management
- URL-Based: Automatically highlights active menu items based on current pathname and search parameters
- Desktop & Mobile: Active states update simultaneously for both desktop dock icons and mobile menu items
-
Turbo Support: The destination is highlighted as soon as a Turbo visit starts, and works with a
data-turbo-permanentdock - Smart Matching: Supports both simple pathname matching and exact pathname + query parameter matching
Accessibility Features
- Keyboard Shortcuts: Integrate with the hotkey controller for accessible keyboard navigation
- Focus Management: Proper focus states for all interactive elements
-
Screen Reader Friendly: Icon links carry an
aria-label, the active link getsaria-current="page", and the mobile toggle exposesaria-expanded - Mobile Touch Support: Touch-optimized interactions with proper pointer event handling