GUI API¶

class viser.GuiApi[source]¶

Interface for working with the 2D GUI in viser.

Used by both our global server object, for sharing the same GUI elements with all clients, and by individual client handles.

reset() → None[source]¶

Reset the GUI.

Return type:: None

set_panel_label(label: str | None) → None[source]¶

Set the main label that appears in the GUI panel.

Parameters:: label (str | None) – The new label.
Return type:: None

configure_theme(*, titlebar_content: TitlebarConfig | None = None, control_layout: Literal['floating', 'collapsible', 'fixed'] = 'floating', control_width: Literal['small', 'medium', 'large'] = 'medium', dark_mode: bool = False, show_logo: bool = True, show_share_button: bool = True, brand_color: tuple[int, int, int] | None = None) → None[source]¶

Configures the visual appearance of the viser front-end.

Parameters:

titlebar_content (TitlebarConfig | None) – Optional configuration for the title bar.
control_layout (Literal['floating', 'collapsible', 'fixed']) – The layout of control elements, options are “floating”, “collapsible”, or “fixed”.
control_width (Literal['small', 'medium', 'large']) – The width of control elements, options are “small”, “medium”, or “large”.
dark_mode (bool) – A boolean indicating if dark mode should be enabled.
show_logo (bool) – A boolean indicating if the logo should be displayed.
show_share_button (bool) – A boolean indicating if the share button should be displayed.
brand_color (tuple[int, int, int] | None) – An optional tuple of integers (RGB) representing the brand color.

Return type:

None

add_folder(label: str, order: float | None = None, expand_by_default: bool = True, visible: bool = True) → GuiFolderHandle[source]¶

Add a folder, and return a handle that can be used to populate it.

Parameters:

label (str) – Label to display on the folder.
order (float | None) – Optional ordering, smallest values will be displayed first.
expand_by_default (bool) – Open the folder by default. Set to False to collapse it by default.
visible (bool) – Whether the component is visible.

Returns:

A handle that can be used as a context to populate the folder.

Return type:

GuiFolderHandle

add_modal(title: str, order: float | None = None) → GuiModalHandle[source]¶

Show a modal window, which can be useful for popups and messages, then return a handle that can be used to populate it.

Parameters:

title (str) – Title to display on the modal.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used as a context to populate the modal.

Return type:

GuiModalHandle

add_tab_group(order: float | None = None, visible: bool = True) → GuiTabGroupHandle[source]¶

Add a tab group.

Parameters:

order (float | None) – Optional ordering, smallest values will be displayed first.
visible (bool) – Whether the component is visible.

Returns:

A handle that can be used as a context to populate the tab group.

Return type:

GuiTabGroupHandle

add_markdown(content: str, image_root: Path | None = None, order: float | None = None, visible: bool = True) → GuiMarkdownHandle[source]¶

Add markdown to the GUI.

Parameters:

content (str) – Markdown content to display.
image_root (Path | None) – Optional root directory to resolve relative image paths.
order (float | None) – Optional ordering, smallest values will be displayed first.
visible (bool) – Whether the component is visible.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiMarkdownHandle

add_html(content: str, order: float | None = None, visible: bool = True) → GuiHtmlHandle[source]¶

Add HTML to the GUI.

Parameters:

content (str) – HTML content to display.
order (float | None) – Optional ordering, smallest values will be displayed first.
visible (bool) – Whether the component is visible.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiHtmlHandle

add_image(image: ndarray, label: str | None = None, format: Literal['png', 'jpeg'] = 'jpeg', jpeg_quality: int | None = None, order: float | None = None, visible: bool = True) → GuiImageHandle[source]¶

Parameters:

image (ndarray)
label (str | None)
format (Literal['png', 'jpeg'])
jpeg_quality (int | None)
order (float | None)
visible (bool)

Return type:

GuiImageHandle

add_plotly(figure: go.Figure, aspect: float = 1.0, order: float | None = None, visible: bool = True) → GuiPlotlyHandle[source]¶

Add a Plotly figure to the GUI. Requires the plotly package to be installed.

Note

Updates to Plotly figures can be slow when you have many plots or frequent updates. For real-time visualization, consider using add_uplot() instead.

Parameters:

