Usage Examples

Examples

This example shows the basic filter-tabs and tab syntax.

Choose programming language: Python, C++, JavaScript
Show Python content
Show C++ content
Show JavaScript content

This is general content visible regardless of the selected filter. Use it for introductory text or instructions that apply to every tab.

This panel shows content specific to Python.

def hello_world():
    print("Hello from Python!")

This panel shows content specific to C++.

#include <iostream>

int main() {
    std::cout << "Hello from C++!" << std::endl;
    return 0;
}

This panel shows content specific to JavaScript.

function helloWorld() {
    console.log("Hello from JavaScript!");
}

Using ARIA Labels for Better Accessibility

Use :aria-label: when a short visible tab name needs more context for screen reader users.

The :aria-label: option does not change the visible tab labels or the visible legend above the tabs. It is added to each tab’s hidden radio input, so assistive technology can announce a more descriptive control name than the short label shown on screen.

In the example below, the visible legend is still generated automatically from the tab names. CLI and GUI match the built-in interface category, so the extension renders the legend as Choose interface: CLI, GUI. The (default) marker only selects the initially active tab; it is removed from the visible tab name before the legend is generated.

Choose interface: CLI, GUI
Show CLI content
Show GUI content

Choose your preferred installation method below.

Install using the command line:

python -m pip install sphinx-filter-tabs

Install from your editor or IDE package manager:

  1. Select the Python environment that builds your Sphinx project.

  2. Search PyPI packages for sphinx-filter-tabs.

  3. Install the package.

  4. Rebuild the documentation.

If your editor opens an integrated terminal, this command is equivalent:

python -m pip install sphinx-filter-tabs

Providing a Custom Legend

By default, the extension creates a visible legend from the tab names. For example, tabs named Staging and Production match the built-in environment category and would produce Choose environment: Staging, Production.

When that generated text is not the clearest label for the group, provide an explicit visible legend with the :legend: option. This is different from :aria-label:: :legend: changes the visible group label for everyone, while :aria-label: changes the accessible name of an individual hidden tab control.

Select Your Deployment Environment
Show Staging content
Show Production content

This panel shows configuration for the staging environment. It’s used for testing before release.

This panel shows configuration for the production environment. This is the live, user-facing setup.

Source Code for Custom Legend

The following RST markup was used to create the above example:

.. filter-tabs::
   :legend: Select Your Deployment Environment

   .. tab:: Staging (default)

      This panel shows configuration for the **staging** environment.
      It's used for testing before release.

   .. tab:: Production

      This panel shows configuration for the **production** environment.
      This is the live, user-facing setup.

Hiding the Visible Legend

Some pages already introduce the tab context in nearby prose or headings. In those cases, add :hide-legend: to keep the tab group visually compact while preserving the semantic <legend> for assistive technology.

Choose operating system for install commands
Show Windows content
Show macOS content
Show Linux content

Install from PowerShell:

pip install sphinx-filter-tabs

Install from Terminal:

python3 -m pip install sphinx-filter-tabs

Install from a shell:

python3 -m pip install sphinx-filter-tabs

Source Code for Hidden Legend

The following RST markup was used to create the compact tab group above:

.. filter-tabs::
   :legend: Choose operating system for install commands
   :hide-legend:

   .. tab:: Windows

      Install from PowerShell:

      .. code-block:: powershell

         pip install sphinx-filter-tabs

   .. tab:: macOS

      Install from Terminal:

      .. code-block:: bash

         python3 -m pip install sphinx-filter-tabs

   .. tab:: Linux

      Install from a shell:

      .. code-block:: bash

         python3 -m pip install sphinx-filter-tabs

Nested Tabs

You can nest filter-tabs directives to create more complex layouts. Indent the inner tab group inside a tab directive of the outer group.

Choose operating system: Windows, macOS, Linux
Show Windows content
Show macOS content
Show Linux content

Windows installation instructions. Choose the command that matches your Python launcher:

Choose programming language: py launcher, python command
Show py launcher content
Show python command content

Install with the Windows py launcher:

py -m pip install sphinx-filter-tabs

Install with the active python command:

python -m pip install sphinx-filter-tabs

macOS installation instructions:

# Using Homebrew Python
python3 -m pip install sphinx-filter-tabs

Linux installation instructions:

python3 -m pip install --user sphinx-filter-tabs

Large Tab Groups

There is no fixed 10-tab limit. The panel-visibility CSS is generated at build time and scales to the tab groups used in each build. The following example shows 12 tabs, which is realistic for a library that ships official clients for many languages.

Note

Tab groups above 15 will trigger a build warning encouraging you to consider restructuring. The generated CSS scales to the largest tab group in the build, but for truly large sets of alternatives a toctree or a comparison table is usually a better fit.

Install the client library for your language
Show Python content
Show JavaScript content
Show TypeScript content
Show Go content
Show Rust content
Show Java content
Show Kotlin content
Show C# content
Show Ruby content
Show PHP content
Show Swift content
Show Elixir content
pip install acme-client

npm install acme-client

npm install acme-client
# Type declarations are bundled; no @types package needed.

go get github.com/acme/acme-client-go

# Cargo.toml
[dependencies]
acme-client = "1.0"

<!-- pom.xml -->
<dependency>
  <groupId>com.acme</groupId>
  <artifactId>acme-client</artifactId>
  <version>1.0.0</version>
</dependency>

// build.gradle.kts
implementation("com.acme:acme-client:1.0.0")

dotnet add package Acme.Client

gem install acme-client

composer require acme/acme-client

// Package.swift
.package(url: "https://github.com/acme/acme-client-swift", from: "1.0.0")

# mix.exs
{:acme_client, "~> 1.0"}