0
# Sidebar Components
1

2
Sidebar navigation system providing hierarchical document navigation with collapsible groups, active link highlighting, and mobile responsive behavior.
3

4
## Capabilities
5

6
### Sidebar Component
7

8
Main sidebar container component that displays navigation structure and handles responsive behavior.
9

10
```javascript { .api }
11
/**
12
 * Main sidebar navigation Vue component
13
 * Available as @theme/components/Sidebar.vue
14
 */
15
const Sidebar: VueComponent = {
16
  name: 'Sidebar',
17
  props: {
18
    items: {
19
      type: Array,
20
      required: true
21
    }
22
  },
23
  slots: {
24
    top: {},    // Top sidebar slot
25
    bottom: {}  // Bottom sidebar slot  
26
  },
27
  emits: ['toggle-sidebar']
28
};
29
```
30

31
**Props:**
32

33
- `items` (Array, required): Array of sidebar navigation items
34

35
**Slots:**
36

37
- `top`: Content displayed at top of sidebar
38
- `bottom`: Content displayed at bottom of sidebar
39

40
**Usage:**
41

42
```vue
43
<template>
44
  <Sidebar 
45
    :items="sidebarItems" 
46
    @toggle-sidebar="handleToggle"
47
  >
48
    <template #top>
49
      <div>Custom top content</div>
50
    </template>
51
    <template #bottom>
52
      <div>Custom bottom content</div>
53
    </template>
54
  </Sidebar>
55
</template>
56
```
57

58
### SidebarLinks Component
59

60
Container component that renders the hierarchical list of sidebar navigation links.
61

62
```javascript { .api }
63
/**
64
 * Sidebar navigation links container Vue component
65
 * Available as @theme/components/SidebarLinks.vue
66
 */
67
const SidebarLinks: VueComponent = {
68
  name: 'SidebarLinks',
69
  props: {
70
    items: {
71
      type: Array,
72
      default: () => []
73
    },
74
    depth: {
75
      type: Number,
76
      default: 0
77
    },
78
    maxDepth: {
79
      type: Number,
80
      default: 1
81
    },
82
    collapsable: {
83
      type: Boolean,
84
      default: true
85
    }
86
  }
87
};
88
```
89

90
**Props:**
91

92
- `items` (Array): Sidebar navigation items
93
- `depth` (Number, default: 0): Current nesting depth
94
- `maxDepth` (Number, default: 1): Maximum depth to render
95
- `collapsable` (Boolean, default: true): Whether groups can be collapsed
96

97
### SidebarLink Component
98

99
Individual sidebar link component with active state handling and nested children support.
100

101
```javascript { .api }
102
/**
103
 * Individual sidebar link Vue component
104
 * Available as @theme/components/SidebarLink.vue
105
 */
106
const SidebarLink: VueComponent = {
107
  name: 'SidebarLink',
108
  props: {
109
    item: {
110
      type: Object,
111
      required: true
112
    },
113
    sidebarDepth: {
114
      type: Number,
115
      default: 1
116
    }
117
  },
118
  computed: {
119
    link: String,
120
    isActive: Boolean,
121
    displayAllHeaders: Boolean,
122
    unwrappedHeaders: Array,
123
    shouldShowChildren: Boolean
124
  }
125
};
126
```
127

128
**Props:**
129

130
- `item` (Object, required): Sidebar item configuration  
131
- `sidebarDepth` (Number, default: 1): Depth of sidebar nesting to show
132

133
### SidebarGroup Component
134

135
Collapsible group component for organizing related sidebar items.
136

137
```javascript { .api }
138
/**
139
 * Collapsible sidebar group Vue component
140
 * Available as @theme/components/SidebarGroup.vue
141
 */
142
const SidebarGroup: VueComponent = {
143
  name: 'SidebarGroup',
144
  props: {
145
    item: {
146
      type: Object,
147
      required: true
148
    },
149
    open: {
150
      type: Boolean,
151
      default: false
152
    },
153
    collapsable: {
154
      type: Boolean,
155
      default: false
156
    },
157
    depth: {
158
      type: Number,
159
      default: 0
160
    }
161
  },
162
  data() {
163
    return {
164
      isOpen: Boolean
165
    };
166
  },
167
  computed: {
168
    isActive: Boolean,
169
    groupClasses: Array
170
  }
171
};
172
```
173