figure (go.Figure) – Plotly figure to display.
aspect (float) – Aspect ratio of the plot in the control panel (width/height).
order (float | None) – Optional ordering, smallest values will be displayed first.
visible (bool) – Whether the component is visible.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiPlotlyHandle

add_uplot(data: tuple[ndarray, ...], series: tuple[Series, ...], *, mode: Literal[1, 2] | None = None, title: str | None = None, bands: tuple[Band, ...] | None = None, scales: dict[str, Scale] | None = None, axes: tuple[Axis, ...] | None = None, legend: Legend | None = None, cursor: Cursor | None = None, focus: Focus | None = None, aspect: float = 1.0, order: float | None = None, visible: bool = True) → GuiUplotHandle[source]¶

Add a uPlot chart to the GUI for high-performance time-series visualization.

uPlot is optimized for plotting large datasets with smooth pan/zoom interactions. All configuration options follow the standard uPlot API. For comprehensive documentation, see: https://github.com/leeoniya/uPlot/tree/1.6.32/docs

Note

Configuration types are exposed under the viser.uplot module for convenience: viser.uplot.Series, viser.uplot.Scale, viser.uplot.Axis, viser.uplot.Band, viser.uplot.Legend, viser.uplot.Cursor, and viser.uplot.Focus. These are TypedDict types; standard dictionaries can also be used.

Parameters:

data (tuple[ndarray, ...]) – Tuple of 1D numpy arrays containing chart data. The first array provides x-axis values, and subsequent arrays contain y-axis data for each series. All arrays must have identical length. Minimum 2 arrays.
series (tuple[Series, ...]) – Series configuration objects defining visual appearance and behavior. Must match the length of data tuple.
mode (Literal[1, 2] | None) – Chart layout mode. 1 = aligned (default) where all series share axes, 2 = faceted where each series gets its own subplot panel.
title (str | None) – Chart title displayed at the top.
bands (tuple[Band, ...] | None) – High/low range visualizations between data series. Useful for showing confidence intervals, error bounds, or min/max ranges. Each band connects two adjacent series indices.
scales (dict[str, Scale] | None) – Scale definitions controlling data-to-pixel mapping and axis ranges. Key features include auto-ranging, manual min/max, time-based scaling, and logarithmic distributions. Multiple scales enable dual-axis charts.
axes (tuple[Axis, ...] | None) – Axis configuration for labels, ticks, grids, and positioning. Controls which side axes appear (top/right/bottom/left), tick formatting, grid line styling, and spacing between tick marks.
legend (Legend | None) – Legend display options including positioning, styling, and custom value formatting functions for hover states.
cursor (Cursor | None) – Interactive cursor behavior including hover proximity detection, drag-to-zoom, and crosshair appearance. Controls how users interact with the chart through mouse/touch.
focus (Focus | None) – Visual highlighting when hovering over series. Controls the alpha transparency of non-focused series to emphasize the active one.
aspect (float) – Width-to-height ratio for the chart display in the control panel. 1.0 creates a square chart, values > 1.0 create wider charts.
order (float | None) – Display ordering relative to other GUI elements (lower values first).
visible (bool) – Whether the chart is visible in the interface.

Returns:

A handle for programmatically updating chart properties and data.

Return type:

GuiUplotHandle

add_button(label: str, disabled: bool = False, visible: bool = True, hint: str | None = None, color: Literal['dark', 'gray', 'red', 'pink', 'grape', 'violet', 'indigo', 'blue', 'cyan', 'green', 'lime', 'yellow', 'orange', 'teal'] | tuple[int, int, int] | None = None, icon: IconName | None = None, order: float | None = None) → GuiButtonHandle[source]¶

Add a button to the GUI. The value of this input is set to True every time it is clicked; to detect clicks, we can manually set it back to False.

Parameters:

label (str) – Label to display on the button.
visible (bool) – Whether the button is visible.
disabled (bool) – Whether the button is disabled.
hint (str | None) – Optional hint to display on hover.
color (Literal['dark', 'gray', 'red', 'pink', 'grape', 'violet', 'indigo', 'blue', 'cyan', 'green', 'lime', 'yellow', 'orange', 'teal'] | tuple[int, int, int] | None) – Optional color to use for the button.
icon (IconName | None) – Optional icon to display on the button.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiButtonHandle

