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