# Badges, Buttons & Icons {octicon}`rocket`

(badges)=

## Badges

Inline badges can be used as a labelling component.
Badges are available in each semantic color, with filled and outline variants:

- {bdg}`plain badge`
- {bdg-primary}`primary`, {bdg-primary-line}`primary-line`
- {bdg-secondary}`secondary`, {bdg-secondary-line}`secondary-line`
- {bdg-success}`success`, {bdg-success-line}`success-line`
- {bdg-info}`info`, {bdg-info-line}`info-line`
- {bdg-warning}`warning`, {bdg-warning-line}`warning-line`
- {bdg-danger}`danger`, {bdg-danger-line}`danger-line`
- {bdg-light}`light`, {bdg-light-line}`light-line`
- {bdg-muted}`muted`, {bdg-muted-line}`muted-line`
- {bdg-dark}`dark`, {bdg-dark-line}`dark-line`
- {bdg-white}`white`, {bdg-white-line}`white-line`
- {bdg-black}`black`, {bdg-black-line}`black-line`

`````{dropdown-syntax}

````{tab-set-code}
```{literalinclude} ./snippets/myst/badge-basic.txt
:language: markdown
```
```{literalinclude} ./snippets/rst/badge-basic.txt
:language: rst
```
````
`````

`bdg-link-` and `bdg-ref-` variants are also available for use with links and references.
The syntax is the same as for the `ref` role.

{bdg-link-primary}`https://example.com`

{bdg-link-primary-line}`explicit title <https://example.com>`

{bdg-ref-primary}`badges`

`````{dropdown-syntax}

````{tab-set-code}
```{literalinclude} ./snippets/myst/badge-link.txt
:language: markdown
```
```{literalinclude} ./snippets/rst/badge-link.txt
:language: rst
```
````
`````

### Badge tooltips

Any badge can be given a tooltip (shown on hover, via the HTML `title`
attribute) by appending a `; tooltip` suffix to its text.
This works for every badge family:

{bdg-primary}`stable ; A released, supported version`
{bdg-link-info}`docs <https://example.com> ; Opens the documentation`
{bdg-ref-primary}`badges <badges> ; Jump to the badges section`

````{tab-set-code}
```markdown
{bdg-primary}`stable ; A released, supported version`
{bdg-link-info}`docs <https://example.com> ; Opens the documentation`
{bdg-ref-primary}`badges <badges> ; Jump to the badges section`
```
```rst
:bdg-primary:`stable ; A released, supported version`
:bdg-link-info:`docs <https://example.com> ; Opens the documentation`
:bdg-ref-primary:`badges <badges> ; Jump to the badges section`
```
````

The tooltip is the text after the **last** unescaped semicolon; both the badge
text and the tooltip are stripped of surrounding whitespace.
To include a literal semicolon in the badge text, escape it as `\;`
(for example `` {bdg}`step 1\; step 2` ``); a trailing bare `;` (with nothing
after it) is not treated as a tooltip and is kept in the badge text.

Because semicolons are valid in URLs and reference targets, the link and
reference badges (`bdg-link-*`, `bdg-ref-*`) only recognise the tooltip suffix
after the explicit `text <target>` form -- a bare target such as
`` {bdg-link-primary}`https://example.com/a;b` `` is never split. To add a
tooltip to a link/ref badge, use the explicit form:
`` {bdg-link-primary}`docs <https://example.com> ; Opens the docs` ``.
A `bdg-ref` tooltip overrides the reference's automatic title.

```{warning}
`title` tooltips are **not** accessible to keyboard or touch users, and are
not surfaced by all screen readers. Do not put essential information in a
tooltip alone -- keep it in the visible badge text (or nearby prose) as well.
```

(sd-badge-tooltip-option)=

#### The `tooltip` role option

When the same badge recurs, such as a status label whose colour and tooltip never change,
its tooltip can be given once rather than in every use.
Every badge role accepts a `tooltip` role option, which is the badge's tooltip
when its text has no `; tooltip` suffix (a suffix still overrides it).
In reStructuredText, set it with the `role` directive, which defines a new role based on a badge role
for the document it appears in:

