Elements

This page describes every available element style and its configuration keys. Keys shown in bold are required. All others are optional.

Common keys shared by all (or most) elements are described in Configuration.

---

Edit box

style: edit

A single-line text input. The variable type (str, int, or float) is inferred from the variable’s initial value. Numeric inputs are right-aligned and highlighted red on invalid input.

Key	Type	Default	Description
position	dict		Element placement; see Positioning elements
variable	str		Variable name
variable_group	str	inherited	Variable group
method	str		Callback on editing finished
text	str / dict	""	Label
text_position	str	"left"	Label placement: left, right, above, above-center, above-left
tooltip	str / dict	""	Tooltip text
enable	bool	true	Whether the field is editable

Example:

- style: edit
  position: {x: 120, y: 40, width: 100, height: 24}
  variable: grid_resolution
  variable_group: model
  method: update_grid
  text: Resolution (m)
  tooltip: Grid cell size in metres

---

Spin box

style: spinbox

A numeric input with up/down arrow buttons. Automatically uses an integer spinbox or a floating-point spinbox depending on the type of the linked variable.

Key	Type	Default	Description
position	dict		Element placement
variable	str		Variable name (type determines int vs float spinbox)
variable_group	str	inherited	Variable group
method	str		Callback fired when the user stops changing the value
minimum	int / float	0	Minimum allowed value
maximum	int / float	100	Maximum allowed value
step	int / float	1 (int) / 0.1 (float)	Step size per arrow click
decimals	int	2	Number of decimal places (float spinbox only)
suffix	str	""	Unit string appended to the displayed value, e.g. " m"
text	str / dict	""	Label
text_position	str	"left"	Label placement
tooltip	str / dict	""	Tooltip text
enable	bool	true	Whether the spinbox is interactive

Example:

- style: spinbox
  position: {x: 120, y: 40, width: 120, height: 24}
  variable: grid_resolution
  variable_group: model
  minimum: 10
  maximum: 10000
  step: 10
  suffix: " m"
  text: Resolution
  method: update_grid

---

Text

style: text

A read-only label that displays the value of a variable as a string. Updated automatically when the variable changes.

Key	Type	Default	Description
position	dict		Element placement
variable	str		Variable whose value is displayed
variable_group	str	inherited	Variable group
text	str / dict	""	Static text (use variable for a dynamic value)

Example:

- style: text
  position: {x: 10, y: 10, width: 300, height: 20}
  variable: status_message

---

Push button

style: pushbutton

A clickable button that triggers a callback.

Key	Type	Default	Description
position	dict		Element placement
text	str / dict		Button label
method	str		Callback on click
icon	str		Path to an image shown on the button
tooltip	str / dict	""	Tooltip text
enable	bool	true	Whether the button is clickable

Example:

- style: pushbutton
  position: {x: 10, y: 10, width: 120, height: 28}
  text: Run Model
  method: run_model
  tooltip: Start the simulation

---

Pop-up menu

style: popupmenu

A dropdown (combo box) from which the user selects one item.

Items can be defined as a static list in the YAML or as a variable that is updated at runtime.

The select key controls what value is stored in the variable:

• "item" — stores the value from option_value corresponding to the selected index

• "index" — stores the zero-based index of the selected item

Key	Type	Default	Description
position	dict		Element placement
variable	str		Variable that stores the selected item or index
variable_group	str	inherited	Variable group
option_string	list / dict		Display strings. Static list or {variable, variable_group}
option_value	list / dict		Values associated with each string. Static list or {variable, variable_group}
select	str	"item"	What to store: "item" or "index"
method	str		Callback on selection change
text	str / dict	""	Label
text_position	str	"left"	Label placement
tooltip	str / dict	""	Tooltip
enable	bool	true

Example (static list):

- style: popupmenu
  position: {x: 100, y: 40, width: 120, height: 24}
  variable: operator
  select: item
  option_string: ["+", "-", "*", "/"]
  option_value: ["add", "subtract", "multiply", "divide"]
  method: calculate

Example (dynamic list from variables):

- style: popupmenu
  position: {x: 100, y: 40, width: 120, height: 24}
  variable: scenario
  select: item
  option_string: {variable: scenario_names}
  option_value: {variable: scenario_ids}
  method: change_scenario

---

List box

style: listbox

A scrollable list from which the user selects one or more items. The select and multiselection keys work the same way as for the pop-up menu.

Key	Type	Default	Description
position	dict		Element placement
variable	str		Selected item/index (or list of them when multiselection: true)
variable_group	str	inherited	Variable group
option_string	list / dict		Display strings
option_value	list / dict		Associated values
select	str	"item"	"item" or "index"
multiselection	bool	false	Allow multiple selections
method	str		Callback on selection change
text	str / dict	""	Label
text_position	str	"left"	Label placement
tooltip	str / dict	""	Tooltip
enable	bool	true

---

Check box

style: checkbox

A toggle that stores True or False in the linked variable.

Key	Type	Default	Description
position	dict		Element placement
variable	str		Boolean variable
variable_group	str	inherited	Variable group
text	str / dict	""	Checkbox label (shown to the right of the checkbox)
method	str		Callback on toggle
tooltip	str / dict	""	Tooltip
enable	bool	true

Example:

- style: checkbox
  position: {x: 10, y: 40, width: 150, height: 20}
  variable: show_grid
  text: Show grid
  method: toggle_grid

---

Radio button group

style: radiobuttongroup

A group of mutually exclusive radio buttons.

Key	Type	Default	Description
position	dict		Element placement
variable	str		Variable storing the selected value
variable_group	str	inherited	Variable group
option_string	list		Label for each radio button
option_value	list		Value stored when each button is selected
method	str		Callback on selection change
enable	bool	true

Example:

- style: radiobuttongroup
  position: {x: 10, y: 10, width: 200, height: 60}
  variable: interpolation_method
  option_string: [Nearest, Linear, Cubic]
  option_value: [nearest, linear, cubic]
  method: change_interpolation

---

Slider

style: slider

A horizontal slider for selecting a value in a numeric range.

Key	Type	Default	Description
position	dict		Element placement
variable	str		Variable storing the current value (integer)
variable_group	str	inherited	Variable group
minimum	int	0	Minimum value
maximum	int	100	Maximum value
method	str		Callback fired when the user releases the slider
slide_method	str		Callback fired continuously while dragging
text	str / dict	""	Label
enable	bool	true

Example:

- style: slider
  position: {x: 200, y: 40, width: 300, height: 24}
  variable: year
  minimum: 2000
  maximum: 2100
  slide_method: update_year_label
  method: reload_data

---

Date/time edit

style: datetimeedit

A date and time picker widget.

Key	Type	Default	Description
position	dict		Element placement
variable	str		Variable storing the datetime value
variable_group	str	inherited	Variable group
method	str		Callback on value change
text	str / dict	""	Label
text_position	str	"left"	Label placement

---

Table view (read-only)

style: tableview

A read-only table populated from a pandas.DataFrame stored in a variable. Supports row or column selection, sorting by column header click, and single or multi-selection. The table cannot be edited by the user — use style: table for an editable table.

Key	Type	Default	Description
position	dict		Element placement
variable	str		Variable storing the selected row index or indices
variable_group	str	inherited	Variable group
option_value	dict		{variable, variable_group} pointing to the DataFrame variable
selection_type	str	"single"	"none", "single", "multiple", "extended"
selection_direction	str	"row"	"row" or "column"
sortable	bool	true	Whether clicking a column header sorts the table
method	str		Callback on row/column selection
text	str / dict	""	Label
text_position	str	"above"	Label placement

Example:

- style: tableview
  position: {x: 10, y: 10, width: -10, height: 200}
  text: Available scenarios
  text_position: above
  variable: selected_row
  option_value: {variable: scenarios_df}
  selection_type: single
  method: select_scenario

---

Table (editable)

style: table

An editable table backed by a pandas.DataFrame. Users can double-click (or press a key) to edit cell values in place. The edited value is parsed back to the column’s original dtype (int, float, or str). Invalid input is automatically reverted.

Key	Type	Default	Description
position	dict		Element placement
option_value	dict		{variable, variable_group} pointing to the DataFrame variable
variable_group	str	inherited	Variable group
editable	bool	false	When true, cells can be edited by double-clicking. When false the table behaves as read-only with row selection.
sortable	bool	false	Whether clicking a column header sorts the table
method	str		Callback fired after a cell is edited (or a row is selected when not editable)
text	str / dict	""	Label displayed below the table

Example:

- style: table
  position: {x: 10, y: 10, width: -10, height: 150}
  text: Parameters
  option_value: {variable: dataframe}
  editable: true
  method: on_cell_edit

Python setup:

import pandas as pd

df = pd.DataFrame({"name": ["a1", "a2"], "value": [1.0, 2.0]})
app.gui.setvar("mygroup", "dataframe", df)

---

File/directory chooser buttons

Three button styles open system file/directory dialogs and store the chosen path in a variable.

Open file: style: pushselectfile

Open directory: style: pushselectdir

Save file: style: pushsavefile

Key	Type	Default	Description
position	dict		Element placement
variable	str		Variable that receives the chosen path
variable_group	str	inherited	Variable group
text	str / dict		Button label
title	str	"Select File"	Dialog window title
filter	str	"All Files (*.*)"	File type filter, e.g. "NetCDF (*.nc)"
full_path	bool	false	Store the full path; if false stores only the filename
method	str		Callback after a path is selected

Example:

- style: pushselectfile
  position: {x: 10, y: 40, width: 160, height: 24}
  variable: bathymetry_file
  text: Select bathymetry file
  title: Open bathymetry file
  filter: NetCDF (*.nc);;All Files (*.*)
  method: load_bathymetry

---

Web view

style: webpage

Embeds a web browser (PySide6 WebEngine) that displays a URL.

Key	Type	Default	Description
position	dict		Element placement
url	str / dict	""	URL to load (static or from variable)

Example:

- style: webpage
  url: https://guitares.readthedocs.io/
  position: {x: 10, y: 10, width: -10, height: -10}

---

Frame (panel)

style: panel

A container that groups child elements. Frames can optionally show a border with a title and can be made collapsible.

Key	Type	Default	Description
position	dict		Placement of the frame within its parent
title	str		Border title (no border shown if omitted)
element	list		Child elements (same syntax as the top-level element list)
collapse	bool	false	Make the frame collapsible
collapsed	bool	false	Initial collapsed state
fraction_expanded	float	0.5	Fraction of parent taken when expanded (used with collapse: true)
fraction_collapsed	float	1.0	Fraction of parent taken when collapsed
id	str		Unique identifier (required for collapsible frames)

Example:

- style: panel
  title: Model settings
  position: {x: 10, y: 10, width: 300, height: -10}
  element:
  - style: spinbox
    position: {x: 10, y: 10, width: 120, height: 24}
    variable: dx
    text: dx
    suffix: " m"

---

Tab panel

style: tabpanel

A container with multiple named tabs, each holding its own set of child elements. See Using tab panels for full documentation.

Map

style: map (or style: maplibre / style: mapbox)

An interactive map widget. See The Map Widget for full documentation.