Dock

The Liquid Glass shelf of app icons with magnification, running indicators, badges, labels and auto-hide. Windows minimize into it.

Installation

pnpm dlx shadcn@latest add @cupertinoui/dock

The first install also adds the macOS theme. See Installation to set up the registry.

Usage

import { Dock, DockIcon, DockItem, DockSeparator } from "@/components/ui/dock"

<Dock magnification={77}>
  <DockItem label="Finder" running>
    <DockIcon className="bg-blue-500 text-white">
      <FolderIcon />
    </DockIcon>
  </DockItem>
  <DockItem label="Mail" running badge={3}>
    <DockIcon className="bg-blue-500 text-white">
      <FolderIcon />
    </DockIcon>
  </DockItem>
  <DockSeparator />
  <DockItem label="Trash">
    <Trash2Icon />
  </DockItem>
</Dock>
The Dock doesn't position itself. Place it at the bottom of a positioned container, e.g. absolute bottom-2 left-1/2 -translate-x-1/2.
Like Apple's icon grid, DockIcon and any img or svg inside a DockItem fill 80.5% of the tile, and DockIcon sizes a symbol to 62% of that. For full-bleed artwork, add [&>svg]:size-full to the DockIcon or use an img.
Badges and icons scale with their tile as it magnifies.

Examples

Auto-hide

With autoHide, the Dock stays out of the way until the pointer reaches the bottom edge of its container. Set revealed to show it from code, e.g. while a window minimizes into it.

Minimizing windows

Pass a ref to a DockItem as a Window's minimizeTo, and the window minimizes into it with the Genie effect.

API Reference

Every part forwards the props of the underlying Base UI Tooltip part. The props below are the ones CupertinoUI adds or changes.

Dock

PropTypeDescription
sizenumber
Default: 51
The tile size in pixels, like the Size slider in Desktop & Dock settings. Tiles sit 2px apart.
magnificationnumberThe size a tile grows to under the pointer. Tiles up to four places away grow less. Leave it out to turn magnification off.
autoHideboolean
Default: false
Hides the Dock until the pointer reaches the bottom edge of its container.
revealedboolean
Default: false
Shows an auto-hiding Dock regardless of the pointer.
classNamestringExtra classes, merged with the component's own.

DockItem

A button laid over the item's content, so the content can be anything, even a live miniature of a window. Takes the props of a button; its ref is the button.

PropTypeDescription
labelReactNodeShown in a tooltip above the item, and used as its accessible name when it is a string.
runningboolean
Default: false
Shows the dot below the icon.
badgeReactNodeA red badge in the top-right corner, e.g. an unread count.
classNamestringExtra classes, merged with the component's own.

DockIcon

A squircle app icon on the icon grid. Give it a background and put a symbol inside.

PropTypeDescription
classNamestringExtra classes, merged with the component's own.

DockSeparator

The divider between apps and minimized windows, folders or the Trash.

PropTypeDescription
classNamestringExtra classes, merged with the component's own.