# Hook Sidebar

> A React sidebar navigation list with a dashed rail that springs down and hooks into the active item, for docs and settings.

- Type: React component (Navigation)
- Access: Free (the source is open to everyone)
- Version: 1.0.1
- Install: `npx wingo-ui@latest add hook-sidebar`
- Docs: https://wingo-ui.com/components/hook-sidebar

## Interaction

Click an item to spring the accent rail down to it. Hovering or tabbing to another row draws a second, dimmer rail that stops where the accent one ends. When the items have hrefs, the rail follows the current route on its own.

## Installation

```bash
npx wingo-ui@latest add hook-sidebar
```

The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add https://wingo-ui.com/r/hook-sidebar.json`

Files:

- `components/ui/hook-sidebar.tsx`

npm dependencies: `npm i motion`

Wingo UI dependencies (installed automatically):

- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
import { HookSidebar } from "@/components/ui/hook-sidebar"

// any item with an href makes the rail follow the current route
const display = [
  { label: "Folder", href: "/folder" },
  { label: "Code block", href: "/codeblock" },
]

const navigation = [{ label: "Gooey nav", href: "/gooeynav" }]

// one HookSidebar per group, stacked
export function Demo() {
  return (
    <div className="flex flex-col gap-5">
      <HookSidebar label="Display" items={display} />
      <HookSidebar label="Navigation" items={navigation} />
    </div>
  )
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `Array<string \| { label: string; href?: string }>` |  | Rows rendered as the vertical list. A plain string or an object with a label is a nav item, and href turns it into a link. |
| `label?` | `string` | `""` | Group title shown above the list, outside the rail. Leave it empty for a bare list. Also names the nav for screen readers. |
| `color?` | `string` | `"#FC4C01"` | Any CSS color for the active rail (hex, rgb, hsl, var). The hover rail stays neutral. |
| `dashed?` | `boolean` | `true` | Draws the rail and its corner as dashes. Set false for a solid line. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Row text size and padding: 12px (sm), 14px (md) or 16px (lg) labels. On touch screens every row is at least 44px tall. |
| `textColor?` | `string` | `"auto"` | Color of the rows that are not active, any CSS color. Auto is the foreground at 70% opacity, so it follows the light and dark theme. |
| `activeTextColor?` | `string` | `"auto"` | Color of the active row and of any row under the pointer, any CSS color. Auto is the foreground color. |
| `hoverColor?` | `string` | `"auto"` | Color of the dimmer rail drawn to the row under the pointer or focus, any CSS color. Auto is the foreground at 30% opacity. |
| `gap?` | `number` | `2` | Space between rows in pixels. The rail re-measures and springs to the new row centers. |
| `cornerRadius?` | `number` | `6` | Radius in pixels of the curve where the rail turns into the active row, and how far the rail stops short of the row's center. |
| `value?` | `number` |  | Active item index for controlled usage. When set, it wins over both the URL and internal state. Pass -1 to hide the accent rail. |
| `defaultValue?` | `number` | `0` | Initial active index. Used only when no item has an href and value is not provided. |
| `onChange?` | `(index: number) => void` |  | Called with the new index whenever an item is selected. |
| `className?` | `string` |  | Extra classes merged onto the root <nav> element. Any other <nav> attribute is passed through too. |

## Parts

### HookSidebarItem (type)

One entry of items: a plain string (a button), or { label, href? } where href renders a link that is active on its own route.

## Examples

- **Project navigation**: Controlled with value and onChange: the rail springs to the chosen section and the panel beside it follows.
- **Sizes**: sm, md and lg scale the type and the row height; on touch screens every size keeps a 44px row.
- **Stacked groups**: One sidebar per group. Pass -1 as the value of every group that does not hold the selection.
- **Solid rail**: Set dashed to false for a continuous line, and color for the accent.

## See also

- [Bounce Sidebar](https://wingo-ui.com/components/bounce-sidebar) ([Markdown](https://wingo-ui.com/components/bounce-sidebar.md))
- [Proximity Sidebar](https://wingo-ui.com/components/proximity-sidebar) ([Markdown](https://wingo-ui.com/components/proximity-sidebar.md))
- [Table Of Contents](https://wingo-ui.com/components/table-of-contents) ([Markdown](https://wingo-ui.com/components/table-of-contents.md))
- [Sidebar](https://wingo-ui.com/components/sidebar) ([Markdown](https://wingo-ui.com/components/sidebar.md))
- [Nav Tabs](https://wingo-ui.com/components/nav-tabs) ([Markdown](https://wingo-ui.com/components/nav-tabs.md))

---

Canonical: https://wingo-ui.com/components/hook-sidebar
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt