Hover Navigation Indicator

Installation#

CLI

npx shadcn@latest add https://hantui-theta.vercel.app/r/hover-nav-indicator.json

Manual

1. Install the dependencies

   npmpnpmbunyarn

   npm install clsx motion tailwind-merge

2. Add the shared helpers

   Components use cn() from lib/utils.ts and the motion tokens below. See Installation if you have not set them up yet.

   lib/motion.ts

   import type { Transition, Variants } from "motion/react";
   
   /** Durations in seconds. */
   export const duration = {
     instant: 0.1,
     quick: 0.18,
     base: 0.28,
     slow: 0.45,
   } as const;
   
   /** Cubic-bezier curves. */
   export const ease = {
     /** Entering, UI response. */
     out: [0.22, 1, 0.36, 1],
     /** Moving on screen. */
     inOut: [0.65, 0, 0.35, 1],
     /** Sheets and the mobile menu. */
     drawer: [0.32, 0.72, 0, 1],
   } as const;
   
   /** Everyday UI: presses, icon swaps, popovers and modals. Exits run at `exitFactor` of the enter. */
   export const ui = {
     press: { scale: 0.96, duration: 0.12 },
     icon: { type: "spring", duration: 0.3, bounce: 0 },
     popover: { duration: 0.18, ease: ease.out },
     modal: { duration: 0.24, ease: ease.out },
     exitFactor: 0.6,
   } as const;
   
   /** Once-per-visit motion on the landing page: hero letters, the reel and the afterimage. */
   export const kinetic = {
     heroLetter: { duration: 0.6, ease: ease.out },
     /** Delay per letter, eased so the wave slows toward the end. */
     heroStep: 0.035,
     reelSwap: { type: "spring", duration: 0.5, bounce: 0.1 },
     /** Two afterimages: lag in seconds and opacity of each. */
     ghost: { lag: [0.04, 0.09], opacity: [0.14, 0.06] },
   } as const;
   
   /** Spring presets. */
   export const spring = {
     snappy: { type: "spring", stiffness: 500, damping: 30 },
     smooth: { type: "spring", stiffness: 260, damping: 26 },
     bouncy: { type: "spring", stiffness: 300, damping: 15 },
   } as const satisfies Record<string, Transition>;
   
   /** Stagger between siblings, in seconds (0.03–0.06). */
   export const stagger = {
     tight: 0.03,
     base: 0.045,
     loose: 0.06,
   } as const;
   
   /** Blur + fade + y-offset. Falls back to a plain fade under reduced motion. */
   export function enterVariants(reduceMotion?: boolean | null, y = 8): Variants {
     if (reduceMotion) {
       return {
         hidden: { opacity: 0 },
         visible: { opacity: 1, transition: { duration: duration.base } },
         exit: { opacity: 0, transition: { duration: duration.quick } },
       };
     }
     return {
       hidden: { opacity: 0, y, filter: "blur(4px)" },
       visible: {
         opacity: 1,
         y: 0,
         filter: "blur(0px)",
         transition: { duration: duration.base, ease: ease.out },
       },
       exit: {
         opacity: 0,
         y: -y / 2,
         filter: "blur(4px)",
         transition: { duration: duration.quick, ease: ease.out },
       },
     };
   }
   
   /** Scale 0.96 → 1 for popovers, menus and dialogs. */
   export function overlayVariants(reduceMotion?: boolean | null): Variants {
     if (reduceMotion) {
       return {
         hidden: { opacity: 0 },
         visible: { opacity: 1, transition: { duration: duration.quick } },
         exit: { opacity: 0, transition: { duration: duration.instant } },
       };
     }
     return {
       hidden: { opacity: 0, scale: 0.96, filter: "blur(2px)" },
       visible: {
         opacity: 1,
         scale: 1,
         filter: "blur(0px)",
         transition: { duration: duration.quick, ease: ease.out },
       },
       exit: {
         opacity: 0,
         scale: 0.96,
         filter: "blur(2px)",
         transition: { duration: duration.instant + 0.02, ease: ease.out },
       },
     };
   }
   
   /** Parent variants that stagger their children in. */
   export function staggerVariants(gap: number = stagger.base, delayChildren = 0): Variants {
     return {
       hidden: {},
       visible: { transition: { staggerChildren: gap, delayChildren } },
       exit: { transition: { staggerChildren: gap / 2, staggerDirection: -1 } },
     };
   }

   Show all 113 lines

3. Copy the source

   components/ui/hover-nav-indicator/hover-nav-indicator.tsx

   "use client";
   
   import { useId, useState, type ComponentProps, type ElementType, type MouseEvent, type ReactNode } from "react";
   import { LayoutGroup, motion, useReducedMotion } from "motion/react";
   import { cn } from "@/lib/utils";
   import { spring } from "@/lib/motion";
   
   export interface HoverNavItem {
     /** Link text. */
     label: string;
     /** Destination. */
     href: string;
     /** Icon before the label. */
     icon?: ReactNode;
   }
   
   export interface HoverNavIndicatorProps
     extends Omit<ComponentProps<"nav">, "children" | "onAnimationStart" | "onDrag" | "onDragStart" | "onDragEnd"> {
     /** Links, in order. */
     items: HoverNavItem[];
     /** href of the current page; the indicator rests here. */
     activeHref?: string;
     /** Indicator style. @default "pill" */
     variant?: "pill" | "underline";
     /** Lay links out in a row or a column. @default "horizontal" */
     orientation?: "horizontal" | "vertical";
     /** Link component to render, e.g. Next.js Link. @default "a" */
     linkComponent?: ElementType;
     /** Called on click, e.g. to update activeHref or prevent default for client routing. */
     onNavigate?: (href: string, event: MouseEvent<HTMLElement>) => void;
   }
   
   export function HoverNavIndicator({
     items,
     activeHref,
     variant = "pill",
     orientation = "horizontal",
     linkComponent: Link = "a",
     onNavigate,
     className,
     "aria-label": ariaLabel = "Main",
     ...props
   }: HoverNavIndicatorProps) {
     const [hovered, setHovered] = useState<string | null>(null);
     const [focused, setFocused] = useState<string | null>(null);
     const reduceMotion = useReducedMotion();
     const groupId = useId();
     const vertical = orientation === "vertical";
     // The indicator follows focus, then hover, and rests on the current page.
     const target = focused ?? hovered ?? activeHref ?? null;
   
     return (
       <nav aria-label={ariaLabel} className={className} {...props}>
         <LayoutGroup id={groupId}>
           <ul
             onPointerLeave={() => setHovered(null)}
             className={cn("relative flex", vertical ? "w-full flex-col gap-0.5" : "flex-wrap items-center gap-1")}
           >
             {items.map((item) => {
               const isActive = item.href === activeHref;
               const isTarget = item.href === target;
               return (
                 <li key={item.href} className={cn("relative", vertical && "w-full")}>
                   <Link
                     href={item.href}
                     aria-current={isActive ? "page" : undefined}
                     onPointerEnter={() => setHovered(item.href)}
                     onFocus={() => setFocused(item.href)}
                     onBlur={() => setFocused(null)}
                     onClick={(event: MouseEvent<HTMLElement>) => onNavigate?.(item.href, event)}
                     className={cn(
                       "relative flex items-center gap-2 text-sm font-medium whitespace-nowrap outline-none transition-colors duration-150",
                       "focus-visible:ring-2 focus-visible:ring-ring [&_svg]:size-4 [&_svg]:shrink-0",
                       vertical ? "h-9 w-full rounded-md px-3" : "h-9 rounded-md px-3",
                       isActive || isTarget ? "text-foreground" : "text-muted-foreground",
                     )}
                   >
                     {isTarget ? (
                       <motion.span
                         layoutId="indicator"
                         aria-hidden="true"
                         transition={reduceMotion ? { duration: 0 } : spring.snappy}
                         className={cn(
                           "absolute",
                           variant === "pill"
                             ? cn("inset-0 rounded-md", isActive ? "bg-accent" : "bg-accent/70")
                             : vertical
                               ? "inset-y-1.5 left-0 w-0.5 rounded-full bg-foreground"
                               : "inset-x-3 -bottom-1 h-0.5 rounded-full bg-foreground",
                         )}
                       />
                     ) : null}
                     <span className="relative flex items-center gap-2">
                       {item.icon}
                       {item.label}
                     </span>
                   </Link>
                 </li>
               );
             })}
           </ul>
         </LayoutGroup>
       </nav>
     );
   }

   Show all 105 lines

Usage#

import Link from "next/link";
import { usePathname } from "next/navigation";
import { HoverNavIndicator } from "@/components/ui/hover-nav-indicator/hover-nav-indicator";

export function SiteNav() {
  const pathname = usePathname();
  return (
    <HoverNavIndicator
      linkComponent={Link}
      activeHref={pathname}
      items={[
        { label: "Product", href: "/product" },
        { label: "Pricing", href: "/pricing" },
      ]}
    />
  );
}

API reference#

Accessibility#

• Real links inside a labelled <nav>; the current page has aria-current="page".
• The indicator follows keyboard focus as well as hover, so Tab users see the same glide.
• The indicator is decorative (aria-hidden); the current page is also shown with a stronger text color.
• With reduced motion enabled, the indicator jumps instead of gliding.