express.ui.value_box

express.ui.value_box(
    showcase=None,
    showcase_layout='left center',
    full_screen=False,
    theme=None,
    height=None,
    max_height=None,
    min_height=None,
    fill=True,
    class_=None,
    **kwargs,
)

Context manager for a value box

This function wraps value_box.

An opinionated (card-powered) box, designed for displaying a title (the 1st child), value (the 2nd child), and other explanation text (other children, if any). Optionally, a showcase can provide for context for what the value represents (for example, it could hold an icon, or even a output_plot).

Parameters

showcase : Optional[TagChild] = None

A Tag child to showcase (e.g., an icon, a output_plot, etc).

showcase_layout : ui._valuebox.SHOWCASE_LAYOUTS_STR | ui.ShowcaseLayout = 'left center'

One of "left center" (default), "top right" or "bottom". Alternatively, you can customize the showcase layout options with the showcase_left_center, :func:~shiny.express.ui.showcase_top_right(), or :func:~shiny.express.ui.showcase_bottom() functions. Use the options functions when you want to control the height or width of the showcase area.

theme : Optional[str | ui.ValueBoxTheme] = None

The name of a theme (e.g. "primary", "danger", "purple", "bg-green", "text-red") for the value box, or a theme constructed with value_box_theme. The theme names provide a convenient way to use your app’s Bootstrap theme colors as the foreground or background colors of the value box. For more control, you can create your own theme with value_box_theme where you can pass foreground and background colors directly. Bootstrap supported color themes: "blue", "purple", "pink", "red", "orange", "yellow", "green", "teal", and "cyan". These colors can be used with bg-NAME, text-NAME, and bg-gradient-NAME1-NAME2 to change the background, foreground, or use a background gradient respectively. If a theme string does not start with text- or bg-, it will be auto prefixed with bg-.

full_screen : bool = False

If True, an icon will appear when hovering over the card body. Clicking the icon expands the card to fit viewport size.

height : Optional[CssUnit] = None

Any valid CSS unit (e.g., height="200px"). Doesn’t apply when a value box is made full_screen.

fill : bool = True

Whether to allow the value box to grow/shrink to fit a fillable container with an opinionated height (e.g., page_fillable).

class_ : Optional[str] = None

Utility classes for customizing the appearance of the summary card. Use bg-* and text-* classes (e.g, "bg-danger" and "text-light") to customize the background/foreground colors.

****kwargs** : TagAttrValue = {}

Additional attributes to pass to card.

Examples

#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 400

## file: app.py
from icons import piggy_bank

from shiny.express import ui

with ui.layout_columns():
    with ui.value_box(
        showcase=piggy_bank, theme="bg-gradient-orange-red", full_screen=True
    ):
        "KPI Title"
        "$1 Billion Dollars"
        "Up 30% VS PREVIOUS 30 DAYS"

    with ui.value_box(
        showcase=piggy_bank,
        theme="text-green",
        showcase_layout="top right",
        full_screen=True,
    ):
        "KPI Title"
        "$1 Billion Dollars"
        "Up 30% VS PREVIOUS 30 DAYS"

    with ui.value_box(
        showcase=piggy_bank, theme="purple", showcase_layout="bottom", full_screen=True
    ):
        "KPI Title"
        "$1 Billion Dollars"
        "Up 30% VS PREVIOUS 30 DAYS"


## file: icons.py
from shiny import ui

piggy_bank = ui.HTML(
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" class="bi bi-piggy-bank " style="fill:currentColor;height:100%;" aria-hidden="true" role="img" ><path d="M5 6.25a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0zm1.138-1.496A6.613 6.613 0 0 1 7.964 4.5c.666 0 1.303.097 1.893.273a.5.5 0 0 0 .286-.958A7.602 7.602 0 0 0 7.964 3.5c-.734 0-1.441.103-2.102.292a.5.5 0 1 0 .276.962z"></path>\n<path fill-rule="evenodd" d="M7.964 1.527c-2.977 0-5.571 1.704-6.32 4.125h-.55A1 1 0 0 0 .11 6.824l.254 1.46a1.5 1.5 0 0 0 1.478 1.243h.263c.3.513.688.978 1.145 1.382l-.729 2.477a.5.5 0 0 0 .48.641h2a.5.5 0 0 0 .471-.332l.482-1.351c.635.173 1.31.267 2.011.267.707 0 1.388-.095 2.028-.272l.543 1.372a.5.5 0 0 0 .465.316h2a.5.5 0 0 0 .478-.645l-.761-2.506C13.81 9.895 14.5 8.559 14.5 7.069c0-.145-.007-.29-.02-.431.261-.11.508-.266.705-.444.315.306.815.306.815-.417 0 .223-.5.223-.461-.026a.95.95 0 0 0 .09-.255.7.7 0 0 0-.202-.645.58.58 0 0 0-.707-.098.735.735 0 0 0-.375.562c-.024.243.082.48.32.654a2.112 2.112 0 0 1-.259.153c-.534-2.664-3.284-4.595-6.442-4.595zM2.516 6.26c.455-2.066 2.667-3.733 5.448-3.733 3.146 0 5.536 2.114 5.536 4.542 0 1.254-.624 2.41-1.67 3.248a.5.5 0 0 0-.165.535l.66 2.175h-.985l-.59-1.487a.5.5 0 0 0-.629-.288c-.661.23-1.39.359-2.157.359a6.558 6.558 0 0 1-2.157-.359.5.5 0 0 0-.635.304l-.525 1.471h-.979l.633-2.15a.5.5 0 0 0-.17-.534 4.649 4.649 0 0 1-1.284-1.541.5.5 0 0 0-.446-.275h-.56a.5.5 0 0 1-.492-.414l-.254-1.46h.933a.5.5 0 0 0 .488-.393zm12.621-.857a.565.565 0 0 1-.098.21.704.704 0 0 1-.044-.025c-.146-.09-.157-.175-.152-.223a.236.236 0 0 1 .117-.173c.049-.027.08-.021.113.012a.202.202 0 0 1 .064.199z"></path></svg>'
)