ui.value_box

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

Value box

An opinionated (card-powered) box, designed for displaying a value and title. Optionally, a showcase can provide context for what the value represents (for example, it could hold an icon, or even a output_plot).

Parameters

title: TagChild

A string, number, or Tag child to display as the title or value of the value box. The title appears above the value.

*args: TagChild | TagAttrs = ()

Unnamed arguments may be any Tag children to display below value. Named arguments are passed to card as element attributes.

showcase: Optional[TagChild] = None

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

showcase_layout: SHOWCASE_LAYOUTS_STR | 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, showcase_top_right, or showcase_bottom functions. Use the options functions when you want to control the height or width of the showcase area.

theme: Optional[str | 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.

id: Optional[str] = None

Provide a unique identifier for the :func:~shiny.ui.value_box() to report its state to Shiny. For example, using id="my_value_box", you can observe the value box’s full screen state with input.my_value_box()["full_screen"].

**kwargs: TagAttrValue = {}

Additional attributes to pass to card.

Returns

Type Description
Tag A card

See Also

Examples

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

## file: app.py
from icons import piggy_bank

from shiny import App, ui

app_ui = ui.page_fluid(
    ui.layout_column_wrap(
        ui.value_box(
            "KPI Title",
            "$1 Billion Dollars",
            "Up 30% VS PREVIOUS 30 DAYS",
            showcase=piggy_bank,
            theme="bg-gradient-orange-red",
            full_screen=True,
        ),
        ui.value_box(
            "KPI Title",
            "$1 Billion Dollars",
            "Up 30% VS PREVIOUS 30 DAYS",
            showcase=piggy_bank,
            theme="text-green",
            showcase_layout="top right",
            full_screen=True,
        ),
        ui.value_box(
            "KPI Title",
            "$1 Billion Dollars",
            "Up 30% VS PREVIOUS 30 DAYS",
            showcase=piggy_bank,
            theme="purple",
            showcase_layout="bottom",
            full_screen=True,
        ),
    )
)


app = App(app_ui, server=None)