# Bounce Sidebar

> A React sidebar navigation list where a small dot hops along an arc to the active item, for docs, settings and scrollspy.

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

## Interaction

Click any item to bounce the marker over to it along a short arc. Tab moves between items and Enter or Space selects one. Heading rows are plain labels, so the dot skips past them. Drive the value from the scroll position and the marker follows the section you are reading.

## Installation

```bash
npx wingo-ui@latest add bounce-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/bounce-sidebar.json`

Files:

- `components/ui/bounce-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 { BounceSidebar } from "@/components/ui/bounce-sidebar"

const items = [
  { label: "General", heading: true },
  { label: "Home", href: "/" },
  { label: "About", href: "/about" },
]

export function Demo() {
  return <BounceSidebar items={items} defaultValue={1} dotColor="#FC4C01" />
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `Array<string \| { label: string; href?: string } \| { label: string; heading: true }>` |  | 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. Add heading: true to render a non-selectable group label the marker skips over. |
| `dotColor?` | `string` | `"#FC4C01"` | Any CSS color for the bouncing active marker (hex, rgb, hsl, var). Heading rows use it for their text too unless headingColor is set. |
| `headingColor?` | `string` | `""` | Any CSS color for the heading rows. Empty follows dotColor. |
| `dotSize?` | `number` | `6` | Diameter of the marker in pixels. It is snapped to the device pixel grid so it stays crisp at any zoom. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Text size and row padding: 12px (sm), 14px (md) or 16px (lg) labels. On touch screens every row is at least 44px tall whatever the size, and the dot re-centers on its row by itself. |
| `activeColor?` | `string` | `"auto"` | Text color of the active item, any CSS color. Auto uses the foreground color of the theme. |
| `textColor?` | `string` | `"auto"` | Text color of the other items, any CSS color. Auto is the foreground color at 70% opacity. |
| `duration?` | `number` | `0.25` | Seconds the dot takes to hop to a new item. Set it to 0 to jump without travel; reduced motion always jumps. |
| `arc?` | `number` | `14` | How far the dot bows out sideways on its hop, in pixels. Short hops are capped so the arc never loops; 0 slides in a straight line. |
| `value?` | `number` |  | Active item index for controlled usage. When set, the component won't manage its own state. Headings count toward the index. |
| `defaultValue?` | `number` | `0` | Initial active index for uncontrolled usage. Ignored when value is provided. |
| `onChange?` | `(index: number) => void` |  | Called with the new index whenever an item is selected. |
| `className?` | `string` |  | Extra classes merged onto the root <ul> element. Any other <ul> attribute is passed through too. |

## Parts

### BounceSidebarItem (type)

One row of items: a plain string, { label, href? } for a nav item (href renders a link), or { label, heading: true } for a group label the dot skips.

## Examples

- **Settings navigation**: Controlled with value and onChange: the dot hops to the section and the panel beside it swaps its content.
- **Sizes**: sm, md and lg scale the type, the row padding and the group headings together.
- **Grouped with headings**: Heading rows label each group. They are not selectable, so the dot hops straight over them.
- **Custom marker color**: Pass any CSS color to dotColor to match your brand.

## See also

- [Hook Sidebar](https://wingo-ui.com/components/hook-sidebar) ([Markdown](https://wingo-ui.com/components/hook-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/bounce-sidebar
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt