Cards#

Cards contain content and actions about a single subject. A card is a flexible and extensible content container, it can be formatted with components including headers and footers, titles and images.

Card Title

Card content

See the Material Design and Bootstrap card descriptions for further details.

Syntax
:::{card} Card Title

Card content
:::

.. card:: Card Title

    Card content

All content before the first occurrence of three or more ^^^ is considered as a header, and all content after the final occurrence of three or more +++ is considered as a footer:

Header

Card Title

Card content

Footer

Syntax
:::{card} Card Title
Header
^^^
Card content
+++
Footer
:::

.. card:: Card Title

    Header
    ^^^
    Card content
    +++
    Footer

When using cards in grids (see grid-item-card) footers can be aligned.

Header

Card Title

Card content

Footer

Header

Card Title

Longer

Card content

Footer

Card images#

You can also add an image as the background of a card or at the top/bottom of the card, with the img-background, img-top, img-bottom options:

your desired alt text
Title

Text

your desired alt text

Header

Title

Content

Footer

Header

Title

Content

Footer

your desired alt text
Syntax
:::::{grid} 2 3 3 4

::::{grid-item}

:::{card} Title
:img-background: images/particle_background.jpg
:class-card: sd-text-black
:img-alt: my text

Text
:::

::::

::::{grid-item-card} Title
:img-top: images/particle_background.jpg
:img-alt:

Header
^^^
Content
+++
Footer
::::

::::{grid-item-card} Title
:img-bottom: images/particle_background.jpg

Header
^^^
Content
+++
Footer
::::

:::::

.. grid:: 2 3 3 4

    .. grid-item::

        .. card:: Title
            :img-background: images/particle_background.jpg
            :class-card: sd-text-black
            :img-alt: my text

            Text

    .. grid-item-card:: Title
        :img-top: images/particle_background.jpg
        :img-alt:

        Header
        ^^^
        Content
        +++
        Footer

    .. grid-item-card:: Title
        :img-bottom: images/particle_background.jpg

        Header
        ^^^
        Content
        +++
        Footer

Clickable cards#

Using the link and link-type options, you can turn an entire card into a clickable link. Try hovering over then clicking on the cards below:

Clickable Card (external)

The entire card can be clicked to navigate to https://example.com.

example.com
Clickable Card (internal)

The entire card can be clicked to navigate to the cards-clickable reference target.

Clickable cards
Syntax
(cards-clickable)=

## Clickable cards

Using the `link` and `link-type` options, you can turn an entire card into a clickable link. Try hovering over then clicking on the cards below:

:::{card} Clickable Card (external)
:link: https://example.com

The entire card can be clicked to navigate to <https://example.com>.
:::

:::{card} Clickable Card (external)
:link: https://example.com
:link-alt: example.com

The entire card can be clicked to navigate to <https://example.com>.
:::

:::{card} Clickable Card (internal)
:link: cards-clickable
:link-type: ref

The entire card can be clicked to navigate to the `cards-clickable` reference target.
:::

:::{card} Clickable Card (internal)
:link: cards-clickable
:link-type: ref
:link-alt: clickable cards

The entire card can be clicked to navigate to the `cards-clickable` reference target.
:::

.. _cards-clickable:

Clickable cards
...............

Using the ``link`` and ``link-type`` options, you can turn an entire card into a clickable link. Try hovering over then clicking on the cards below:

.. card:: Clickable Card (external)
    :link: https://example.com

    The entire card can be clicked to navigate to https://example.com.

.. card:: Clickable Card (external)
    :link: https://example.com
    :link-alt: example.com

    The entire card can be clicked to navigate to https://example.com.

.. card:: Clickable Card (internal)
    :link: cards-clickable
    :link-type: ref

    The entire card can be clicked to navigate to the ``cards-clickable`` reference target.

.. card:: Clickable Card (internal)
    :link: cards-clickable
    :link-type: ref
    :link-alt: clickable cards

    The entire card can be clicked to navigate to the ``cards-clickable`` reference target.

The external link created above is equivalent to using <https://example.com> (https://example.com), or if the link-alt option is provided, [alt text](https://example.com) (alt text).

Tip

Using URLs as link text makes it harder for disabled people and for search engines to digest your web page, so it’s best to provide link text via the link-alt option.

The internal link created above is equivalent to using {ref}`cards-clickable` (Clickable cards), or if the link-alt option is provided, {ref}`alt text <cards-clickable>` (alt text).

Note

You cannot add additional links to the clickable card, neither in the card title nor in the card body. The entire card becomes a single link to the destination you specify, which overrides any other links inside the card.

Aligning cards#

You can use the text-align option to align the text in a card, and also auto margins to align the cards horizontally.

Align Center

Content

Align Right

Content

Align Left

Content

Card carousels#

The card-carousel directive can be used to create a single row of fixed width, scrollable cards. The argument should be a number between 1 and 12, to denote the number of cards to display.

When scrolling a carousel, the scroll will snap to the start of the nearest card:

card 1

content

card 2

Longer

content

card 3
card 4
card 5
card 6
Syntax
::::{card-carousel} 2

:::{card} card 1
content
:::
:::{card} card 2
Longer

content
:::
:::{card} card 3
:::
:::{card} card 4
:::
:::{card} card 5
:::
:::{card} card 6
:::
::::

.. card-carousel:: 2

    .. card:: card 1

        content

    .. card:: card 2

        Longer

        content

    .. card:: card 3

    .. card:: card 4

    .. card:: card 5

    .. card:: card 6

card options#

width

The width that the card should take up (in %): auto, 25%, 50%, 75%, 100%.

margin

Outer margin of grid. One (all) or four (top bottom left right) values from: 0, 1, 2, 3, 4, 5, auto.

text-align

Default horizontal text alignment: left, right, center or justify

img-background

A URI (relative file path or URL) to an image to be placed below the content.

img-top

A URI (relative file path or URL) to an image to be placed above the content.

img-bottom

A URI (relative file path or URL) to an image to be placed below the content.

img-alt

Alternative text for the image (that will be used by screen-readers).

link

Turn the entire card into a clickable link to an external/internal target.

link-type

Type of link: url (default), ref, doc, any.

link-alt

Alternative text for the link (that will be used by screen-readers).

shadow

The size of the shadow below the card: none, sm (default), md, lg.

class-card

Additional CSS classes for the card container element.

class-header

Additional CSS classes for the header element.

class-body

Additional CSS classes for the body element.

class-title

Additional CSS classes for the title element.

class-footer

Additional CSS classes for the footer element.

class-img-top

Additional CSS classes for the top image (if present).

class-img-bottom

Additional CSS classes for the bottom image (if present).

On this page
Show Source