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.
File Input
File Input
File selector widgets allow users to select a file in their Latch Data and return a latch path that can be downloaded and used in a layout.
Widget Parameters
label
: string string value (required)
default
: string latch data path string used as the default widget value
required
: boolean a boolean that sets the input as requiring input by user and errored when empty
appearance
: dict containing widget appearance attributes:
"placeholder"
: string placeholder value displayed before a set value
"detail"
: string secondary label text displayed after thet label
"help_text"
: string informative text displayed below input
"error_text"
: string error text displayed below input that replaceshelp_text
and sets the input state as errored
"description"
: string longer description text displayed in a hoverable tooltip next to the label
Registry Table Input
Registry Table Input
Registry Table Select inputs allow users to select a table from their workspaces registry. The input returns a table id that can be used to fetch table data using the Table class.
Widget Parameters
label
: string label (required)
default
: string id of a registry table
required
: boolean that sets the input as requiring input by user and errored when empty
appearance
: dict containing widget appearance attributes:
"placeholder"
: string placeholder value displayed before a set value
"detail"
: string secondary label text displayed after thet label
"help_text"
: string informative text displayed below input
"error_text"
: string error text displayed below input that replaceshelp_text
and sets the input state as errored
"description"
: string longer description text displayed in a hoverable tooltip next to the label
Table Class Parameters & Methods
Parameters
id
: string id of registry table
Methods
Table.get_dataframe()
: returns a pandas dataframe for the provided registry table id
Datasource
Datasource
The Datasource widget allows you to select a tabular datasource from various sources. The datasource can be a file, registry table, or other dataframe in the notebook.
When setting default values, you must specify the datasource type and then specify the appropriate key or id.
Text Input
Text Input
Text inputs allow users to specify a custom text string.
label
: string label (required)
default
: default string value for input
required
: a boolean that sets the input as requiring input by user and errored when empty
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
Select Input
Select Input
Select inputs allow users to select a single item from a list of string or number options.
label
: string label (required)
options
: list of values for the select
default
: default option from options
required
: a boolean that sets the input as requiring input by user and errored when empty
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
Multiselect Input
Multiselect Input
Multiselect inputs allow users to select a list of items from a list of string or number options.
label
: string label (required)
options
: list of values for the select
default
: list of default options from options
required
: a boolean that sets the input as requiring input by user and errored when empty
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
Radio Group Input
Radio Group Input
Radio group inputs allow users to select a single item from a list of string or number options.
Checkbox Input
Checkbox Input
Checkbox inputs allow users to select a boolean true or false value
Mutliple Widgets in a Row
Mutliple Widgets in a Row
With Rows you’re able to stack widgets horizontally, in a row. Widgets in a Row will automatically wrap to the next line when there is insufficient space.
Button Widget
Button Widget
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: