# Sidebar

The list of pages beside every page, grouped by section and built from the docs collection.

The sidebar lists every page, grouped by the folder it sits in, and marks the page the reader is on. From 1024px it is a column left of the content; below that, the same list opens from the menu button in the header.

::component-preview{src="~/demos/SidebarDemo.vue"}
::

## Anatomy

The layer renders `DocsSidebar` beside every page. Its parts work on their own, so an override can reuse them.

::component-anatomy
---
parts:
  - name: DocsSidebar
    description: The sticky column. Reads the navigation and renders the parts below.
    children:
      - name: DocsSidebarNav
        required: true
        description: The pages, grouped by section.
        children:
          - name: DocsSidebarItem
            required: true
            description: One page.
      - name: DocsSidebarLinks
        description: The links set in the app config.
---
::

## Usage

`DocsSidebarNav` renders a navigation tree in the shape `queryCollectionNavigation` returns. `useDocsNavigation` reads the tree of the `docs` collection, with each page’s `badge`.

```vue
<template>
  <docs-sidebar-nav :navigation="navigation ?? []" />
</template>

<script setup lang="ts">
const { data: navigation } = await useDocsNavigation()
</script>
```

A section with pages renders as a group under its label. A page at the top level of `content/` renders without a label. Every item whose path matches the route is marked as the current one.

## Badges

A page with `badge` in its front matter shows the badge after its title in the sidebar.

```md
---
title: Table of Contents
badge: New
---
```

## Hiding the sidebar

A page that sets `sidebar: false` in its page meta takes the full width, and the header shows the menu button at every width. The landing page does this.

```vue [app/pages/changelog.vue]
<script setup lang="ts">
definePageMeta({ sidebar: false })
</script>
```

## API reference

### `DocsSidebar`

Takes no props. To change the column itself, replace it with a component of the same name in your app.

### `DocsSidebarNav`

::docs-table
---
columns:
  - label: Prop
  - label: Type
  - label: Default
rows:
  - items:
      - label: navigation
        description: The sections and pages to list, as `queryCollectionNavigation` returns them.
      - label: Array<ContentNavigationItem>
      - label: none
        plaintext: true
---
::

### `DocsSidebarLinks`

Takes no props. It lists `docs.links` from the app config, which starts with the Magic as a Service™ links. See [Configuration](/guide/configuration#app-config).