Skip to main content

Custom Sidebar Badges for Pages

Updated Apr 06, 2026 ·

Overview​

This page provides the details for adding custom badges (LAB, PROJECT, BETA, EXPLORE) to individual sidebar page links in Docusaurus v3. These badges help visually distinguish different types of content pages in the documentation sidebar.

Background​

The sidebar customization allows adding badges to both category folders and individual pages. For individual pages, badges are controlled through front matter properties rather than configuration files.

Badge descriptions:

BadgeDescription
LABIndicates lab or tutorial content
PROJECTIndicates project-based content (larger scope than labs)
BETAIndicates beta or experimental features
EXPLOREIndicates exploratory or advanced content

Implementation​

Badges are implemented through theme overrides that check for custom properties on sidebar items and render styled badge elements. The theme override for page links is located at:

src/theme/DocSidebarItem/Link/index.js

This file checks for sidebar_custom_props in the page's front matter to determine which badges to display.

For badge styling, custom CSS is added to:

src/css/custom.scss

Usage: Badges on Individual Pages​

To add badges to individual page links in the sidebar, include sidebar_custom_props in the page's front matter:

---
title: My Page Title
sidebar_custom_props:
  labs: true    # Shows LAB badge
---

You can also combine multiple badges on the same page:

sidebar_custom_props:
  labs: true
  projects: true
  beta: true

Styling​

Badges are styled with:

  • Rounded corners and padding
  • Positioned to the right of page titles
  • Responsive font sizes
  • Dark mode color variants

Additional notes:

  • Badges only appear on sidebar links, not in the page content
  • Front matter changes require a site rebuild to take effect
  • Badges work with autogenerated sidebars
  • Category badges use _category_.json files instead