Skip to content

How to use cards & buttons

This guide shows you how to use cards and buttons to visualize and interact with your data in the dashboard.

Cards

The Card is a flexible and extensible component, allowing for customization via Markdown text. Refer to any online guide for basic markdown usage.

You can add a Card to your dashboard by inserting the Card into the components argument of the Page.

Card

import vizro.models as vm
from vizro import Vizro

page = vm.Page(
    title="Card",
    components=[
        vm.Card(
            text="""
                ### Card Title
                Commodi repudiandae consequuntur voluptatum.
            """,
        ),
    ],
)

dashboard = vm.Dashboard(pages=[page])

Vizro().build(dashboard).run()
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
    - text: |
        Commodi repudiandae consequuntur voluptatum.
      title: Card Title
      type: card
  title: Card

Card

Customize card text

The Card utilizes the dcc.Markdown component from Dash as its underlying text component. For more details on customizing the markdown text, refer to the dcc.Markdown component documentation. Based on the provided examples from Dash, the Card model supports the following:

  • Headers
  • Emphasis
  • Lists
  • Block Quotes
  • Links

Card with custom text

import vizro.models as vm
from vizro import Vizro

page = vm.Page(
    title="Customizing Text",
    components=[
        vm.Card(
            text="""
                # Header level 1 <h1>

                ## Header level 2 <h2>

                ### Header level 3 <h3>

                #### Header level 4 <h4>
            """,
        ),
        vm.Card(
            text="""
                 ### Paragraphs
                 Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.

                 Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.

                 Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.

                 Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
            """,
        ),
        vm.Card(
            text="""
                ### Block Quotes

                >
                > A block quote is a long quotation, indented to create a separate block of text.
                >
            """,
        ),
        vm.Card(
            text="""
                ### Lists

                * Item A
                    * Sub Item 1
                    * Sub Item 2
                * Item B
            """,
        ),
        vm.Card(
            text="""
                ### Emphasis

                This word will be *italic*

                This word will be **bold**

                This word will be _**bold and italic**_
            """,
        ),
    ],
)

dashboard = vm.Dashboard(pages=[page])

Vizro().build(dashboard).run()
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
  - text: |
      # Header level 1 <h1>

      ## Header level 2 <h2>

      ### Header level 3 <h3>

      #### Header level 4 <h4>
    type: card
  - text: |
      Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.

      Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.

      Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.

      Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
    title: Paragraphs
    type: card
  - text: |
      >
      > A block quote is a long quotation, indented to create a separate block of text.
      >
    title: Block Quotes
    type: card
  - text: |
      * Item A
        * Sub Item 1
        * Sub Item 2
      * Item B
    title: Lists
    type: card
  - text: |
      This word will be *italic*

      This word will be **bold**

      This word will be _**bold and italic**_
    title: Emphasis
    type: card
  title: Customizing Text

CardText

Place an image on a card

Images can be added to the text parameter by using the standard markdown syntax:

![Image ALT text](Image URL)

