First steps 9: Using widgets#

In the previous first steps guides, you used different sources and structures to import and filter data.

In this section, you will add interactive widgets to your plots.

Adding widgets#

Widgets are additional visual elements that you can include in your visualization. Use widgets to display additional information or to interactively control elements of your Bokeh document, for example:

This Bokeh document combines a plot with three widgets:

A Div widget to display HTML text
A Spinner widget to select a numeric value
A RangeSlider widget to adjust a range

See Bokeh’s built-in widgets in the user guide for a complete list of Bokeh’s widgets.

Follow these steps to recreate the example from above:

Import the Div, RangeSlider, and Spinner widgets from bokeh.models:
```
from bokeh.models import Div, RangeSlider, Spinner
```

Set up your data, your figure, and your renderer:

x = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
y = [4, 5, 5, 7, 2, 6, 4, 9, 1, 3]

p = figure(x_range=(1,9), width=500, height=250)
points = p.circle(x=x, y=y, size=30, fill_color="#21a7df")

Create a Div object and pass it some HTML code as a string:

div = Div(
    text="""
        <p>Select the circle's size using this control element:</p>
        """,
    width=200,
    height=30,
)

Create a Spinner object:

spinner = Spinner(
    title="Circle size",  # a string to display above the widget
    low=0,  # the lowest possible number to pick
    high=60,  # the highest possible number to pick
    step=5,  # the increments by which the number can be adjusted
    value=points.glyph.size,  # the initial value to display in the widget
    width=200,  #  the width of the widget in pixels
)

To link the value generated by the spinner to the size property of your glyph, use the js_link() function. This function uses JavaScript to interactively link two Bokeh models. The first argument you pass to this function is the attribute of your spinner ("value") that you want to link to your circle glyphs. The second attribute is the glyph you want to link to your spinner (points.glyph). The third argument is the property of your glyph that you want to link to your spinner’s value:
```
spinner.js_link("value", points.glyph, "size")
```

Create a RangeSlider object:

range_slider = RangeSlider(
    title="Adjust x-axis range", # a title to display above the slider
    start=0,  # set the minimum value for the slider
    end=10,  # set the maximum value for the slider
    step=1,  # increments for the slider
    value=(p.x_range.start, p.x_range.end),  # initial values for slider
)

To link the values generated by the RangeSlider to the existing plot, use the js_link() function again. This time, however, you need to assign two values at once: the beginning of the plot’s x-axis and the end of its x-axis. The RangeSlider returns a tuple of those two values. Therefore, you need to use the attr_selector of the js_link() function to tell Bokeh which part of the Tuple to assign to either the start or the end of the plot’s x-axis:
```
range_slider.js_link("value", p.x_range, "start", attr_selector=0)
range_slider.js_link("value", p.x_range, "end", attr_selector=1)
```

Create a layout with all the elements of your dashboard and display it in a browser:

layout = layout([
    [div, spinner],
    [range_slider],
    [p],
])

show(layout)

This is what the completed example looks like:

from bokeh.layouts import layout
from bokeh.models import Div, RangeSlider, Spinner
from bokeh.plotting import figure, show

# prepare some data
x = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
y = [4, 5, 5, 7, 2, 6, 4, 9, 1, 3]

# create plot with circle glyphs
p = figure(x_range=(1, 9), width=500, height=250)
points = p.circle(x=x, y=y, size=30, fill_color="#21a7df")

# set up textarea (div)
div = Div(
    text="""
          <p>Select the circle's size using this control element:</p>
          """,
    width=200,
    height=30,
)

# set up spinner
spinner = Spinner(
    title="Circle size",
    low=0,
    high=60,
    step=5,
    value=points.glyph.size,
    width=200,
)
spinner.js_link("value", points.glyph, "size")

# set up RangeSlider
range_slider = RangeSlider(
    title="Adjust x-axis range",
    start=0,
    end=10,
    step=1,
    value=(p.x_range.start, p.x_range.end),
)
range_slider.js_link("value", p.x_range, "start", attr_selector=0)
range_slider.js_link("value", p.x_range, "end", attr_selector=1)

# create layout
layout = layout(
    [
        [div, spinner],
        [range_slider],
        [p],
    ],
)

# show result
show(layout)

Using widgets with a Bokeh server#

Another way to use widgets is with a Bokeh server application. Bokeh includes a standalone server component. Use the Bokeh server if you want to connect your JavaScript-based visualization running in a browser to Python code running on a server.

Use this command on a command line to start Bokeh in server mode:

bokeh serve

You can use Bokeh Server to build complex dashboards and interactive applications. Some of the capabilities of the Bokeh server include:

UI widgets and plot selections that drive computations and plot updates
Streaming live data to automatically updating plots
Intelligent server-side downsampling of large datasets
Sophisticated glyph re-writing and transformations for “Big Data”
Plot and dashboard publishing for wider audiences

This is an example of a simple Bokeh server app. Adjust the sliders in the widgets on the left to change the sine wave on the right:

Find the source code for this Bokeh server app at examples/server/app/slider.py. For more examples of Bokeh server applications, see the Gallery.

Next steps#

Congratulations, you have completed all of Bokeh’s first steps guides!

More information about Bokeh is available in the user guide. For more in-depth information about all aspects of Bokeh, see the reference guide.

For more examples of what you can do with Bokeh, check the Gallery and the examples directory in Bokeh’s GitHub repository.

Finally, on the Bokeh community page, you can find links and information about asking for help and contributing to Bokeh and the Bokeh community.