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"