---
slug: /sidebar
---

# Sidebar

Creating a sidebar is useful to:

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

To use sidebars on your Docusaurus site:

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

```js title="docusaurus.config.js"
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // highlight-next-line
          sidebarPath: './sidebars.js',
        },
      },
    ],
  ],
};
```

:::important Node.js runtime

The sidebars file is run with Node.js. You can't use or import browsers APIs, React or JSX in it.

:::

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"
export default {
  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 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"
export default {
  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"
export default {
  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"
export default {
  themeConfig: {
    // highlight-start
    docs: {
      sidebar: {
        autoCollapseCategories: true,
      },
    },
    // highlight-end
  },
};
```

## Passing CSS classes {#passing-css-classes}

To pass CSS classes to a sidebar item, add the optional `className` attribute to any of the items. This is useful to apply visual customizations to specific sidebar items.

```js
{
  type: 'doc',
  id: 'doc1',
  // highlight-start
  className: 'sidebar-item--highlighted',
  // 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
};
```

## Passing a unique key {#passing-unique-key}

Passing a unique `key` attribute can help uniquely identify a sidebar item. Sometimes other attributes (such as `label`) are not enough to distinguish two sidebar items from each other.

```js
{
  type: 'category',
  // highlight-start
  label: 'API', // You may have multiple categories with this widespread label
  key: 'api-for-feature-1', // and now, they can be uniquely identified
  // highlight-end
};
```

:::info How is this useful?

Docusaurus only uses the `key` attribute to generate unique i18n translation keys. When a translation key conflict happens ([issue](https://github.com/facebook/docusaurus/issues/10913)), Docusaurus will tell you to apply a `key` to distinguish sidebar items.

Alternatively, you may have your own reasons for using the `key` attribute that will be passed to the respective sidebar item React components.

:::

## 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"
export default {
  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.ts')
    .default
    .split('\n')
    // remove comments
    .map((line) => !['//','/*','*'].some(commentPattern => line.trim().startsWith(commentPattern)) && line)
    .filter(Boolean)
    .join('\n')}
</CodeBlock>
```