```rst
.. role:: bdg-stable(bdg-success)
   :tooltip: A released, supported version

:bdg-stable:`v2.1` :bdg-stable:`v2.2 ; Long-term support release`
```

```{eval-rst}
.. role:: bdg-stable(bdg-success)
   :tooltip: A released, supported version

:bdg-stable:`v2.1` :bdg-stable:`v2.2 ; Long-term support release`
```

To use such a role in every reStructuredText document,
put the `role` directive in [`rst_prolog`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog)
in your `conf.py`, which is read at the start of each reStructuredText document
(Markdown documents parsed by MyST do not read it):

```python
rst_prolog = """
.. role:: bdg-stable(bdg-success)
   :tooltip: A released, supported version
"""
```

Defining the role in only one document is not enough for the others:
a document that uses a role defined elsewhere can fail with an "Unknown interpreted text role" error,
for example in an incremental or parallel build.

The option also applies to the bare `<target>` form of the link and reference badges,
where the `; tooltip` suffix is not recognised.

For extension authors: the badge roles follow the docutils convention for role functions.
Their option specification is the role's `options` attribute (`{"tooltip": ...}`;
docutils also adds `class` when the role is registered, which badges accept and ignore),
and the option is read from the `options` dictionary passed to each call,
so an extension that presets a badge role passes `options={"tooltip": "..."}`.

