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 thevalue
. *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 withbg-NAME
,text-NAME
, andbg-gradient-NAME1-NAME2
to change the background, foreground, or use a background gradient respectively.If a
theme
string does not start withtext-
orbg-
, it will be auto prefixed withbg-
. 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 madefull_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-*
andtext-*
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, usingid="my_value_box"
, you can observe the value box’s full screen state withinput.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)