Widgets

Widgets are HTML controls deck.gl overlays on the canvas — zoom buttons, a compass, a screenshot button, a popup. All 15 are available, generated from deck.gl’s own prop tables.

Pass them to Deck with the widgets keyword:

Deck(layer, widgets = [ZoomWidget(), CompassWidget()])

Widgets are styled by a deck.gl stylesheet that pages include only when they actually contain a widget. Every example below sits on a Carto basemap, passed as map_style — see Getting Started.

Common Props

Every widget accepts these:

Prop Default Description
id per widget Identifier, unique within a deck
placement per widget "top-left", "top-right", "bottom-left", "bottom-right"
style Dict() Inline CSS, including the --button-* custom properties
class_name "" Extra CSS class
view_id nothing Bind the widget to one view in a multi-view deck

The tables below list what each widget adds on top of those.

Camera

ZoomWidget

Zoom in and out buttons.

demo(ZoomWidget())

In addition to the common props:

Prop
on_zoom
orientation
transition_duration
zoom_axis
zoom_in_label
zoom_out_label

Descriptions and accepted values are in the deck.gl widget reference.

Lay the buttons out horizontally and move them:

demo(ZoomWidget(placement = "bottom-left", orientation = "horizontal",
                transition_duration = 400))

CompassWidget

A compass rose showing the current bearing. Click it to reset to north, then to flatten the pitch.

demo(CompassWidget(); pitch = 45, bearing = -30)

In addition to the common props:

Prop
label
on_reset
transition_duration

Descriptions and accepted values are in the deck.gl widget reference.

GimbalWidget

Pitch and bearing together, drawn as a gimbal. Click to reset both.

demo(GimbalWidget(); pitch = 50, bearing = 20)

In addition to the common props:

Prop
label
on_reset
stroke_width
transition_duration

Descriptions and accepted values are in the deck.gl widget reference.

ResetViewWidget

Returns the camera to where it started. Give it an explicit initial_view_state to reset somewhere other than the deck’s own.

demo(ResetViewWidget(), ZoomWidget())

In addition to the common props:

Prop
initial_view_state
label
on_reset

Descriptions and accepted values are in the deck.gl widget reference.

ScrollbarWidget

A scrollbar that pans the view within content_bounds, given as two corners, [[min_lng, min_lat], [max_lng, max_lat]].

demo(
    ScrollbarWidget(content_bounds = [[-122.6, 37.6], [-122.3, 37.9]],
                    orientation = "vertical", placement = "top-right"),
    ScrollbarWidget(id = "scroll-x", content_bounds = [[-122.6, 37.6], [-122.3, 37.9]],
                    orientation = "horizontal", placement = "bottom-left"),
)

Two widgets of the same type need distinct ids, as above.

In addition to the common props:

Prop
capture_wheel
content_bounds
decorations
end_button_aria_label
orientation
page_size
start_button_aria_label
step_size

Descriptions and accepted values are in the deck.gl widget reference.

Display

FullscreenWidget

Expands the deck’s container to fill the screen.

demo(FullscreenWidget())

In a notebook or on this page the deck lives in an iframe, so fullscreen applies to that frame.

In addition to the common props:

Prop
container
enter_label
exit_label
on_fullscreen_change

Descriptions and accepted values are in the deck.gl widget reference.

ThemeWidget

Switches the widgets between light and dark. initial_theme_mode may be "auto", "light", or "dark"; light_mode_theme and dark_mode_theme hold the CSS custom properties each mode applies.

demo(ThemeWidget(initial_theme_mode = "auto"), ZoomWidget(), CompassWidget())

In addition to the common props:

Prop
dark_mode_label
dark_mode_theme
initial_theme_mode
light_mode_label
light_mode_theme
on_theme_mode_change
theme_mode

Descriptions and accepted values are in the deck.gl widget reference.

ScreenshotWidget

Downloads the canvas as an image.

demo(ScreenshotWidget(filename = "map.png", image_format = "image/png"))

In addition to the common props:

Prop
filename
image_format
label
on_capture

Descriptions and accepted values are in the deck.gl widget reference.

LoadingWidget

A spinner shown while any layer is still fetching data. It stays hidden otherwise, so it is invisible on a deck whose data is already embedded.

demo(LoadingWidget(label = "Loading…"))

In addition to the common props:

Prop
label
on_loading_change

Descriptions and accepted values are in the deck.gl widget reference.

Information

InfoWidget

A tooltip anchored to the picked object. get_tooltip is a JavaScript function of the picking info, and mode is "hover" or "click".

demo(InfoWidget(
    mode = "click",
    get_tooltip = JS("info => info.index >= 0 ? {html: `<b>index</b> \${info.index}`} : null"),
))

