Controls

Learn which type of controls are supported and how to use them.

A control is an element of the user interface that allows the user of the application to change input parameters. A dstack application may have any number of controls. The supported types of controls include text fields, drop-downs, sliders, and check-boxes. 
All controls inherit the base class dstack.controls.Control. They must be initiated and passed as **kwargs to the function dstack.app(). The argument of the function that produces the output (which is also passed to dstack.app()) must match the controls passed to the application. Here's a simple example:
from datetime import datetime, timedelta
​
import dstack.controls as ctrl
import dstack as ds
import plotly.graph_objects as go
import pandas_datareader.data as web
​
​
def get_chart(symbols: ctrl.ComboBox):
    start = datetime.today() - timedelta(days=30)
    end = datetime.today()
    df = web.DataReader(symbols.value(), 'yahoo', start, end)
    fig = go.Figure(
        data=[go.Candlestick(x=df.index, open=df['Open'], high=df['High'], low=df['Low'], close=df['Close'])])
    return fig
​
​
app = ds.app(get_chart, symbols=ctrl.ComboBox(['FB', 'AMZN', 'AAPL', 'NFLX', 'GOOG']))
​
result = ds.push('faang', app)
print(result.url)
Controls may use user functions to populate their data (e.g. load it from a database). It's also possible to make controls dependant on each other, e.g. to update their state based on the state of other controls.
Control API Reference
TextField
dstack.controls.TextField
Parameter
Type
Description
Required
data
Can be one of the following:
str
Callable[[], str]
The initial text value of the control.
Required if handler is not set.
handler
Callable[..., None]
The function that updates the state of the control.
Required if data is not set.
long
bool
True if the field may contain long values (text paragraphs). False by default.
No
label
str
The caption of the control.
No
depends
Can be one of the following:
List[Control]
Control
The other controls this control depends on.
No
require_apply
bool
True if the field requires an Apply button to be clicked for the application to update the output. True by default.
No
optional
bool
True if the filed's value is required for the application to provide the output. False by default. If it's False, the data is empty, and the Apply button is required, the Apply button will be disabled.
No
ComboBox
dstack.controls.ComboBox
Parameter
Type
Description
Required
data
​
Can be one of the following:
List[Any]
Callable
​
​
Can be one of the following:
A list of items. See example A.
A function that returns a list of items. See example B.
Required if handler is not set.
handler
Callable[..., None]
The function that updates the state of the control.
Required if data is not set.
selected
Can be one of the following:
int
List[int]
Can be one of the following:
An index of the currently selected item. Only if multiple set to False.
A list of indexes of the currently selected items. Only if multiple set to True.
No
multiple
bool
True if multiple selection is allowed. False by default.
No
label
str
The caption of the control.
No
depends
Can be one of the following:
List[Control]
Control
The other controls this control depends on. 
No
require_apply
bool
True if the field requires an Apply button to be clicked for the application to update the output. True by default.
No
optional
bool
True if the filed's value is required for the application to provide the output. False by default. If it's False, the data is empty, and the Apply button is required, the Apply button will be disabled.
No
CheckBox
dstack.controls.CheckBox
Parameter
Type
Description
Required
data
Can be one of the following:
bool
Callable
The initial value of the control.
Required if handler is not set.
handler
Callable
The function that updates the state of the control.
Required if data is not set.
label
str
The caption of the control.
No
depends
Can be one of the following:
List[Control]
Control
The other controls this control depends on. 
No

🧩 Concepts

Outputs

Last updated 3 weeks ago

Parameter	Type	Description	Required
`data`	Can be one of the following: `str` `Callable[[], str]`	The initial text value of the control.	Required if `handler` is not set.
`handler`	`Callable[..., None]`	The function that updates the state of the control.	Required if `data` is not set.
`long`	`bool`	`True` if the field may contain long values (text paragraphs). `False` by default.	No
`label`	`str`	The caption of the control.	No
`depends`	Can be one of the following: `List[Control]` `Control`	The other controls this control depends on.	No
`require_apply`	bool	`True` if the field requires an `Apply` button to be clicked for the application to update the output. `True` by default.	No
`optional`	`bool`	`True` if the filed's value is required for the application to provide the output. `False` by default. If it's `False,` the `data` is empty, and the Apply button is required, the `Apply` button will be disabled.	No

Parameter	Type	Description	Required
`data`	Can be one of the following: `List[Any]` `Callable`	Can be one of the following: A list of items. See example A. A function that returns a list of items. See example B.	Required if `handler` is not set.
`handler`	`Callable[..., None]`	The function that updates the state of the control.	Required if `data` is not set.
`selected`	Can be one of the following: `int` `List[int]`	Can be one of the following: An index of the currently selected item. Only if `multiple` set to `False`. A list of indexes of the currently selected items. Only if `multiple` set to `True`.	No
`multiple`	`bool`	`True` if multiple selection is allowed. `False` by default.	No
`label`	`str`	The caption of the control.	No
`depends`	Can be one of the following: `List[Control]` `Control`	The other controls this control depends on.	No
`require_apply`	bool	`True` if the field requires an `Apply` button to be clicked for the application to update the output. `True` by default.	No
`optional`	bool	`True` if the filed's value is required for the application to provide the output. `False` by default. If it's `False,` the `data` is empty, and the Apply button is required, the `Apply` button will be disabled.	No