:::{tip}
Role presets in the project configuration are planned for the
[sphinx-ub-directives](https://sphinx-ub-directives.readthedocs.io) package,
from the [sphinx-needs](https://github.com/useblocks/sphinx-needs) project,
whose directive presets already accept sphinx-design directives as a base
and also work in [ubCode](https://ubcode.useblocks.com/).
Until then, use `rst_prolog` as above.
:::

See [Bootstrap badges](https://getbootstrap.com/docs/5.0/components/badge/) for more information, and related [Material Design chips](https://material.io/components/chip).

(buttons)=

## Buttons

Buttons in Sphinx Design are actually links:

- Links that can be styled to look like
  [Bootstrap buttons](https://getbootstrap.com/docs/5.0/components/buttons/)
- Links that are either external (`button-link`) or internal (`button-ref`)

Most of the time, you should create links using the link syntax for the language
you've chosen:

- [Markdown/MyST links and cross-references](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#examples)
- [rST links and cross-references](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks)

Sometimes, though, you may want to call attention to a particular link or set of
links, or set them apart visually from other links on the site.

:::{admonition} Note on accessibility

Despite the name, `button-link` and `button-ref` do **not** convert to
`<button>` tags in HTML. They are output as `<a>` tags and use CSS to achieve
the button look. This has important accessibility implications. For example,
assistive tech will include Sphinx Design "buttons" when asked to present a list
of all the links on the page.
:::

```{button-link} https://example.com
```

```{button-link} https://example.com
Button text
```

```{button-link} https://example.com
:color: primary
:shadow:
```

```{button-link} https://example.com
:color: primary
:outline:
```

```{button-link} https://example.com
:color: secondary
:expand:
```

```{button-ref} buttons
:color: info
```

```{button-ref} buttons
:color: info

Reference Button text
```

`````{dropdown-syntax}

````{tab-set-code}
```{literalinclude} ./snippets/myst/button-link.txt
:language: markdown
```
```{literalinclude} ./snippets/rst/button-link.txt
:language: rst
```
````
`````

The content of a `button-ref` supports rich inline formatting (such as emphasis
and icons), which is rendered in the button, just as it is for `button-link`:

```{button-ref} buttons
:ref-type: ref
:color: primary

**Bold text**
```

To break the text of a button over several lines, write it as a line block in
reStructuredText (one `|` per line), or end each line but the last with a
backslash (`\`, a hard line break) in MyST Markdown.
The MyST hard line break only breaks the line in HTML and LaTeX output:
other builders join the lines (text) or print the raw break markup (texinfo),
and the gettext message contains that markup too, so translated projects should
use the reStructuredText line block (in MyST, inside an `eval-rst` block):

```{eval-rst}
.. button-link:: https://example.com
    :color: primary

    | Multi-line
    | button text
```

````{tab-set-code}
```markdown
:::{button-link} https://example.com
:color: primary

Multi-line\
button text
:::
```
```rst
.. button-link:: https://example.com
    :color: primary

    | Multi-line
    | button text
```
````

In reStructuredText, a one-line label that starts with `| ` (or is a bare `|`) is read
as a one-line line block, whose leading bar is not shown, so write a literal leading
bar as `\|`.

Reference targets may also contain spaces, for example the labels that
`sphinx.ext.autosectionlabel` generates from section titles.

When using [myst-parser](https://myst-parser.readthedocs.io/), you can also set
`ref-type` to `myst` to resolve Markdown-style references.

Use the `click-parent` option to make the button's parent container also clickable.

:::{card} Card with an expanded button

```{button-link} https://example.com
:color: info
:expand:
:click-parent:
```

:::

Use the `new-tab` option to open the button's link in a new browser tab.
Since this changes what the reader expects a link to do,
say so in the button text:

```{button-link} https://example.com
:color: primary
:new-tab:

example.com (opens in a new tab)
```

````{tab-set-code}
```markdown
:::{button-link} https://example.com
:color: primary
:new-tab:

example.com (opens in a new tab)
:::
```
```rst
.. button-link:: https://example.com
    :color: primary
    :new-tab:

    example.com (opens in a new tab)
```
````

### `button-link` and `button-ref` options

ref-type (`button-ref` only)
: Type of reference to use; `any` (default), `ref`, `doc`, or `myst`

color
: Set the color of the button (background and font).
  One of the semantic color names: `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark`, `muted`.

outline
: Outline color variant

align
: Align the button on the page; `left`, `right`, `center` or `justify`

expand
: Expand to fit parent width

click-parent
: Make parent container also clickable

new-tab
: Open the link in a new browser tab (`target="_blank"`, `rel="noreferrer noopener"`).
  Works for both `button-link` and `button-ref`.
  Sphinx renders the `rel` attribute only from version 7.4;
  browsers already treat `target="_blank"` links as `noopener`.
  It affects only HTML-based output (HTML, EPUB); other formats ignore it.

tooltip
: Add tooltip on hover

shadow
: Add shadow CSS

class
: Additional CSS classes

(icons)=

## Inline Icons

Inline icon roles are available for the [GitHub octicon](https://primer.style/octicons/), [Google Material Design Icons](https://github.com/google/material-design-icons), or [FontAwesome](https://fontawesome.com/icons?d=gallery&m=free) libraries.

Octicon icons and Material icons are added as SVG's directly into the page with the `octicon` and `material-<flavor>` roles. See below for the different flavors of Material Design Icons.

By default the icon will be of height `1em` (i.e. the height of the font).
A specific height can be set after a semi-colon (`;`) with units of either `px`, `em` or `rem`.
Additional CSS classes can also be added to the SVG after a second semi-colon (`;`) delimiter.

Icon roles can be used within section titles, and the icon is preserved when the
title is referenced from a `toctree` (whilst no longer leaking its SVG markup
into plain-text contexts such as the search index).

:::{note}
Icon roles cannot be used inside a `toctree` *entry title*
(the `Title <target>` form written directly in the `toctree` directive),
because Sphinx parses those titles as plain text, so roles are never processed.
To show an icon next to a page's toctree entry, place the icon role in that
page's own top-level heading instead, and reference the page without an explicit
title.
:::

### Octicon Icons

A coloured icon: {octicon}`report;1em;sd-text-info`, some more text.

````{tab-set-code}
```{literalinclude} ./snippets/myst/icon-octicon.txt
:language: markdown
```
```{literalinclude} ./snippets/rst/icon-octicon.txt
:language: rst
```
````

````{dropdown} All Octicons
:open:

```{_all-octicon}
```
````

### Material Design Icons

Material Design icons come as several flavors. Each flavor represents a different role used in sphinx-design. These flavors are:

- `material-regular`
- `material-outlined`
- `material-round`
- `material-sharp`
- `material-twotone`

Not all icons are available for each flavor, but most are. Instead of displaying the 10660+ icons here, you are encouraged to browse the available icons from the [Material Design Icons' showcase](https://fonts.google.com/icons) hosted by Google.

- A regular icon: {material-regular}`data_exploration;2em`, some more text
- A coloured regular icon: {material-regular}`settings;3em;sd-text-success`, some more text.
- A coloured outline icon: {material-outlined}`settings;3em;sd-text-success`, some more text.
- A coloured sharp icon: {material-sharp}`settings;3em;sd-text-success`, some more text.
- A coloured round icon: {material-round}`settings;3em;sd-text-success`, some more text.
- A coloured two-tone icon: {material-twotone}`settings;3em;sd-text-success`, some more text.

````{tab-set-code}
```{literalinclude} ./snippets/myst/icon-material-design.txt
:language: markdown
```
```{literalinclude} ./snippets/rst/icon-material-design.txt
:language: rst
```
````

### FontAwesome Icons

FontAwesome icons are added via the FontAwesome CSS classes.
The role name selects the icon *style* — solid (`fa-solid`/`fas`/`fa`),
brands (`fa-brands`/`fab`) or regular (`fa-regular`/`far`) — and you can pick
any spelling:

- A solid icon {fa-solid}`rocket;sd-text-primary`, some more text.
- A brand icon {fa-brands}`github`, some more text.
- A regular icon {fa-regular}`bell;sd-text-warning`, some more text.

By default each role emits exactly the classes it is named after: the
`fa-solid` role applied to `rocket` produces
`<span class="fa-solid fa-rocket">`, while the `fas` role produces
`<span class="fas fa-rocket">`.

#### Matching your FontAwesome version

Set `sd_fontawesome_version` to the major version of the FontAwesome CSS you
load, and every role spelling is translated to that version's class scheme —
so the role names are version-agnostic: write whichever spelling you prefer,
and upgrading (or downgrading) FontAwesome is a one-line `conf.py` change:

```python
sd_fontawesome_version = "6"
```

| Roles | Style | `"4"` | `"5"` | `"6"` |
| ----- | ----- | ----- | ----- | ----- |
| `fa`, `fas`, `fa-solid` | solid | `fa` | `fas` | `fa-solid` |
| `fab`, `fa-brands` | brands | `fa` | `fab` | `fa-brands` |
| `far`, `fa-regular` | regular | `fa` | `far` | `fa-regular` |

The default, `"as-named"`, emits the role name verbatim as the leading class
(the behaviour shown above, and of previous sphinx-design versions).

```{note}
The bare `fa` role maps to *solid* under `"5"`/`"6"` (FontAwesome 4's single
style became solid in v5). Conversely, `"4"` collapses all style distinctions
to `fa` in the HTML classes, since FontAwesome 4 had no style prefixes —
LaTeX output is unaffected (it always uses the role's own style).

Only the leading *style* class is translated — icon **names** that FontAwesome
renamed between versions (e.g. v4 `external-link` vs v6
`arrow-up-right-from-square`) are emitted as written, just like in the LaTeX
note below.
```

#### Loading the FontAwesome CSS

sphinx-design does **not** bundle the FontAwesome CSS.
By default (`sd_fontawesome_source = "none"`) you, or your theme, are
responsible for making it available (many themes already include it).

To have sphinx-design load it for you from a
[FontAwesome CDN](https://cdnjs.com/libraries/font-awesome),
so you no longer have to hand-edit
[`html_css_files`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files),
set:

```python
sd_fontawesome_source = "cdn"
```

This adds `sd_fontawesome_cdn_url` (a FontAwesome v6 `all.min.css` by default)
to the HTML output. Override `sd_fontawesome_cdn_url` to pin a different
version or a self-hosted copy.

````{warning}
Since the FontAwesome icons are fetched directly from their distributed CSS, specifying a height/size to the icon roles is not supported.
However, you can always add your custom CSS class that controls the `font-size` property.

If a height/size is supplied to an icon role, then it will be interpreted as a CSS class.
There can only be a maximum of 1 `;` in the roles' arguments
````

````{tab-set-code}
```markdown
- An icon {fa-solid}`spinner;sd-text-primary`, some more text.
- An icon {fa-brands}`github`, some more text.
- An icon {fa-brands}`gitkraken;sd-text-success fa-xl`, some more text.
- An icon {fa-solid}`skull;sd-text-danger`, some more text.
```
```rst
- An icon :fa-solid:`spinner;sd-text-primary`, some more text.
- An icon :fa-brands:`github`, some more text.
- An icon :fa-brands:`gitkraken;sd-text-success fa-xl`, some more text.
- An icon :fa-solid:`skull;sd-text-danger`, some more text.
```
````

- An icon {fa-solid}`spinner;sd-text-primary`, some more text.
- An icon {fa-brands}`github`, some more text.
- An icon {fa-brands}`gitkraken;sd-text-success fa-xl`, some more text.
- An icon {fa-solid}`skull;sd-text-danger`, some more text.

#### Using FontAwesome Pro kits

If you use a [FontAwesome Pro kit](https://fontawesome.com/kits), keep
`sd_fontawesome_source = "none"` (do **not** also load the free CDN, whose
own font-face would fight your kit), load the kit as usual, and either use the
v6 role names (`fa-solid`/`fa-brands`/`fa-regular`) directly, or set
`sd_fontawesome_version = "6"`, which makes every spelling — including the
concise `fas`/`fab`/`far` — emit exactly the classes a Pro kit expects.

#### Concise role names

The `fas`, `fab` and `far` roles (and `fa`, which FontAwesome itself
deprecated in v5) are equally supported, with no plans to remove them. By
default (`sd_fontawesome_version = "as-named"`) each role name is emitted
verbatim as the leading CSS class, so these produce the v4/v5 class scheme
(`fas fa-...`):

- An icon {fas}`spinner;sd-text-primary`, some more text.
- An icon {fab}`github`, some more text.
- An icon {far}`bell`, some more text.

The free CDN builds define both class schemes, so the concise names work fine
there as-is. And combined with `sd_fontawesome_version`, the concise names are
future-proof for *any* setup: keep writing `fas`/`fab`/`far` and set the
version knob to match the CSS you load — no source churn when FontAwesome (or
your theme's bundled copy) moves on. The `fa-solid`/`fa-brands`/`fa-regular`
spellings remain handy for matching what fontawesome.com shows for each icon.
Note that not all regular style icons are free; `far`/`fa-regular` only work
with the free ones.

#### FontAwesome in LaTeX output

By default, icons are only rendered for HTML builders.
To also render them in LaTeX output, set `sd_fontawesome_latex` to the LaTeX
package you want to use:

| `sd_fontawesome_latex` | LaTeX package | Rendering |
| ---------------------- | ------------- | --------- |
| `False` / `"none"` (default) | – | icons skipped (one warning per build) |
| `True` / `"fontawesome"` | [`fontawesome`](https://ctan.org/pkg/fontawesome) | `\faicon{name}` |
| `"fontawesome5"` | [`fontawesome5`](https://ctan.org/pkg/fontawesome5) | `\faIcon{name}` (see below) |

```python
sd_fontawesome_latex = "fontawesome5"
```

With `"fontawesome5"`, the icon style is mapped to that package's conventions:
brand icons resolve by name (`\faIcon{github}`), regular-style icons use the
optional style argument (`\faIcon[regular]{name}`), and solid icons use the
default (`\faIcon{name}`). Note that `sd_fontawesome_version` only selects the
*HTML* class scheme; LaTeX rendering is driven by the role's style and
`sd_fontawesome_latex` alone.

If your theme (or another extension) already loads the `fontawesome5` package,
set `sd_fontawesome_latex = "fontawesome5"` so both agree, avoiding the LaTeX
error that comes from mixing the `fontawesome` and `fontawesome5` packages.

```{note}
The LaTeX packages predate FontAwesome 6 and resolve icons by their **v5**
(or v4, for `fontawesome`) names. Icons that were renamed in v6 (for example
`arrow-up-right-from-square`, formerly `external-link-alt`) render in HTML
but will raise an "icon not found" error when building PDF output — use the
older name if you need LaTeX support for such an icon.
```