add_upload_button(label: str, disabled: bool = False, visible: bool = True, hint: str | None = None, color: Literal['dark', 'gray', 'red', 'pink', 'grape', 'violet', 'indigo', 'blue', 'cyan', 'green', 'lime', 'yellow', 'orange', 'teal'] | tuple[int, int, int] | None = None, icon: IconName | None = None, mime_type: str = '*/*', order: float | None = None) → GuiUploadButtonHandle[source]¶

Add a button to the GUI. The value of this input is set to True every time it is clicked; to detect clicks, we can manually set it back to False.

Parameters:

label (str) – Label to display on the button.
visible (bool) – Whether the button is visible.
disabled (bool) – Whether the button is disabled.
hint (str | None) – Optional hint to display on hover.
color (Literal['dark', 'gray', 'red', 'pink', 'grape', 'violet', 'indigo', 'blue', 'cyan', 'green', 'lime', 'yellow', 'orange', 'teal'] | tuple[int, int, int] | None) – Optional color to use for the button.
icon (IconName | None) – Optional icon to display on the button.
mime_type (str) – Optional MIME type to filter the files that can be uploaded.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiUploadButtonHandle

add_button_group(label: str, options: Sequence[str], visible: bool = True, disabled: bool = False, hint: str | None = None, order: float | None = None) → GuiButtonGroupHandle[source]¶

Add a button group to the GUI.

Parameters:

label (str) – Label to display on the button group.
options (Sequence[str]) – Sequence of options to display as buttons.
visible (bool) – Whether the button group is visible.
disabled (bool) – Whether the button group is disabled.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiButtonGroupHandle

add_checkbox(label: str, initial_value: bool, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiCheckboxHandle[source]¶

Add a checkbox to the GUI.

Parameters:

label (str) – Label to display on the checkbox.
initial_value (bool) – Initial value of the checkbox.
disabled (bool) – Whether the checkbox is disabled.
visible (bool) – Whether the checkbox is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiCheckboxHandle

add_text(label: str, initial_value: str, multiline: bool = False, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiTextHandle[source]¶

Add a text input to the GUI.

Parameters:

label (str) – Label to display on the text input.
initial_value (str) – Initial value of the text input.
multiline (bool) – Whether the text input supports multiple lines, delimited with the n character.
disabled (bool) – Whether the text input is disabled.
visible (bool) – Whether the text input is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiTextHandle

add_number(label: str, initial_value: IntOrFloat, min: IntOrFloat | None = None, max: IntOrFloat | None = None, step: IntOrFloat | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiNumberHandle[IntOrFloat][source]¶

Add a number input to the GUI, with user-specifiable bound and precision parameters.

Parameters:

label (str) – Label to display on the number input.
initial_value (IntOrFloat) – Initial value of the number input.
min (IntOrFloat | None) – Optional minimum value of the number input.
max (IntOrFloat | None) – Optional maximum value of the number input.
step (IntOrFloat | None) – Optional step size of the number input. Computed automatically if not specified.
disabled (bool) – Whether the number input is disabled.
visible (bool) – Whether the number input is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiNumberHandle[IntOrFloat]

Add a length-2 vector input to the GUI.

Parameters:

label (str) – Label to display on the vector input.
initial_value (tuple[float, float] | ndarray) – Initial value of the vector input.
min (tuple[float, float] | ndarray | None) – Optional minimum value of the vector input.
max (tuple[float, float] | ndarray | None) – Optional maximum value of the vector input.
step (float | None) – Optional step size of the vector input. Computed automatically if not
disabled (bool) – Whether the vector input is disabled.
visible (bool) – Whether the vector input is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiVector2Handle

Add a length-3 vector input to the GUI.

Parameters:

label (str) – Label to display on the vector input.
initial_value (tuple[float, float, float] | ndarray) – Initial value of the vector input.
min (tuple[float, float, float] | ndarray | None) – Optional minimum value of the vector input.
max (tuple[float, float, float] | ndarray | None) – Optional maximum value of the vector input.
step (float | None) – Optional step size of the vector input. Computed automatically if not
disabled (bool) – Whether the vector input is disabled.
visible (bool) – Whether the vector input is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiVector3Handle

add_dropdown(label: str, options: Sequence[TLiteralString], initial_value: TLiteralString | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiDropdownHandle[TLiteralString][source]¶

add_dropdown(label: str, options: Sequence[TString], initial_value: TString | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiDropdownHandle[TString]

Add a dropdown to the GUI.

Parameters:

label – Label to display on the dropdown.
options – Sequence of options to display in the dropdown.
initial_value – Initial value of the dropdown.
disabled – Whether the dropdown is disabled.
visible – Whether the dropdown is visible.
hint – Optional hint to display on hover.
order – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

add_progress_bar(value: float, visible: bool = True, animated: bool = False, color: Literal['dark', 'gray', 'red', 'pink', 'grape', 'violet', 'indigo', 'blue', 'cyan', 'green', 'lime', 'yellow', 'orange', 'teal'] | tuple[int, int, int] | None = None, order: float | None = None) → GuiProgressBarHandle[source]¶

Add a progress bar to the GUI.

Parameters:

value (float) – Value of the progress bar. (0 - 100)
visible (bool) – Whether the progress bar is visible.
animated (bool) – Whether the progress bar is in a loading state (animated, striped).
color (Literal['dark', 'gray', 'red', 'pink', 'grape', 'violet', 'indigo', 'blue', 'cyan', 'green', 'lime', 'yellow', 'orange', 'teal'] | tuple[int, int, int] | None) – The color of the progress bar.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiProgressBarHandle

add_slider(label: str, min: IntOrFloat, max: IntOrFloat, step: IntOrFloat, initial_value: IntOrFloat, marks: tuple[IntOrFloat | tuple[IntOrFloat, str], ...] | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiSliderHandle[IntOrFloat][source]¶

Add a slider to the GUI. Types of the min, max, step, and initial value should match.

Parameters:

label (str) – Label to display on the slider.
min (IntOrFloat) – Minimum value of the slider.
max (IntOrFloat) – Maximum value of the slider.
step (IntOrFloat) – Step size of the slider.
initial_value (IntOrFloat) – Initial value of the slider.
marks (tuple[IntOrFloat | tuple[IntOrFloat, str], ...] | None) – tuple of marks to display below the slider. Each mark should either be a numerical or a (number, label) tuple, where the label is provided as a string.
disabled (bool) – Whether the slider is disabled.
visible (bool) – Whether the slider is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiSliderHandle[IntOrFloat]

add_multi_slider(label: str, min: IntOrFloat, max: IntOrFloat, step: IntOrFloat, initial_value: tuple[IntOrFloat, ...], min_range: IntOrFloat | None = None, fixed_endpoints: bool = False, marks: tuple[IntOrFloat | tuple[IntOrFloat, str], ...] | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiMultiSliderHandle[IntOrFloat][source]¶

Add a multi slider to the GUI. Types of the min, max, step, and initial value should match.

Parameters:

label (str) – Label to display on the slider.
min (IntOrFloat) – Minimum value of the slider.
max (IntOrFloat) – Maximum value of the slider.
step (IntOrFloat) – Step size of the slider.
initial_value (tuple[IntOrFloat, ...]) – Initial values of the slider.
min_range (IntOrFloat | None) – Optional minimum difference between two values of the slider.
fixed_endpoints (bool) – Whether the endpoints of the slider are fixed.
marks (tuple[IntOrFloat | tuple[IntOrFloat, str], ...] | None) – tuple of marks to display below the slider. Each mark should either be a numerical or a (number, label) tuple, where the label is provided as a string.
disabled (bool) – Whether the slider is disabled.
visible (bool) – Whether the slider is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiMultiSliderHandle[IntOrFloat]

add_rgb(label: str, initial_value: tuple[int, int, int], disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiRgbHandle[source]¶

Add an RGB picker to the GUI.

Parameters:

label (str) – Label to display on the RGB picker.
initial_value (tuple[int, int, int]) – Initial value of the RGB picker.
disabled (bool) – Whether the RGB picker is disabled.
visible (bool) – Whether the RGB picker is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiRgbHandle

add_rgba(label: str, initial_value: tuple[int, int, int, int], disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiRgbaHandle[source]¶

Add an RGBA picker to the GUI.

Parameters:

label (str) – Label to display on the RGBA picker.
initial_value (tuple[int, int, int, int]) – Initial value of the RGBA picker.
disabled (bool) – Whether the RGBA picker is disabled.
visible (bool) – Whether the RGBA picker is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiRgbaHandle