reactive.Value

reactive.Value(value=MISSING, *, read_only=False, name=None)

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().

name : str | None = None

An optional name for the reactive value, used in OpenTelemetry logging and debugging. If not provided, the name will be automatically inferred from the assignment statement (e.g., counter = reactive.Value(0) will use “counter” as the name). If automatic inference fails, the name will be None and logs will show "<unnamed>". Input values created by Shiny will have their names set automatically based on their input IDs.

Returns

An instance of a reactive value.

Raises

: 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
destroy Destroy this reactive value.
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.

destroy

reactive.Value.destroy()

Destroy this reactive value.

Unsets the value, invalidating all dependents and freeing the stored value. Idempotent: calling destroy() more than once has no effect. Works on read-only values (e.g., input values).

Note

This method will only perform the minimum cleanup needed to release resources and invalidate dependents — the same work that would happen if this object were garbage collected.

freeze

reactive.Value.freeze()

Freeze the reactive value.

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

Raises

: DestroyedReactiveError

If the value has been destroyed.

get

reactive.Value.get()

Read the reactive value.

Returns

: T

A value.

Raises

: DestroyedReactiveError

If the value has been destroyed.

: 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 False for destroyed values.

Returns

: 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

: bool

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

Raises

: DestroyedReactiveError

If the value has been destroyed.

: RuntimeError

If called on a read-only reactive value.

unset

reactive.Value.unset()

Unset the reactive value.

Returns

: None

True if the value was set prior to this unsetting.