# Dock

> macOS style dock with smooth magnification, launch bounce, badges, auto hide and right-click menus on any edge.

A macOS style dock. Icons swell on a spring as the pointer passes, hop when you click them, and show badges and open-app dots. Right click, long press, or press the menu key on an icon to open its context menu with checks, shortcuts and submenus.

<demo-dock>



</demo-dock>

## Installation

```bash
npx shadcn-vue@latest add "https://nxui.geoql.in/r/dock.json"
```

## Usage

The dock is absolutely positioned on an edge of its nearest positioned parent, so give the parent `position: relative` and a size.

```vue
<script setup lang="ts">
  import Dock from '~/components/ui/dock/Dock.vue';
  import type { DockItemData } from '~/components/ui/dock/types';

  const items: DockItemData[] = [
    {
      icon: 'lucide:house',
      label: 'Home',
      active: true,
      menu: [
        { label: 'New Window', shortcut: '⌘N' },
        { separator: true },
        {
          label: 'Options',
          items: [{ label: 'Open at Login', checked: false }],
        },
        { label: 'Quit' },
      ],
    },
    { icon: 'lucide:mail', label: 'Mail', badge: 3 },
    { icon: 'lucide:message-circle', label: 'Messages', badge: true },
    { separator: true },
    { icon: 'lucide:trash-2', label: 'Trash' },
  ];
</script>

<template>
  <div class="relative h-115 w-full overflow-hidden">
    <Dock :items="items" position="bottom" theme="dark" />
  </div>
</template>
```

## Props

<table>
<thead>
  <tr>
    <th>
      Prop
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        items
      </code>
    </td>
    
    <td>
      <code>
        DockItemData[]
      </code>
    </td>
    
    <td>
      <code>
        []
      </code>
    </td>
    
    <td>
      The apps in the dock. See the item shape below. Add <code>
        { separator: true }
      </code>
      
       to divide groups.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        position
      </code>
    </td>
    
    <td>
      <code>
        'bottom' | 'top' | 'left' | 'right'
      </code>
    </td>
    
    <td>
      <code>
        'bottom'
      </code>
    </td>
    
    <td>
      Edge of the positioned parent the dock sits on. Icons grow away from it; left and right are vertical.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        theme
      </code>
    </td>
    
    <td>
      <code>
        'dark' | 'light'
      </code>
    </td>
    
    <td>
      <code>
        'dark'
      </code>
    </td>
    
    <td>
      Colors of the panel, tiles, labels and menus.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        base-item-size
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        50
      </code>
    </td>
    
    <td>
      Icon size at rest, in px. The dock shrinks evenly when its parent is too small.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        magnification
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        70
      </code>
    </td>
    
    <td>
      Size of the icon under the pointer, in px. Set it to <code>
        base-item-size
      </code>
      
       to turn magnifying off.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        distance
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        200
      </code>
    </td>
    
    <td>
      How far from the pointer icons still grow, in px.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        panel-height
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        68
      </code>
    </td>
    
    <td>
      Thickness of the dock bar, in px.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        gap
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        10
      </code>
    </td>
    
    <td>
      Space between icons, in px.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        roundness
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        0.5
      </code>
    </td>
    
    <td>
      Corner rounding of tiles and bar, from square (0) to circles (1).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        spring
      </code>
    </td>
    
    <td>
      <code>
        { mass?: number; stiffness?: number; damping?: number }
      </code>
    </td>
    
    <td>
      <code>
        { mass: 0.1, stiffness: 150, damping: 12 }
      </code>
    </td>
    
    <td>
      Spring the icons grow and shrink with. Low damping overshoots and wobbles.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bounce
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Icons hop when clicked, like apps launching.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        auto-hide
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Slides the dock off its edge until the pointer comes near that edge.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tiles
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Draws a rounded tile behind each icon. Turn off for bare glyphs.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        show-labels
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Shows the label of the hovered or focused icon in a tooltip.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        show-indicators
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Shows a dot next to items marked <code>
        active
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        show-badges
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Shows the badges set on items.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        badge-color
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        '#ff453a'
      </code>
    </td>
    
    <td>
      Fill color of the badges.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        accent-color
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        '#0a84ff'
      </code>
    </td>
    
    <td>
      Color of the highlighted menu row and the keyboard focus ring.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        class
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        ''
      </code>
    </td>
    
    <td>
      Extra classes for the dock panel.
    </td>
  </tr>
</tbody>
</table>

### Item shape

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        icon
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Iconify name, e.g. <code>
        lucide:house
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        label
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Tooltip text and accessible name.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onClick
      </code>
    </td>
    
    <td>
      <code>
        () => void
      </code>
    </td>
    
    <td>
      Called on click (the icon also hops).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        class
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Extra classes for the item button.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        active
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Draws the open-app dot.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        badge
      </code>
    </td>
    
    <td>
      <code>
        number | string | boolean
      </code>
    </td>
    
    <td>
      A count or text badge, or <code>
        true
      </code>
      
       for a plain dot.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        menu
      </code>
    </td>
    
    <td>
      <code>
        DockMenuItem[]
      </code>
    </td>
    
    <td>
      Context menu rows.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        separator
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Renders a divider instead of an icon.
    </td>
  </tr>
</tbody>
</table>

Menu rows (`DockMenuItem`) take `label`, `onClick`, `icon`, `checked`, `disabled`, `shortcut`, `items` (a submenu) and `separator`.

## Slots

<table>
<thead>
  <tr>
    <th>
      Slot
    </th>
    
    <th>
      Props
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        icon
      </code>
    </td>
    
    <td>
      <code>
        { item: DockItemData, index: number }
      </code>
    </td>
    
    <td>
      Custom content for each tile, e.g. app artwork.
    </td>
  </tr>
</tbody>
</table>

## Accessibility

- The dock is a `toolbar`. Arrow keys move focus between icons, `Home` and `End` jump to the ends.
- `ContextMenu`, `Shift+F10` or the arrow pointing away from the edge opens an icon's menu with the first row focused.
- In menus, arrows move the highlight, `→` opens a submenu, `←` or `Esc` goes back, and `Esc` or `Tab` closes and returns focus to the icon.
- With `prefers-reduced-motion`, icons resize without the spring, the hop is skipped and menus fade instead of popping.
- Ported from [React Bits](https://reactbits.dev/components/dock) by David Haz.