An image ALT text provides a description to your image and serves e.g. as a text placeholder or to improve the accessibility of your app. Providing an image ALT text is optional.

  1. To use a relative Image URL, place an image of your choice into your assets folder first
  2. Use markdown to render your image by using one of the following syntax:
    • Relative Image URL: ![Image ALT text](/path/to/image.png)
    • Absolute Image URL: ![Image ALT text](https://XXXXXX)

Card with image

import vizro.models as vm
from vizro import Vizro

page = vm.Page(
        title="Placing Images",
        components=[
            vm.Card(
                text="""
                ### My card with image!

                ![continent](assets/images/continents/africa.svg)

                 Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.

                 Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.

                 Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
            """,
            ),
        ],
    )

dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
    - text: |
        ![continent](assets/images/continents/africa.svg)

        Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.

        Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.

        Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
      title: My card with image!
      type: card
  title: Placing Images

CardImageDefault

Note

Note that inserting images using html is by default turned off by the dcc.Markdown to prevent users being exposed to cross-site scripting attacks. If you need to turn it on, a custom component would have to be created.

You might notice that the image is quite large, find out how to style images (e.g. position and size) in the next section!

Style a card image

To change the styling of the image (e.g. size or position), add a URL hash to your image like this:

![Image ALT text](Image URL#my-image)

Note the added URL hash #my-image. Now create a CSS file placed in your assets folder and provide an attribute selector to select images with that matching URL hash.

Card with styled image

img[src*="#my-image"] {
  width: 120px;
  height: 120px;
}
import vizro.models as vm
from vizro import Vizro

page = vm.Page(
        title="Styling Images",
        components=[
            vm.Card(
                text="""
                ### My card with image!

                ![](assets/images/continents/africa.svg#my-image)

                 Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.

                 Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.

                 Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
            """,
            ),
        ],
    )

dashboard = vm.Dashboard(pages=[page])

Vizro().build(dashboard).run()
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
    - text: |
        ![](assets/images/continents/africa.svg#my-image)

        Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.

        Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.

        Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
      title: My card with image!
      type: card
  title: Styling Images

CardImageStyled

Tip

Use the following pre-defined URL hashes in your image path to have the image float next to the text:

  • floating-left: ![](my_image.png#floating-left)
  • floating-right: ![](my_image.png#floating-right)
  • floating-center: ![](my_image.png#floating-center)

Card with floating image

import vizro.models as vm
from vizro import Vizro

page = vm.Page(
        title="Floating Images",
        components=[
            vm.Card(
                text="""
                ### My card with image!

                ![](assets/images/continents/africa.svg#my-image#floating-right)

                 Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.

                 Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.

                 Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.

                 Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.

                 Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.

                Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
            """,
            ),
        ],
    )

dashboard = vm.Dashboard(pages=[page])

Vizro().build(dashboard).run()
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
    - text: |
        ![](assets/images/continents/africa.svg#my-image#floating-right)

        Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.

        Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.

        Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.

        Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.

        Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.

        Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
      title: My card with image!
      type: card
  title: Floating Images

CardImageFloating

Create a navigation card

Note

This section describes how to use the Card component to create a navigation card. To configure the navigation panel on the left hand side of the screen, refer to the guide on navigation.

A navigation card allows you to navigate to a different page via a click on the card area. To create a navigation card, do the following:

  • Insert the Card into the components argument of the Page
  • Provide the text parameter with a title and some description
  • Provide the href parameter (relative or absolute URL)

Navigation Card

import vizro.models as vm
import vizro.plotly.express as px
from vizro import Vizro

iris = px.data.iris()

page_1 = vm.Page(
    title="Homepage",
    components=[
        vm.Card(
            text="""
            ### Filters and parameters

            Leads to the first page on click.
            """,
            href="/filters-and-parameters",
        ),
        vm.Card(
            text="""
            ### Google - External Link

            Leads to an external link on click.
            """,
            href="https://google.com",
        ),
    ],
)

page_2 = vm.Page(
    title="Filters and parameters",
    components=[
        vm.Graph(id="scatter", figure=px.scatter(iris, x="sepal_length", y="petal_width", color="sepal_width")),
    ],
)

dashboard = vm.Dashboard(pages=[page_1, page_2])

Vizro().build(dashboard).run()
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
    - text: |
        ### Filters and parameters

        Leads to the first page on click
      href: /filters-and-parameters
      type: card
    - text: |
        ### Google - External Link

        Leads to an external link on click.
      href: https://google.com
      type: card
  title: Homepage
- components:
    - figure:
        _target_: scatter
        color: sepal_width
        data_frame: iris
        x: sepal_length
        y: petal_width
      id: scatter
      type: graph
  title: Filters and parameters

NavCard

If you now click on the card area, you should automatically be redirected to the relevant href.

Note

When using the Card, keep the following considerations in mind:

  • If the href provided is a relative URL, it should match the path of the Page that the Card should navigate to.
  • If the href provided is an absolute link, it should start with https:// or an equivalent protocol.

Add an icon

If you want to add an icon to your card, just add your image as described in the previous section If you use the image URL hash icon-top, the image will be styled according to our default icon styling.

Navigation Card with Icon

import vizro.models as vm
import vizro.plotly.express as px
from vizro import Vizro

iris = px.data.iris()

page_1 = vm.Page(
    title="Homepage",
    components=[
        vm.Card(
            text="""
            ![](assets/images/icons/content/hypotheses.svg#icon-top)

            ### Filters and parameters

            Leads to the first page on click.
            """,
            href="/filters-and-parameters",
        ),

        vm.Card(
            text="""
            ![](assets/images/icons/content/features.svg#icon-top)

            ### Google - External Link

            Leads to an external link on click.
            """,
            href="https://google.com",
        ),
    ],
)

page_2 = vm.Page(
    title="Filters and parameters",
    components=[
        vm.Graph(id="scatter", figure=px.scatter(iris, x="sepal_length", y="petal_width", color="sepal_width")),
    ],
)

dashboard = vm.Dashboard(pages=[page_1, page_2])

Vizro().build(dashboard).run()
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
    - text: |
        ![](assets/images/icons/content/hypotheses.svg#icon-top)

        ### Filters and parameters

        Leads to the first page on click
      href: /filters-and-parameters
      type: card
    - text: |
        ![](assets/images/icons/content/features.svg#icon-top)

        ### Google - External Link

        Leads to an external link on click.
      href: https://google.com
      type: card
  title: Homepage
- components:
    - figure:
        _target_: scatter
        color: sepal_width
        data_frame: iris
        x: sepal_length
        y: petal_width
      id: scatter
      type: graph
  title: Filters and parameters

NavCardIcon

Note that in the above example the first Card navigates to an existing Page in the app with path = filters-and-parameters and the second one to an external link.

Add an icon responsive to theme switch

To add an icon that is responsive to the theme switch, you will need to override the value of the filter CSS property.

The filter CSS property lets you add visual effects to elements using different functions. In our example, we're using the --inverse-color CSS variable from the Vizro theme.

It uses the CSS invert() function to flip the color of the icon when you switch themes. Please note that this only works if your initial icon has a white fill color. If your icon is not white, you can change its color by adding fill="white" to the SVG code.

Assign the predefined CSS variable --inverse-color to the filter property of your selected icon.

img[src*="#my-image"] {
  filter: var(--inverse-color);
}
Responsive icon

responsive icon

Buttons

To enhance dashboard interactions, you can use the Button component to trigger any pre-defined action functions such as e.g. exporting chart data. Please refer to the user guide on Actions for currently available options.

To add a Button, simply insert it into the components argument of the Page.

You can configure the text argument to alter the display text of the Button and the actions argument to define which action function should be executed on button click.

In the below example we show how to configure a button to export the filtered data of a target chart using export_data, a pre-defined action function.

Button

import vizro.models as vm
import vizro.plotly.express as px
from vizro import Vizro
from vizro.actions import export_data

df = px.data.iris()

page = vm.Page(
    title="My first page",
    layout=vm.Layout(grid=[[0], [0], [0], [0], [1]]),
    components=[
        vm.Graph(
            id="scatter_chart",
            figure=px.scatter(
                df,
                x="sepal_width",
                y="sepal_length",
                color="species",
                size="petal_length",
            ),
        ),
        vm.Button(
            text="Export data",
            actions=[vm.Action(function=export_data(targets=["scatter_chart"]))],
        ),
    ],
    controls=[vm.Filter(column="species", selector=vm.Dropdown(title="Species"))],
)

dashboard = vm.Dashboard(pages=[page])

Vizro().build(dashboard).run()
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
  - components:
    - figure:
        _target_: scatter
        x: sepal_width
        y: sepal_length
        color: species
        size: petal_length
        data_frame: iris
      id: scatter_chart
      type: graph
    - type: button
      text: Export data
      id: export_data
      actions:
        - function:
            _target_: export_data
            targets:
              - scatter_chart
    controls:
      - column: species
        selector:
          title: Species
          type: dropdown
        type: filter
    layout:
      grid:
        - [0]
        - [0]
        - [0]
        - [0]
        - [1]
    title: My first page

Button

The Button component is currently reserved to be used inside the main panel (right-side) of the dashboard. However, there might be use cases where one would like to place the Button inside the control panel (left-side) with the other controls.

In this case, simply follow the user-guide outlined for custom components and manually add the Button as a valid type to the controls argument by running the following lines before your dashboard configurations:

from vizro import Vizro
import vizro.models as vm

vm.Page.add_type("controls", vm.Button)

# Add dashboard configurations below
...