Dock
dockDisplays magnifying icon shortcuts along an animated application dock.
Usage
Persistent bottom navigation (with a current item)
activeKey plus onSelect is the same controlled pattern as NavMenu and RouteTabs. The current item gets aria-current="page" and an indicator dot under the icon, a shape cue rather than colour alone. Once onSelect is provided, DockIcon renders as a real <button> (focusable, activated by Enter) and the container becomes a nav landmark.
Current: Home
const [active, setActive] = useState("home")
<Dock aria-label="Main navigation" activeKey={active} onSelect={setActive}>
<DockIcon itemKey="home" label="Home"><Home className="size-5" /></DockIcon>
<DockIcon itemKey="search" label="Search"><Search className="size-5" /></DockIcon>
<DockIcon itemKey="alerts" label="Notifications"><Bell className="size-5" /></DockIcon>
<DockIcon itemKey="settings" label="Settings"><Settings className="size-5" /></DockIcon>
</Dock>Basic usage
DockIcon package icon, when the mouse is close to it, the icon will be enlarged according to the horizontal distance (macOS magnification dock effect).
<Dock>
<DockIcon><Home className="size-5" /></DockIcon>
<DockIcon><Search className="size-5" /></DockIcon>
<DockIcon><Bell className="size-5" /></DockIcon>
<DockIcon><Settings className="size-5" /></DockIcon>
<DockIcon><User className="size-5" /></DockIcon>
</Dock>Stronger amplification
magnification increases the peak size and distance increases the range of influence to obtain a more exaggerated amplification effect.
<Dock magnification={84} distance={160}>
<DockIcon><Home className="size-5" /></DockIcon>
<DockIcon><Search className="size-5" /></DockIcon>
<DockIcon><Bell className="size-5" /></DockIcon>
</Dock>Custom resting size
iconSize Sets the base size when not hovering, adapting to more compact or looser docks.
<Dock iconSize={32}>
<DockIcon><Home className="size-4" /></DockIcon>
<DockIcon><Search className="size-4" /></DockIcon>
<DockIcon><Settings className="size-4" /></DockIcon>
</Dock>When to use
Use Dock for a floating row of shortcuts along the bottom or side of a page. Icons enlarge elastically as the pointer approaches, creating a macOS-like effect suited to portfolios, personal sites, and desktop-inspired interfaces. Use Navbar for conventional site navigation, or Menu and Menubar for functional action menus.
Import
import { Dock, DockIcon } from "@hulianui/ui"Props
Dock
| Name | Type | Default | Description |
|---|---|---|---|
| magnification | number | 64 | Peak icon size in pixels when the pointer is closest. |
| distance | number | 140 | Radius of the magnification influence in pixels. |
| iconSize | number | 40 | Resting icon size in pixels. |
| activeKey | string | - | Key of the current item, compared against each DockIcon's itemKey. |
| onSelect | (key: string) => void | - | Fired when an item is chosen. Providing it turns each `DockIcon` into a real `<button>` and upgrades the container to a nav landmark. |
| aria-label | string | - | Landmark name when the container renders as <nav>. |
| className | string | - | Additional class name. |
DockIcon
| Name | Type | Default | Description |
|---|---|---|---|
| itemKey | string | - | Key of this item, used with the Dock's activeKey and onSelect. |
| active | boolean | - | Forces the selected state, taking precedence over the activeKey comparison. |
| label | string | - | Accessible name when the icon is clickable, since icons rarely carry text. |
| className | string | - | Additional class name. |
Slots
Dock
| Slot | Type | Description |
|---|---|---|
| children | ReactNode | A set of DockIcon elements. |
DockIcon
| Slot | Type | Description |
|---|---|---|
| children | ReactNode | Content of one icon. |
Example
<Dock>
<DockIcon><Home className="size-5" /></DockIcon>
<DockIcon><Search className="size-5" /></DockIcon>
<DockIcon><Settings className="size-5" /></DockIcon>
</Dock>Usage guidelines
- A current item is core information for a Dock, not decoration. The macOS Dock itself highlights the active app and marks running ones; on the web a Dock is typically a persistent bottom navigation, which must answer "where am I". Express it with
activeKeyplusitemKeyonDockIcon, and the component emitsaria-current="page"together with an indicator dot under the icon, a shape cue rather than colour alone. - `DockIcon` only becomes a real `<button>` when `onSelect` is provided (focusable, activated by Enter), and the container then upgrades to a
navlandmark. Without it the icon stays a non-semantic container, because many consumers put their own<a>in the children and an automatic button wrapper would nest interactive elements.
- Native macOS and Tauri system-Dock caveats do not apply to this React component.
- Magnification depends on the
mouseXvalue distributed through context and animated with Motion springs, so it is a client-side interaction. Give icon artwork a consistent fixed size such assize-5so every item scales uniformly.
Related
Navbar · BeianFooter · NavMenu · NavigationMenu · Menu · Menubar