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:

from lplots.widgets.select import w_select

options = w_select(
  label="Select an item from the dropdown",
  options=["alpha", "bravo", "charlie"],
)


print(options.value)
# prints `"alpha", "bravo" or "charlie"` depending on user selection

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.

select = w_multi_select(
  label="Multiselect Input",
  options=["Alpha", "Bravo", "Charlie"],
  appearance={
    "placeholder": "Placeholder…",
    "detail": "(details)",
    "help_text": "Help text",
    "error_text": "Error text",
    "description": "Hover description",
  }
)

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 replaces help_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:

# Cell number 1
a = w_text_input(label="a")

print(a.value)
  • In this example, the text input widget a is the writer. When the user inputs a new value, it updates the Signal associated with a.
  • Accessing a.value makes the cell a listener. Whenever the input in a changes, the cell will automatically re-run. Calling a.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:

  1. Use a Button widget (Recommended)
  2. Use ._signal.sample() (Not recommended)

A button widget allows you to manually trigger a cell run only when the button is clicked.

Example:

from lplots.widgets.text import w_text_input
from lplots.widgets.button import w_button

# Create a text input widget
text_input = w_text_input(label="Input")

# Create a button to trigger execution manually
button = w_button(label="Run")

# When the button is clicked, this cell will execute
if button.value:
    print(text_input.value)

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.

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:

from lplots.widgets.text import w_text_input
text_input = w_text_input(label="Input")

print(text_input.value)

The following code will only execute when the user presses the “Run” button in the upper right corner of the UI:

from lplots.widgets.text import w_text_input
text_input = w_text_input(label="Input")

print(text_input._signal.sample())