Dropdowns

Dropdowns create a compact selector near the top of the sidebar. Use them for related sections that users should be able to jump into without making every section a permanent top-level tab.

Good examples include Components, Programs, Examples, Resources, or Use cases.

​

When to use dropdowns

Use dropdowns when:

• the content is useful, but not important enough to be a top-level tab
• users may want to jump into a secondary section from anywhere
• the section has its own route prefix, such as /components/*
• keeping the sidebar focused matters more than keeping every group visible

Use tabs instead when the section is a primary product area like Guides or API Reference.

​

How dropdowns work

DocsAlot dropdowns are prefix-based. Each dropdown points to a route prefix with href.

For example, a dropdown with "href": "components" points users to /components and activates sidebar groups whose pages live under /components/*.

​

Basic example

{
  "navigation": {
    "dropdowns": [
      {
        "dropdown": "Components",
        "href": "components",
        "icon": "grid-2",
        "iconType": "regular"
      },
      {
        "dropdown": "Programs",
        "href": "partners",
        "icon": "handshake",
        "iconType": "regular"
      }
    ],
    "groups": [
      {
        "group": "Getting Started",
        "pages": ["quickstart"]
      },
      {
        "group": "Organization Components",
        "pages": [
          "components/accordion",
          "components/card",
          "components/tabs"
        ]
      },
      {
        "group": "Programs",
        "pages": [
          "partners/index",
          "partners/affiliates"
        ]
      }
    ]
  }
}

With this setup:

• The sidebar shows a dropdown selector for Components and Programs.
• Selecting Components routes to /components.
• Pages under components/* are shown in that navigation context.

​

Dropdown properties

Each dropdown supports:

• dropdown: the label shown in the selector
• href: the route prefix or external URL
• icon: a Font Awesome icon name
• iconType: regular, solid, duotone, brands, light, thin, or sharp-solid
• hidden: hides the dropdown without deleting the config

​

Use dropdowns with languages

If your site uses language navigation, keep dropdowns at the top of the navigation object and put translated pages inside each language.

{
  "navigation": {
    "dropdowns": [
      {
        "dropdown": "Components",
        "href": "components",
        "icon": "grid-2"
      }
    ],
    "languages": [
      {
        "language": "en",
        "default": true,
        "groups": [
          {
            "group": "Components",
            "pages": ["components/accordion", "components/card"]
          }
        ]
      },
      {
        "language": "fr",
        "groups": [
          {
            "group": "Composants",
            "pages": ["fr/components/accordion", "fr/components/card"]
          }
        ]
      }
    ]
  }
}

​

Agent-first setup

If you use the DocsAlot CLI with Claude, Codex, or another coding agent, ask it to reorganize the navigation and preview the result.

use docsalot cli to move Components and Programs into navigation dropdowns, update layout.json, and run a preview locally

Then publish after review:

use docsalot cli to push this documentation to remote and publish

​

Common mistakes

• Do not use a leading slash in internal href values. Use "components", not "/components".
• Do not point a dropdown to a folder that has no visible pages.
• Do not use dropdowns as a replacement for every sidebar group. They are best for secondary lanes.
• Keep dropdown prefixes distinct from tab prefixes when possible.