---
slug: /sidebar
---

# Sidebar

Creating a sidebar is useful to:

- Group multiple **related documents**
- **Display a sidebar** on each of those documents
- Provide **paginated navigation**, with next/previous button

To use sidebars on your Docusaurus site:

1. Define a file that exports a dictionary of [sidebar objects](#sidebar-object).
2. Pass this object into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.

```js title="docusaurus.config.js"
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // highlight-next-line
          sidebarPath: require.resolve('./sidebars.js'),
        },
      },
    ],
  ],
};
```

This section serves as an overview of miscellaneous features of the doc sidebar. In the following sections, we will more systematically introduce the following concepts:

```mdx-code-block
import DocCardList from '@theme/DocCardList';

<DocCardList />
```

## Default sidebar {#default-sidebar}

If the `sidebarPath` is unspecified, Docusaurus [automatically generates a sidebar](autogenerated.mdx) for you, by using the filesystem structure of the `docs` folder:

```js title="sidebars.js"
module.exports = {
  mySidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // generate sidebar from the docs folder (or versioned_docs/<version>)
    },
  ],
};
```

You can also define your sidebars explicitly.

## Sidebar object {#sidebar-object}

A sidebar at its crux is a hierarchy of categories, doc links, and other hyperlinks.

```ts
type Sidebar =
  // Normal syntax
  | SidebarItem[]
  // Shorthand syntax
  | {[categoryLabel: string]: SidebarItem[]};
```

For example:

```js title="sidebars.js"
module.exports = {
  mySidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        {
          type: 'doc',
          id: 'doc1',
        },
      ],
    },
    {
      type: 'category',
      label: 'Docusaurus',
      items: [
        {
          type: 'doc',
          id: 'doc2',
        },
        {
          type: 'doc',
          id: 'doc3',
        },
      ],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};
```

This is a sidebars file that exports one sidebar, called `mySidebar`. It has three top-level items: two categories and one external link. Within each category, there are a few doc links.

A sidebars file can contain [**multiple sidebar objects**](multiple-sidebars.mdx), identified by their object keys.

```ts
type SidebarsFile = {
  [sidebarID: string]: Sidebar;
};
```

## Theme configuration {#theme-configuration}

### Hideable sidebar {#hideable-sidebar}

By enabling the `themeConfig.docs.sidebar.hideable` option, you can make the entire sidebar hideable, allowing users to better focus on the content. This is especially useful when content is consumed on medium-sized screens (e.g. tablets).

```js title="docusaurus.config.js"
module.exports = {
  themeConfig: {
    // highlight-start
    docs: {
      sidebar: {
        hideable: true,
      },
    },
    // highlight-end
  },
};
```

### Auto-collapse sidebar categories {#auto-collapse-sidebar-categories}

The `themeConfig.docs.sidebar.autoCollapseCategories` option would collapse all sibling categories when expanding one category. This saves the user from having too many categories open and helps them focus on the selected section.

```js title="docusaurus.config.js"
module.exports = {
  themeConfig: {
    // highlight-start
    docs: {
      sidebar: {
        autoCollapseCategories: true,
      },
    },
    // highlight-end
  },
};
```

## Passing custom props {#passing-custom-props}

To pass in custom props to a sidebar item, add the optional `customProps` object to any of the items. This is useful to apply site customizations by swizzling React components rendering sidebar items.

```js
{
  type: 'doc',
  id: 'doc1',
  // highlight-start
  customProps: {
    badges: ['new', 'green'],
    featured: true,
  },
  // highlight-end
};
```

## Sidebar Breadcrumbs {#sidebar-breadcrumbs}

By default, breadcrumbs are rendered at the top, using the "sidebar path" of the current page.

This behavior can be disabled with plugin options:

```js title="docusaurus.config.js"
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // highlight-next-line
          breadcrumbs: false,
        },
      },
    ],
  ],
};
```

## Complex sidebars example {#complex-sidebars-example}

A real-world example from the Docusaurus site:

```mdx-code-block
import CodeBlock from '@theme/CodeBlock';

<CodeBlock language="js" title="sidebars.js">
  {require('!!raw-loader!@site/sidebars.js')
    .default
    .split('\n')
    // remove comments
    .map((line) => !['//','/*','*'].some(commentPattern => line.trim().startsWith(commentPattern)) && line)
    .filter(Boolean)
    .join('\n')}
</CodeBlock>
```