Sidebar

The sidebar is a vertical navigation component fixed to the left. They can be used to display branding, navigation links, forms, etc.

Overview #

The sidebar is a specialized offcanvas which can be created by adding .sidebar to a responsive offcanvas (.offcanvas-{breakpoint}). You can find detailed explanations about how it works after this example. Try resizing your browser—the sidebar will only be visible on md screens and up. Below this, it is just a regular offcanvas that can be opened with the toggle button.

<body class="ps-md-sbwidth">
  <!-- Sidebar -->
  <nav class="sidebar offcanvas-start offcanvas-md" tabindex="-1" id="sidebar-example">
    <div class="offcanvas-header border-bottom border-secondary border-opacity-25">
      <a class="sidebar-brand" href="#">
        <img src="..." alt="Logo" width="24" height="24" class="d-inline-block align-text-top">
        Builder
      </a>
      <button type="button" class="btn-close d-md-none" data-bs-dismiss="offcanvas" aria-label="Close" data-bs-target="#sidebar-example"></button>
    </div>
    <div class="offcanvas-body">
      <div class="mt-2 mb-3">
        <input type="text" class="form-control" placeholder="Search">
      </div>
      <ul class="sidebar-nav">
        <li>
          <h6 class="sidebar-header">Getting started</h6>
        </li>
        <li><hr class="sidebar-divider"></li>
        <li class="nav-item">
          <a class="nav-link active" href="#" aria-current="page">Installation</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">CLI commands</a>
        </li>
        <li class="mt-3">
          <h6 class="sidebar-header">Components</h6>
        </li>
        <li><hr class="sidebar-divider"></li>
        <li class="nav-item">
          <a class="nav-link" href="#">File explorer</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">Spreadsheet</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">Maps</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">Messenger</a>
        </li>
      </ul>
    </div>
  </nav>

  ...

  <!-- Sidebar toggle -->
  <button type="button" data-bs-toggle="offcanvas" data-bs-target="#sidebar-example" class="btn btn-secondary d-md-none">
    <i class="fa-light fa-sidebar me-1"></i> Sidebar
  </button>

  ...
</body>

<body class="ps-md-sbwidth">
  <!-- Sidebar -->
  <nav class="sidebar offcanvas-start offcanvas-md" tabindex="-1" id="sidebar-example">
    <div class="offcanvas-header">
      <a class="sidebar-brand" href="#">
        <img src="..." alt="Logo" width="24" height="24" class="d-inline-block align-text-top">
        Builder
      </a>
      <button type="button" class="btn-close d-md-none" data-bs-dismiss="offcanvas" aria-label="Close" data-bs-target="#sidebar-example"></button>
    </div>
    <div class="offcanvas-body">
      <div class="mt-2 mb-3">
        <input type="text" class="form-control" placeholder="Search">
      </div>
      <ul class="sidebar-nav">
        <li>
          <h6 class="sidebar-header">Getting started</h6>
        </li>
        <li><hr class="sidebar-divider"></li>
        <li class="nav-item">
          <a class="nav-link active" href="#" aria-current="page">Installation</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">CLI commands</a>
        </li>
        <li class="mt-3">
          <h6 class="sidebar-header">Components</h6>
        </li>
        <li><hr class="sidebar-divider"></li>
        <li class="nav-item">
          <a class="nav-link" href="#">File explorer</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">Spreadsheet</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">Maps</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">Messenger</a>
        </li>
      </ul>
    </div>
  </nav>

  ...

  <!-- Sidebar toggle -->
  <button type="button" data-bs-toggle="offcanvas" data-bs-target="#sidebar-example" class="btn btn-secondary d-md-none">
    <i class="fa-light fa-sidebar me-1"></i> Sidebar
  </button>

  ...
</body>

Please note, the icon being used is taken from the Font Awesome icon library (opens in new tab).

Warning

Heads up! The .sidebar uses the !important keyword to set its background-color property (in order to effectively override the offcanvas style). Therefore, background utilities will not work here. To change the background-color, please set the --bs-sidebar-bg variable using inline CSS.

Overview How it works #

Here's how everything works together to create a functional sidebar:

As mentioned above, the sidebar is a specialized offcanvas. More specifically, it is a specialized responsive offcanvas (.offcanvas-{breakpoint}). This means that for the given {breakpoint} and up, the sidebar is a vertical navigation component fixed to the left. Below this, it is a regular offcanvas that can be toggled with the click of a button.
Sidebars will only work properly with .offcanvas-start. No other type is supported.
You need to add the .ps-{breakpoint}-sbwidth class to the sidebar container, where {breakpoint} is the same as the one in .offcanvas-{breakpoint} (in the sidebar). This sets padding-left equal to the width of the sidebar, but only for the breakpoint and up where the sidebar is active. Usually this container is going to be the <body> as shown in the example above.
A close button is generally recommended inside the sidebar/offcanvas. This can be responsively hidden (as shown in the example above) using display utilities. This close button should explicitly target the sidebar's id via the data-bs-target attribute.
You can use the optional built-in sub-components such as .sidebar-brand, .sidebar-nav, and so on, to populate your sidebar. You can also just use any other components that suit your needs.
The width of the sidebar (and the container padding) can be changed by changing the --bs-sidebar-width CSS variable defined at the :root {...} level.

Generally speaking, due to the heavy reliance on the offcanvas component, it is recommended that you give that documentation page a thorough read before using the sidebar.

Information

Please note, when the .sidebar component is a direct child of the <body>, we automatically add padding-left to the <body> (equal to the sidebar's width) via the :has() CSS selector. However, this is not supported in some browsers yet, therefore, it is always safer to manually add the .ps-{breakpoint}-sbwidth class to make sure your content does not overlap with the sidebar.

Up next

Spinners

Help us grow

Our main goal is to make Halfmoon the go-to framework for building websites, dashboards and tools. If you believe in our mission, consider becoming a sponsor and help us grow.

You can email us directly if you have any queries. We are always happy to answer.