For the common case of showing a few columns, the layer’s tooltip prop is simpler — it ships the columns for you and needs no JavaScript:

ScatterplotLayer(data = points, get_position = [:lng, :lat], tooltip = [:name, :size])

In addition to the common props:

Prop
arrow
get_tooltip
mode
offset

Descriptions and accepted values are in the deck.gl widget reference.

PopupWidget

A popup pinned to a coordinate. content is HTML.

demo(PopupWidget(
    position = [-122.44, 37.77],
    content = "<b>Downtown</b><br>Pinned to a coordinate.",
    default_is_open = true,
    close_button = true,
))

In addition to the common props:

Prop
arrow
close_button
close_on_click_outside
content
default_is_open
marker
offset
on_open_change
position

Descriptions and accepted values are in the deck.gl widget reference.

ContextMenuWidget

A right-click menu. Each entry is a label and a key, and on_menu_item_selected receives the key.

demo(ContextMenuWidget(
    menu_items = [
        Dict("label" => "Zoom in",   "key" => "zoom-in"),
        Dict("label" => "Copy point", "key" => "copy"),
    ],
    on_menu_item_selected = JS("key => console.log('selected', key)"),
))

Right-click the map to open it.

In addition to the common props:

Prop
arrow
get_menu_items
menu_items
offset
on_menu_item_selected

Descriptions and accepted values are in the deck.gl widget reference.

Custom Controls

These three are building blocks: they render a control and hand the event back to JavaScript, so what they do is up to you.

IconWidget

A button with your own icon. icon is an image URL — a file, or an inlined SVG as here.

demo(IconWidget(
    icon = star_icon,
    label = "Say hello",
    on_click = JS("() => console.log('icon widget clicked')"),
))

In addition to the common props:

Prop
color
icon
label
on_click

Descriptions and accepted values are in the deck.gl widget reference.

ToggleWidget

A two-state button, with a separate icon and label for the on state.

demo(ToggleWidget(
    icon = dot_icon,    label = "Markers off",
    on_icon = star_icon, on_label = "Markers on",
    initial_checked = false,
    on_change = JS("checked => console.log('checked:', checked)"),
))

In addition to the common props:

Prop
color
icon
initial_checked
label
on_change
on_color
on_icon
on_label

Descriptions and accepted values are in the deck.gl widget reference.

SelectorWidget

A dropdown. options is a list of label/value pairs.

demo(SelectorWidget(
    options = [
        Dict("label" => "Orange", "value" => "orange"),
        Dict("label" => "Blue",   "value" => "blue"),
    ],
    initial_value = "orange",
    on_change = JS("value => console.log('picked', value)"),
))

Reacting to a selection means changing layer props from JavaScript. For anything driven from Julia, rebuild the Deck and re-render instead.

In addition to the common props:

Prop
initial_value
on_change
options

Descriptions and accepted values are in the deck.gl widget reference.

Combining Widgets

Widgets stack in the order given, grouped by placement.

demo(
    ZoomWidget(placement = "top-left"),
    CompassWidget(placement = "top-left"),
    ResetViewWidget(placement = "top-left"),
    FullscreenWidget(placement = "top-right"),
    ScreenshotWidget(placement = "top-right"),
    ThemeWidget(placement = "bottom-right");
    pitch = 40, bearing = -25,
)

Every Widget

Generated from deck.gl v9.3.11:

Widget Extra props
CompassWidget label, on_reset, transition_duration
ContextMenuWidget arrow, get_menu_items, menu_items, offset, on_menu_item_selected
FullscreenWidget container, enter_label, exit_label, on_fullscreen_change
GimbalWidget label, on_reset, stroke_width, transition_duration
IconWidget color, icon, label, on_click
InfoWidget arrow, get_tooltip, mode, offset
LoadingWidget label, on_loading_change
PopupWidget arrow, close_button, close_on_click_outside, content, default_is_open, marker, offset, on_open_change, position
ResetViewWidget initial_view_state, label, on_reset
ScreenshotWidget filename, image_format, label, on_capture
ScrollbarWidget capture_wheel, content_bounds, decorations, end_button_aria_label, orientation, page_size, start_button_aria_label, step_size
SelectorWidget initial_value, on_change, options
ThemeWidget dark_mode_label, dark_mode_theme, initial_theme_mode, light_mode_label, light_mode_theme, on_theme_mode_change, theme_mode
ToggleWidget color, icon, initial_checked, label, on_change, on_color, on_icon, on_label
ZoomWidget on_zoom, orientation, transition_duration, zoom_axis, zoom_in_label, zoom_out_label