|
| 1 | +--- |
| 2 | +title: Sidebar Accordion |
| 3 | +--- |
| 4 | + |
| 5 | +# Sidebar Accordion ((tag|VitePress plugin|blue)) |
| 6 | + |
| 7 | +[[readingTime]] |
| 8 | + |
| 9 | +[](https://github.com/binarynoir/vitepress-sidebar-accordion) [](https://www.npmjs.com/package/@binarynoir/vitepress-sidebar-accordion) [](https://github.com/binarynoir/vitepress-sidebar-accordion/actions/workflows/ci.yml) [](https://github.com/binarynoir/vitepress-sidebar-accordion/blob/main/LICENSE) |
| 10 | + |
| 11 | +`@binarynoir/vitepress-sidebar-accordion` turns the default theme's sidebar into an accordion: one open group per level. Opening a group closes the groups beside it, and after navigating, only the branch holding the current page stays open. |
| 12 | + |
| 13 | +That is how the VuePress sidebar behaved, so a site moving to VitePress keeps the same feel. On a large docs site it also keeps the sidebar short. |
| 14 | + |
| 15 | +## See it live |
| 16 | + |
| 17 | +This site's sidebar is the demo. Try it in the sidebar beside this page: |
| 18 | + |
| 19 | +1. Open **Richer pages**. **Navigation from your folders**, the group this page is in, closes. |
| 20 | +2. Inside **Richer pages**, open **Markdown Tags**, then **Glossary Tooltips**. Markdown Tags closes; Richer pages stays open. |
| 21 | +3. Follow any link in the sidebar. Only the new page's branch is left open. |
| 22 | +4. Come back to this page and close **Navigation from your folders**, then follow the [Auto Navbar](/plugins/auto-navbar) link. The group opens again, because the page you landed on is in it. |
| 23 | + |
| 24 | +| Reader does | Default VitePress | With the accordion | |
| 25 | +| ---------------------------------- | ------------------------------------- | ---------------------------------------------- | |
| 26 | +| Opens a group | Every group they opened stays open | Open groups at the same level close | |
| 27 | +| Opens a group inside another group | Its siblings stay open | Only its siblings close; the parent stays open | |
| 28 | +| Follows a link to another page | Groups opened along the way stay open | Only the new page's branch is left open | |
| 29 | +| Closes the current page's group | It stays closed on the next page | It opens again on the next page in that branch | |
| 30 | + |
| 31 | +## Install |
| 32 | + |
| 33 | +```sh |
| 34 | +npm install --save-dev @binarynoir/vitepress-sidebar-accordion |
| 35 | +``` |
| 36 | + |
| 37 | +## Use |
| 38 | + |
| 39 | +**1. Theme.** Call `useSidebarAccordion()` from your theme's `setup`: |
| 40 | + |
| 41 | +```ts |
| 42 | +// .vitepress/theme/index.ts |
| 43 | +import DefaultTheme from 'vitepress/theme'; |
| 44 | +import { useSidebarAccordion } from '@binarynoir/vitepress-sidebar-accordion'; |
| 45 | + |
| 46 | +export default { |
| 47 | + extends: DefaultTheme, |
| 48 | + setup() { |
| 49 | + useSidebarAccordion(); |
| 50 | + }, |
| 51 | +}; |
| 52 | +``` |
| 53 | + |
| 54 | +**2. Sidebar.** Give each group a `collapsed` value. VitePress only draws the caret that opens and closes a group when `collapsed` is set, and the accordion works through that caret. `collapsed: true` starts the groups closed; VitePress opens the current page's branch on load. |
| 55 | + |
| 56 | +```ts |
| 57 | +// .vitepress/config.mts |
| 58 | +export default defineConfig({ |
| 59 | + themeConfig: { |
| 60 | + sidebar: [ |
| 61 | + { |
| 62 | + text: 'Guide', |
| 63 | + collapsed: true, |
| 64 | + items: [ |
| 65 | + { text: 'Introduction', link: '/guide/' }, |
| 66 | + { |
| 67 | + text: 'Advanced', |
| 68 | + collapsed: true, |
| 69 | + items: [{ text: 'Plugins', link: '/guide/plugins' }], |
| 70 | + }, |
| 71 | + ], |
| 72 | + }, |
| 73 | + { text: 'Reference', collapsed: true, items: [{ text: 'API', link: '/reference/api' }] }, |
| 74 | + ], |
| 75 | + }, |
| 76 | +}); |
| 77 | +``` |
| 78 | + |
| 79 | +Groups without `collapsed` are always open, and the accordion leaves them alone. |
| 80 | + |
| 81 | +### With Auto Sidebar |
| 82 | + |
| 83 | +[Auto Sidebar](/plugins/auto-sidebar/) sets `collapsed` on every group it generates through its `collapsed` option. This site does exactly that: |
| 84 | + |
| 85 | +```ts |
| 86 | +sidebar: generateSidebar(docsRoot, { |
| 87 | + collapsed: true, |
| 88 | +}), |
| 89 | +``` |
| 90 | + |
| 91 | +## How it works |
| 92 | + |
| 93 | +VitePress keeps each group's open state inside its sidebar item component and offers no API to change it. So the accordion clicks the group's caret, the same button a reader would press, and VitePress's own state stays in sync. |
| 94 | + |
| 95 | +- A click the reader makes on a group header or caret is caught in the capture phase, because the caret stops its click from bubbling. Once Vue has updated, if the group is now open, the open groups beside it, and any open groups inside those, are closed, innermost first. |
| 96 | +- Clicks the accordion makes itself are not trusted events, so they never start another round. |
| 97 | +- After each route change, once VitePress has opened the new page's branch, the accordion opens any group in that branch the reader had closed and closes the branches beside it. |
| 98 | +- During the server-side build, `useSidebarAccordion()` does nothing. |
| 99 | + |
| 100 | +It reads VitePress's own class names (`.VPSidebarItem`, `.collapsible`, `.collapsed`, `.has-active`, `.is-active`, `.caret`), so it works with the default theme's sidebar, or a custom one that renders the same markup. |
| 101 | + |
| 102 | +## Exports |
| 103 | + |
| 104 | +`useSidebarAccordion()` is all most sites need. The pieces it is built from are exported too, for a theme that wants to wire them up its own way: |
| 105 | + |
| 106 | +| Export | What it does | |
| 107 | +| ---------------------------- | ---------------------------------------------------------------------- | |
| 108 | +| `handleSidebarClick(event)` | The capture-phase click handler `useSidebarAccordion` adds. | |
| 109 | +| `keepActiveBranchOnly(root)` | Opens the current page's branch and closes the rest. | |
| 110 | +| `closeOpenSiblings(item)` | Closes the open groups beside `item`, and any open groups inside them. | |
| 111 | +| `getSiblingItems(item)` | The sidebar items at the same level as `item`. | |
| 112 | +| `toggleGroup(group)` | Opens or closes a group by clicking its caret. | |
| 113 | +| `isOpenGroup(item)` | Whether `item` is a group that is currently open. | |
| 114 | +| `GROUP_SELECTOR` and friends | The CSS selectors above, for matching the same elements in theme code. | |
| 115 | + |
| 116 | +## Limits |
| 117 | + |
| 118 | +- **Default theme markup only.** A theme that replaces the sidebar with different markup needs its own accordion. |
| 119 | +- **Groups need `collapsed`.** A group without it has no caret, and stays open. |
| 120 | + |
| 121 | +[Source and full README on GitHub](https://github.com/binarynoir/vitepress-sidebar-accordion) |
0 commit comments