Widgets
Widgets can be used to create transforms that users can update based on user input. You’re able to define a widget and use its user input in your analysis code.
Each widget functions as a Python class and can be assigned to a variable. By calling .value
on the variable, you can access the actual widget value. For example:
Widgets are rendered in the order that they are called.
Supported Widget Types
Below is a comprehensive list of supported widget types.
Widget Appearance
Each widget allows you to specify appearance and input discriptions.
appearance
: a dict containing widget appearance attributes:
"placeholder"
: placeholder value displayed before a set value
"detail"
: secondary label text displayed after thet label
"help_text"
: informative text displayed below input
"error_text"
: error text displayed below input that replaceshelp_text
and sets the input state as errored
"description"
: longer description text displayed in a hoverable tooltip next to the label
Widgets Reactivity
- Every widget stores a Signal, which is the fundamental unit of reactivity in a Plot notebook.
- Signals hold dynamic values that change over time. When a signal’s value is updated, any notebook cell that references it is automatically re-executed.
- Each Signal consists of a writer and a listener:
- The writer sets the Signal’s value.
- The listener subscribes to the Signal and triggers automatic cell execution when the Signal changes.
Example:
- In this example, the text input widget
a
is the writer. When the user inputs a new value, it updates the Signal associated witha
. - Accessing
a.value
makes the cell a listener. Whenever the input in a changes, the cell will automatically re-run. Callinga.value
also returns the widget’s current value. - This reactivity extends to any downstream cell using
a.value
, ensuring they also re-execute when a is updated.
Can I access a widget value without triggering a cell rerun?
To retrieve a widget’s value, you typically would use .value
. However, there are times when you don’t want to trigger an automatic cell run when the widget value updates, especially if the cells using widget.value
are computationally expensive. There are two solutions to this problem:
- Use a Button widget (Recommended)
- Use
._signal.sample()
(Not recommended)
1. Use a Button Widget (Recommended)
A button widget allows you to manually trigger a cell run only when the button is clicked.
Example:
How it works:
- The cell only executes when the user clicks the Run button.
- Widget value changes do not automatically rerun the cell, offering full control over execution.
2 - Use .signal.sample()
(Not recommended)
You can use ._signal.sample()
to access the widget’s value without triggering a cell rerun. Think of ._signal.sample()
as capturing a snapshot of the widget’s value at the precise moment you click the “Run” button in the upper right corner of a cell.
Examples: The following code cell will automatically rerun whenever the widget value changes:
The following code will only execute when the user presses the “Run” button in the upper right corner of the UI:
Was this page helpful?