reactive.value

reactive.value(self, value=MISSING, *, read_only=False)

Create a reactive value.

Reactive values are the source of reactivity in Shiny. Changes to reactive values invalidate downstream reactive functions (calc, effect, and render functions decorated with @output). When these functions are invalidated, they get scheduled to re-execute.

Shiny input values are read-only reactive values. For example, input.x is a reactive value object, and to get the current value, you can call input.x() or input.x.get(). When you do that inside of a reactive function, the function takes a dependency on the reactive value.

Parameters

value: T | MISSING_TYPE = MISSING

An optional initial value.

read_only: bool = False

If True, then the reactive value cannot be set().

Returns

Type Description
An instance of a reactive value.

Raises

Type Description
SilentException If get is called before a value is provided/set.

Note

A reactive value may only be read from within a reactive function (e.g., calc, effect, shiny.render.text, etc.) and, when doing so, the function takes a reactive dependency on the value (i.e., when the value changes, the calling reactive function will re-execute).

See Also

Examples

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

## file: app.py
from shiny import App, Inputs, Outputs, Session, reactive, render, ui

app_ui = ui.page_sidebar(
    ui.sidebar(
        ui.input_action_button("minus", "-1"),
        ui.input_action_button("plus", "+1"),
    ),
    ui.output_text("value"),
)


def server(input: Inputs, output: Outputs, session: Session):
    val = reactive.value(0)

    @reactive.effect
    @reactive.event(input.minus)
    def _():
        newVal = val.get() - 1
        val.set(newVal)

    @reactive.effect
    @reactive.event(input.plus)
    def _():
        newVal = val.get() + 1
        val.set(newVal)

    @render.text
    def value():
        return str(val.get())


app = App(app_ui, server)

Methods

Name Description
freeze Freeze the reactive value.
get Read the reactive value.
is_set Check if the reactive value is set.
set Set the reactive value to a new value.
unset Unset the reactive value.

freeze

reactive.value.freeze()

Freeze the reactive value.

Freezing is equivalent to unsetting the value, but it does not invalidate dependents.

get

reactive.value.get()

Read the reactive value.

Returns

Type Description
T A value.

Raises

Type Description
SilentException If the value is not set.
RuntimeError If called from outside a reactive function.

is_set

reactive.value.is_set()

Check if the reactive value is set.

Returns

Type Description
bool True if the value is set, False otherwise.

set

reactive.value.set(value)

Set the reactive value to a new value.

Parameters

value: T

A value.

Returns

Type Description
bool True if the value was set to a different value and False otherwise.

Raises

Type Description
RuntimeError If called on a read-only reactive value.

unset

reactive.value.unset()

Unset the reactive value.

Returns

Type Description
None True if the value was set prior to this unsetting.