174
**Props:**
175

176
- `item` (Object, required): Group configuration object
177
- `open` (Boolean, default: false): Whether group is initially open
178
- `collapsable` (Boolean, default: false): Whether group can be collapsed
179
- `depth` (Number, default: 0): Nesting depth of the group
180

181
### SidebarButton Component
182

183
Mobile sidebar toggle button component for responsive navigation.
184

185
```javascript { .api }
186
/**
187
 * Mobile sidebar toggle button Vue component
188
 * Available as @theme/components/SidebarButton.vue
189
 */
190
const SidebarButton: VueComponent = {
191
  name: 'SidebarButton',
192
  emits: ['toggle-sidebar']
193
};
194
```
195

196
## Sidebar Configuration
197

198
Configure sidebar through themeConfig:
199

200
```javascript
201
// VuePress config
202
module.exports = {
203
  themeConfig: {
204
    sidebar: {
205
      // Sidebar for /guide/ section
206
      '/guide/': [
207
        {
208
          title: 'Getting Started',
209
          collapsable: false,
210
          children: [
211
            '/guide/',
212
            '/guide/installation',
213
            '/guide/basic-config'
214
          ]
215
        },
216
        {
217
          title: 'Advanced',
218
          collapsable: true,
219
          children: [
220
            '/guide/custom-themes',
221
            '/guide/plugins'
222
          ]
223
        }
224
      ],
225
      
226
      // Auto-generated sidebar from headers
227
      '/api/': 'auto',
228
      
229
      // Fallback sidebar
230
      '/': [
231
        '',
232
        'getting-started',
233
        'advanced'
234
      ]
235
    },
236
    
237
    // Sidebar depth (0 = only h1, 1 = h1+h2, etc.)
238
    sidebarDepth: 2,
239
    
240
    // Display all headers or just active page headers
241
    displayAllHeaders: false,
242
    
243
    // Active header links
244
    activeHeaderLinks: true
245
  }
246
}
247
```
248

249
## Sidebar Item Types
250

251
```javascript { .api }
252
interface SidebarItem {
253
  /** Item type */
254
  type?: 'group' | 'page' | 'external' | 'auto';
255
  /** Display title */
256
  title?: string;
257
  /** Link path */
258
  path?: string;
259
  /** Child items */
260
  children?: SidebarItem[];
261
  /** Whether group is collapsable */
262
  collapsable?: boolean;
263
  /** Sidebar depth for this item */
264
  sidebarDepth?: number;
265
  /** Initial open group index */
266
  initialOpenGroupIndex?: number;
267
}
268

269
// Shorthand formats
270
type SidebarConfig = 
271
  | SidebarItem[]
272
  | { [path: string]: SidebarItem[] | 'auto' }
273
  | 'auto';
274
```
275

276
**Usage Examples:**
277

278
```javascript
279
// Simple array of paths
280
sidebar: [
281
  '/',
282
  '/guide/',
283
  '/api/'
284
]
285

286
// Array with titles
287
sidebar: [
288
  ['/', 'Home'],
289
  ['/guide/', 'Guide'],
290
  ['/api/', 'API Reference']
291
]
292

293
// Group configuration
294
sidebar: [
295
  {
296
    title: 'User Guide',
297
    collapsable: false,
298
    sidebarDepth: 1,
299
    children: [
300
      '/',
301
      '/guide/'
302
    ]
303
  }
304
]
305

306
// Path-specific sidebars
307
sidebar: {
308
  '/guide/': [
309
    {
310
      title: 'Guide',
311
      children: ['/guide/', '/guide/installation']
312
    }
313
  ],
314
  '/api/': 'auto'
315
}
316
```
317

318
## Auto Sidebar Generation
319

320
When `sidebar: 'auto'` is configured, the theme automatically generates sidebar from page headers:
321

322
- Creates groups from h2 headers
323
- Nests h3+ headers under h2 parents
324
- Includes anchor links for easy navigation
325
- Respects `sidebarDepth` configuration