Input Widgets
Use single-line Python to define input widgets and retrieve their values in 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
.sample()
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 sample()
You can use .sample()
to access the widget’s value without triggering a cell rerun. Think of .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: