Styling visual attributes#

Applying Bokeh’s built-in themes#

Bokeh comes with five built-in themes to quickly change the appearance of one or more plots: caliber, dark_minimal, light_minimal, night_sky, and contrast.

To use one of the built-in themes, assign the name of the theme you want to use to the theme property of your document.

For example:

from bokeh.io import curdoc
from bokeh.plotting import figure, output_file, show

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

output_file("dark_minimal.html")

curdoc().theme = 'dark_minimal'

p = figure(title='dark_minimal', width=300, height=300)
p.line(x, y)

show(p)

For more examples and detailed information, see bokeh.themes.

Creating custom themes#

Themes in Bokeh are defined in YAML or JSON files. To create your own theme files, follow the format defined in bokeh.themes.Theme.

Using YAML, for example:

attrs:
    Figure:
        background_fill_color: '#2F2F2F'
        border_fill_color: '#2F2F2F'
        outline_line_color: '#444444'
    Axis:
        axis_line_color: !!null
    Grid:
        grid_line_dash: [6, 4]
        grid_line_alpha: .3
    Title:
        text_color: "white"

To use your custom theme in a Bokeh plot, load your YAML or JSON file into a bokeh.themes.Theme object:

from bokeh.themes import Theme
curdoc().theme = Theme(filename="./theme.yml")

Line properties#

line_color

color to use to stroke lines with

line_width

line stroke width in units of pixels

line_alpha

floating point between 0 (transparent) and 1 (opaque)

line_join

how path segments should be joined together

• 'miter'

• 'round'

• 'bevel'

line_cap

how path segments should be terminated

• 'butt'

• 'round'

• 'square'

line_dash

a line style to use

• 'solid'

• 'dashed'

• 'dotted'

• 'dotdash'

• 'dashdot'

• an array of integer pixel distances that describe the on-off pattern of dashing to use

• a string of spaced integers matching the regular expression ‘^(\d+(\s+\d+)*)?$’ that describe the on-off pattern of dashing to use

line_dash_offset

the distance in pixels into the line_dash that the pattern should start from

Fill properties#

fill_color

color to use to fill paths with

fill_alpha

floating point between 0 (transparent) and 1 (opaque)

Hatch properties#

hatch_color

color to use to stroke hatch patterns with

hatch_alpha

floating point between 0 (transparent) and 1 (opaque)

hatch_weight

line stroke width in units of pixels

hatch_scale

a rough measure of the “size” of a pattern. This value has different specific meanings, depending on the pattern.

hatch_pattern

a string name (or abbreviation) for a built-in pattern, or a string name of a pattern provided in hatch_extra. The built-in patterns are:

Built-in Hatch Patterns#

FullName	Abbreviation	Example
blank	" "
dot	"."
ring	"o"
horizontal_line	"-"
vertical_line	"|"
cross	"+"
horizontal_dash	'"'
vertical_dash	":"
spiral	"@"
right_diagonal_line	"/"
left_diagonal_line	"\\"
diagonal_cross	"x"
right_diagonal_dash	","
left_diagonal_dash	"`"
horizontal_wave	"v"
vertical_wave	">"
criss_cross	"*"

hatch_extra

a dict mapping string names to custom pattern implementations. The name can be referred to by hatch_pattern. For example, if the following value is set for hatch_extra:

hatch_extra={ 'mycustom': ImageURLTexture(url=...) }

then the name "mycustom" may be set as a hatch_pattern.

Text properties#

text_font

font name, e.g., 'times', 'helvetica'

text_font_size

font size in px, em, or pt, e.g., '16px', '1.5em'

text_font_style

font style to use

• 'normal' normal text

• 'italic' italic text

• 'bold' bold text

text_color

color to use to render text with

text_alpha

floating point between 0 (transparent) and 1 (opaque)

text_align

horizontal anchor point for text: 'left', 'right', 'center'

text_baseline

vertical anchor point for text

• 'top'

• 'middle'

• 'bottom'

• 'alphabetic'

• 'hanging'

Visible property#

Glyph renderers, axes, grids, and annotations all have a visible property. Use this property to turn them on and off.

from bokeh.io import output_file, show
from bokeh.plotting import figure

# We set-up a standard figure with two lines
p = figure(width=500, height=200, tools='')
visible_line = p.line([1, 2, 3], [1, 2, 1], line_color="blue")
invisible_line = p.line([1, 2, 3], [2, 1, 2], line_color="pink")

# We hide the xaxis, the xgrid lines, and the pink line
invisible_line.visible = False
p.xaxis.visible = False
p.xgrid.visible = False

output_file("styling_visible_property.html")

show(p)

This can be particularly useful in interactive examples with a Bokeh server or CustomJS.

from bokeh.io import output_file, show
from bokeh.layouts import layout
from bokeh.models import BoxAnnotation, Toggle
from bokeh.plotting import figure

output_file("styling_visible_annotation_with_interaction.html")

p = figure(width=600, height=200, tools='')
p.line([1, 2, 3], [1, 2, 1], line_color="#0072B2")
pink_line = p.line([1, 2, 3], [2, 1, 2], line_color="#CC79A7")

green_box = BoxAnnotation(left=1.5, right=2.5, fill_color='#009E73', fill_alpha=0.1)
p.add_layout(green_box)

# Use js_link to connect button active property to glyph visible property

toggle1 = Toggle(label="Green Box", button_type="success", active=True)
toggle1.js_link('active', green_box, 'visible')

toggle2 = Toggle(label="Pink Line", button_type="success", active=True)
toggle2.js_link('active', pink_line, 'visible')

show(layout([p], [toggle1, toggle2]))

Color properties#

Bokeh objects have several properties related to colors. Use those color properties to control the appearance of lines, fills, or text, for example.

Use one of these options to define colors in Bokeh:

• Any of the named CSS colors, such as 'green' or 'indigo'. You can also use the additional name 'transparent' (equal to '#00000000').

• An RGB(A) hex value, such as '#FF0000' (without alpha information) or '#44444444' (with alpha information).

• A CSS4 rgb(), rgba(), or hsl() color string, such as 'rgb(0 127 0 / 1.0)', 'rgba(255, 0, 127, 0.6)', or 'hsl(60deg 100% 50% / 1.0)'.

• A 3-tuple of integers (r, g, b) (where r, g, and b are integers between 0 and 255).

• A 4-tuple of (r, g, b, a) (where r, g, and b are integers between 0 and 255 and a is a floating-point value between 0 and 1).

• A 32-bit unsigned integer representing RGBA values in a 0xRRGGBBAA byte order pattern, such as 0xffff00ff or 0xff0000ff.

To define a series of colors, use an array of color data such as a list or the column of a ColumnDataSource. This also includes NumPy arrays.

For example:

import numpy as np

from bokeh.plotting import figure, output_file, show

output_file("specifying_colors.html")

x = [1, 2, 3]
y1 = [1, 4, 2]
y2 = [2, 1, 4]
y3 = [4, 3, 2]

# use a single RGBA color
single_color = (255, 0, 0, 0.5)

# use a list of different colors
list_of_colors = [
    "hsl(60deg 100% 50% / 1.0)",
    "rgba(0, 0, 255, 0.9)",
    "LightSeaGreen",
]

# use a series of color values as numpy array
numpy_array_of_colors = np.array(
    [
        0xFFFF00FF,
        0x00FF00FF,
        0xFF000088,
    ],
    np.uint32,
)

p = figure(title="Specifying colors")

# add glyphs to plot
p.line(x, y1, line_color=single_color)
p.circle(x, y2, radius=0.12, color=list_of_colors)
p.triangle(x, y3, size=30, fill_color=numpy_array_of_colors)

show(p)

In addition to specifying the alpha value of a color when defining the color itself, you can also set an alpha value separately by using the line_alpha or fill_alpha properties of a glyph.

In case you define a color with an alpha value and also explicitly provide an alpha value through a line_alpha or fill_alpha property at the same time, the following happens: If your color definition does include an alpha value (such as '#00FF0044' or 'rgba(255, 0, 127, 0.6)'), this alpha value takes precedence over the alpha value you provide through the objects’s property. Otherwise, the alpha value defined in the objects’s property is used.

The following figure demonstrates each possible combination of using RGB and RGBA colors together with the line_alpha or fill_alpha properties:

Screen units and data-space units#

When setting visual properties of Bokeh objects, you use either screen units or data-space units:

• Screen units use raw numbers of pixels to specify height or width

• Data-space units are relative to the data and the axes of the plot

Take a 400 pixel by 400 pixel graph with x and y axes ranging from 0 through 10, for example. A glyph that is one fifth as wide and tall as the graph would have a size of 80 screen units or 2 data-space units.

Objects in Bokeh that support both screen units and data-space units usually have a dedicated property to choose which unit to use. This unit-setting property is the name of the property with an added _units. For example: A Whisker annotation has the property upper. To define which unit to use, set the upper_units property to either 'screen' or 'data'.

Dimensions#

To change the width and height of a Plot, use its width and height attributes. Those two attributes use screen units. They control the size of the entire canvas area, including any axes or titles (but not the toolbar).

If you are using the bokeh.plotting interface, you can pass these values to figure() directly:

from bokeh.plotting import figure, output_file, show

output_file("dimensions.html")

# create a new plot with specific dimensions
p = figure(width=700)
p.height = 300

p.circle([1, 2, 3, 4, 5], [2, 5, 8, 2, 7], size=10)

show(p)

Responsive sizes#

To automatically adjust the width or height of your plot in relation to the available space in the browser, use the plot’s sizing_mode property.

To control how the plot scales to fill its container, see the documentation for layouts, in particular the sizing_mode property of LayoutDOM.

If you set sizing_mode to anything different than fixed, Bokeh adjusts the width and height as soon as a plot is rendered. However, Bokeh uses width and height to calculate the initial aspect ratio of your plot.

Plots will only resize down to a minimum of 100px (height or width) to prevent problems in displaying your plot.

Title#

To style the title of your plot, use the Title annotation, which is available as the .title property of the Plot.

You can use most of the standard text properties. However, text_align and text_baseline do not apply. To position the title relative to the entire plot, use the properties align and offset instead.

As an example, to set the color and font style of the title text, use plot.title.text_color:

from bokeh.plotting import figure, output_file, show

output_file("title.html")

p = figure(width=400, height=400, title="Some Title")
p.title.text_color = "olive"
p.title.text_font = "times"
p.title.text_font_style = "italic"

p.circle([1, 2, 3, 4, 5], [2, 5, 8, 2, 7], size=10)

show(p)

Background#

To change the background fill style, adjust the background_fill_color and background_fill_alpha properties of the Plot object:

from bokeh.plotting import figure, output_file, show

output_file("background.html")

p = figure(width=400, height=400)
p.background_fill_color = "beige"
p.background_fill_alpha = 0.5

p.circle([1, 2, 3, 4, 5], [2, 5, 8, 2, 7], size=10)

show(p)

Border#

To adjust the border fill style, use the border_fill_color and border_fill_alpha properties of the Plot object. You can also set the minimum border on each side (in screen units) with these properties:

• min_border_left

• min_border_right

• min_border_top

• min_border_bottom

Additionally, if you set min_border, Bokeh applies a minimum border setting to all sides as a convenience. The min_border default value is 40px.

from bokeh.plotting import figure, output_file, show

output_file("border.html")

p = figure(width=400, height=400)
p.border_fill_color = "whitesmoke"
p.min_border_left = 80

p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)

show(p)

Outline#

Bokeh Plot objects have various line properties. To change the appearance of outlines, use those line properties that are prefixed with outline_.

For example, to set the color of the outline, use outline_line_color:

from bokeh.plotting import figure, output_file, show

output_file("outline.html")

p = figure(width=400, height=400)
p.outline_line_width = 7
p.outline_line_alpha = 0.3
p.outline_line_color = "navy"

p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)

show(p)

Selected and unselected glyphs#

To customize the styling of selected and non-selected glyphs, set the selection_glyph and nonselection_glyph attributes of the GlyphRenderer. You can either set them manually or by passing them to add_glyph().

The plot below uses the bokeh.plotting interface to set these attributes. Click or tap any of the circles on the plot to see the effect on the selected and non-selected glyphs. To clear the selection and restore the original state, click anywhere in the plot outside of a circle.

from bokeh.io import output_file, show
from bokeh.models import Circle
from bokeh.plotting import figure

output_file("styling_selections.html")

plot = figure(width=400, height=400, tools="tap", title="Select a circle")
renderer = plot.circle([1, 2, 3, 4, 5], [2, 5, 8, 2, 7], size=50)

selected_circle = Circle(fill_alpha=1, fill_color="firebrick", line_color=None)
nonselected_circle = Circle(fill_alpha=0.2, fill_color="blue", line_color="firebrick")

renderer.selection_glyph = selected_circle
renderer.nonselection_glyph = nonselected_circle

show(plot)

If you just need to set the color or alpha parameters of the selected or non-selected glyphs, provide color and alpha arguments to the glyph function, prefixed by "selection_" or "nonselection_":

from bokeh.io import output_file, show
from bokeh.plotting import figure

output_file("styling_selections.html")

plot = figure(width=400, height=400, tools="tap", title="Select a circle")
renderer = plot.circle([1, 2, 3, 4, 5], [2, 5, 8, 2, 7], size=50,

                       # set visual properties for selected glyphs
                       selection_color="firebrick",

                       # set visual properties for non-selected glyphs
                       nonselection_fill_alpha=0.2,
                       nonselection_fill_color="blue",
                       nonselection_line_color="firebrick",
                       nonselection_line_alpha=1.0)

show(plot)

If you use the bokeh.models interface, use the add_glyph() function:

p = Plot()
source = ColumnDataSource(dict(x=[1, 2, 3], y=[1, 2, 3]))

initial_circle = Circle(x='x', y='y', fill_color='blue', size=50)
selected_circle = Circle(fill_alpha=1, fill_color="firebrick", line_color=None)
nonselected_circle = Circle(fill_alpha=0.2, fill_color="blue", line_color="firebrick")

p.add_glyph(source,
            initial_circle,
            selection_glyph=selected_circle,
            nonselection_glyph=nonselected_circle)

Hover inspections#

To style the appearance of glyphs that are hovered over, pass color or alpha parameters prefixed with "hover_" to your renderer function.

Alternatively, set the selection_glyph and nonselection_glyph attributes of the GlyphRenderer, just like in Selected and unselected glyphs above.

This example uses the first method of passing a color parameter with the "hover_" prefix:

from bokeh.models import HoverTool
from bokeh.plotting import figure, output_file, show
from bokeh.sampledata.glucose import data

output_file("styling_hover.html")

subset = data.loc['2010-10-06']

x, y = subset.index.to_series(), subset['glucose']

# Basic plot setup
plot = figure(width=600, height=300, x_axis_type="datetime", tools="",
              toolbar_location=None, title='Hover over points')

plot.line(x, y, line_dash="4 4", line_width=1, color='gray')

cr = plot.circle(x, y, size=20,
                fill_color="grey", hover_fill_color="firebrick",
                fill_alpha=0.05, hover_alpha=0.3,
                line_color=None, hover_line_color="white")

plot.add_tools(HoverTool(tooltips=None, renderers=[cr], mode='hline'))

show(plot)

Labels#

To add or change the text of an axis’ overall label, use the axis_label property. To add line breaks to the text in an axis label, include \n in your string.

To control the visual appearance of the label text, use any of the standard text properties prefixed with axis_label_. For instance, to set the text color of the label, set axis_label_text_color.

To change the distance between the axis label and the major tick labels, set the axis_label_standoff property.

For example:

from bokeh.plotting import figure, output_file, show

output_file("bounds.html")

p = figure(width=400, height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)

p.xaxis.axis_label = "Lot Number"
p.xaxis.axis_label_text_color = "#aa6666"
p.xaxis.axis_label_standoff = 30

p.yaxis.axis_label = "Bin Count"
p.yaxis.axis_label_text_font_style = "italic"

show(p)

Bounds#

To limit the bounds where axes are drawn, set the bounds property of an axis object to a 2-tuple of (start, end):

from bokeh.plotting import figure, output_file, show

output_file("bounds.html")

p = figure(width=400, height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)

p.xaxis.bounds = (2, 4)

show(p)

Tick locations#

Bokeh uses several “ticker” models to decide where to display ticks on axes (categorical, datetime, mercator, linear, or log scale). To configure the placements of ticks, use the .ticker property of an axis.

If you use the bokeh.plotting interface, Bokeh chooses an appropriate ticker placement model automatically.

In case you need to control which ticker placement model to use, you can also explicitly define a list of tick locations. Assign FixedTicker with a list of tick locations to an axis:

from bokeh.plotting import figure
from bokeh.models.tickers import FixedTicker

p = figure()

# no additional tick locations will be displayed on the x-axis
p.xaxis.ticker = FixedTicker(ticks=[10, 20, 37.4])

As a shortcut, you can also supply the list of ticks directly to an axis’ ticker property:

from bokeh.plotting import figure, output_file, show

output_file("fixed_ticks.html")

p = figure(width=400, height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)

p.xaxis.ticker = [2, 3.5, 4]

show(p)

Tick lines#

To control the visual appearance of the major and minor ticks, set the appropriate line properties, prefixed with major_tick_ and minor_tick_, respectively.

For instance, to set the color of the major ticks, use major_tick_line_color. To hide either set of ticks, set the color to None.

Additionally, to control how far in and out of the plotting area the ticks extend, use the properties major_tick_in/major_tick_out and minor_tick_in/minor_tick_out. These values are in screen units. Therefore, you can use negative values.

from bokeh.plotting import figure, output_file, show

output_file("axes.html")

p = figure(width=400, height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)

p.xaxis.major_tick_line_color = "firebrick"
p.xaxis.major_tick_line_width = 3
p.xaxis.minor_tick_line_color = "orange"

p.yaxis.minor_tick_line_color = None

p.axis.major_tick_out = 10
p.axis.minor_tick_in = -3
p.axis.minor_tick_out = 8

show(p)

Tick label formats#

To style the text of axis labels, use the TickFormatter object of the axis’ formatter property. Bokeh uses a number of ticker formatters by default in different situations:

• BasicTickFormatter — Default formatter for linear axes.

• CategoricalTickFormatter — Default formatter for categorical axes.

• DatetimeTickFormatter — Default formatter for datetime axes.

• LogTickFormatter — Default formatter for log axes.

These default tick formatters do not expose many configurable properties. To control tick formatting at a finer-grained level, use one of the NumeralTickFormatter or PrintfTickFormatter described below.

from bokeh.models import NumeralTickFormatter
from bokeh.plotting import figure, output_file, show

output_file("gridlines.html")

p = figure(width=400, height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)

p.xaxis[0].formatter = NumeralTickFormatter(format="0.0%")
p.yaxis[0].formatter = NumeralTickFormatter(format="$0.00")

show(p)

from bokeh.models import PrintfTickFormatter
from bokeh.plotting import figure, output_file, show

output_file("gridlines.html")

p = figure(width=400, height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)

p.xaxis[0].formatter = PrintfTickFormatter(format="%4.1e")
p.yaxis[0].formatter = PrintfTickFormatter(format="%5.3f mu")

show(p)

from bokeh.models import FuncTickFormatter
from bokeh.plotting import figure, output_file, show

output_file("formatter.html")

p = figure(width=500, height=500)
p.circle([0, 2, 4, 6, 8, 10], [6, 2, 4, 10, 8, 0], size=30)

p.yaxis.formatter = FuncTickFormatter(code="""
    return Math.floor(tick) + " + " + (tick % 1).toFixed(2)
""")

show(p)

Tick label orientation#

To control the orientation of major tick labels, use the major_label_orientation property. This property accepts the values "horizontal" or "vertical" or a floating-point number that gives the angle (in radians) to rotate from the horizontal:

from math import pi

from bokeh.plotting import figure, output_file, show

output_file("gridlines.html")

p = figure(width=400, height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)

p.xaxis.major_label_orientation = pi/4
p.yaxis.major_label_orientation = "vertical"

show(p)

Lines#

To configure the visual appearance of grid lines, use a collection of line properties, prefixed with grid_.

For instance, to set the color of grid lines, use grid_line_color. To hide grid lines, set their line color to None:

from bokeh.plotting import figure, output_file, show

output_file("gridlines.html")

p = figure(width=400, height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)

# change just some things about the x-grid
p.xgrid.grid_line_color = None

# change just some things about the y-grid
p.ygrid.grid_line_alpha = 0.5
p.ygrid.grid_line_dash = [6, 4]

show(p)

Minor lines#

To configure the visual appearance of minor grid lines, use a collection of line properties, prefixed with minor_grid_.

For instance, to set the color of grid lines, use minor_grid_line_color. By default, minor grid lines are hidden (which means that their line color is set to None):

from bokeh.plotting import figure, output_file, show

output_file("minorgridlines.html")

p = figure(width=400, height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)

# change just some things about the y-grid
p.ygrid.minor_grid_line_color = 'navy'
p.ygrid.minor_grid_line_alpha = 0.1

show(p)

Bands#

Use “bands” to display filled, shaded bands between adjacent grid lines. To control the visual appearance of these bands, use a collection of fill properties and hatch properties that are prefixed with band_.

For instance, to set the color of grid bands, use band_fill_color. To hide grid bands, set their fill color to None (this is the default).

This example defines bands filled with a solid color:

from bokeh.plotting import figure, output_file, show

output_file("grid_band_fill.html")

p = figure(width=400, height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)

# change just some things about the x-grid
p.xgrid.grid_line_color = None

# change just some things about the y-grid
p.ygrid.band_fill_alpha = 0.1
p.ygrid.band_fill_color = "navy"

show(p)

This example uses bands filled with a hatch pattern:

from bokeh.io import output_file, show
from bokeh.plotting import figure

output_file("grid_band_hatch.html")

p = figure(height=250, width=600, x_range=(0, 10), tools="", toolbar_location=None)
p.line(x=[0,1,2,3,4,5,6,7,8,9,10],
       y=[1,3,4,3,1,2,6,5,2,3,4])

p.ygrid.grid_line_color = None

ticks = [0, 2, 4, 6, 8, 10]
p.xaxis[0].ticker = ticks
p.xgrid[0].ticker = ticks

p.xgrid.band_hatch_pattern = "/"
p.xgrid.band_hatch_alpha = 0.6
p.xgrid.band_hatch_color = "lightgrey"
p.xgrid.band_hatch_weight = 0.5
p.xgrid.band_hatch_scale = 10

show(p)

Bounds#

To set explicit bounds that limit where grids are drawn, use a 2-tuple of (start, end). This is identical to setting bounds for axes:

from bokeh.plotting import figure, output_file, show

output_file("bounds.html")

p = figure(width=400, height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)

p.grid.bounds = (2, 4)

show(p)

Location#

To control the location of the legend labels, use the location property.

import numpy as np

from bokeh.plotting import figure, output_file, show

x = np.linspace(0, 4*np.pi, 100)
y = np.sin(x)

output_file("legend_labels.html")

p = figure()

p.circle(x, y, legend_label="sin(x)")
p.line(x, y, legend_label="sin(x)")

p.line(x, 2*y, legend_label="2*sin(x)",
       line_dash=[4, 4], line_color="orange", line_width=2)

p.square(x, 3*y, legend_label="3*sin(x)", fill_color=None, line_color="green")
p.line(x, 3*y, legend_label="3*sin(x)", line_color="green")

p.legend.location = "bottom_left"

show(p)

import numpy as np

from bokeh.models import Legend
from bokeh.plotting import figure, output_file, show

x = np.linspace(0, 4*np.pi, 100)
y = np.sin(x)

output_file("legend_labels.html")

p = figure(toolbar_location="above")

r0 = p.circle(x, y)
r1 = p.line(x, y)

r2 = p.line(x, 2*y, line_dash=[4, 4], line_color="orange", line_width=2)

r3 = p.square(x, 3*y, fill_color=None, line_color="green")
r4 = p.line(x, 3*y, line_color="green")

legend = Legend(items=[
    ("sin(x)"   , [r0, r1]),
    ("2*sin(x)" , [r2]),
    ("3*sin(x)" , [r3, r4]),
], location="center")

p.add_layout(legend, 'right')

show(p)

Title#

To add or change a legend’s title, use its title property:

plot.legend.title = "Division"

To control the visual appearance of the legend title, use any of the standard text properties prefixed with title_. For instance, to set the font style of the legend, use title_text_font_style.

To set the distance between the title and the rest of the legend (in pixels), use the title_standoff property.

import pandas as pd

from bokeh.palettes import Spectral4
from bokeh.plotting import figure, output_file, show
from bokeh.sampledata.stocks import AAPL, GOOG, IBM, MSFT

output_file("styling_legend_title.html", title="styling_legend_title.py example")

p = figure(width=800, height=250, x_axis_type="datetime")

for data, name, color in zip([AAPL, IBM, MSFT, GOOG], ["AAPL", "IBM", "MSFT", "GOOG"], Spectral4):
    df = pd.DataFrame(data)
    df['date'] = pd.to_datetime(df['date'])
    p.line(df['date'], df['close'], line_width=2, color=color, legend_label=name)

p.legend.location = "top_left"
p.legend.title = 'Stock'
p.legend.title_text_font_style = "bold"
p.legend.title_text_font_size = "20px"

show(p)

Orientation#

To control the orientation of the legend, use the orientation property. Valid values for this property are:

• "vertical"

• "horizontal"

The default orientation is "vertical".

import numpy as np

from bokeh.plotting import figure, output_file, show

x = np.linspace(0, 4*np.pi, 100)
y = np.sin(x)

output_file("legend_labels.html")

p = figure()

p.circle(x, y, legend_label="sin(x)")
p.line(x, y, legend_label="sin(x)")

p.line(x, 2*y, legend_label="2*sin(x)",
       line_dash=[4, 4], line_color="orange", line_width=2)

p.square(x, 3*y, legend_label="3*sin(x)", fill_color=None, line_color="green")
p.line(x, 3*y, legend_label="3*sin(x)", line_color="green")

p.legend.orientation = "horizontal"

show(p)

Label text#

To control the visual appearance of the legend labels, use any of the standard text properties prefixed with label_. For instance, to set the font style of the labels, use label_text_font_style.

import numpy as np

from bokeh.plotting import figure, output_file, show

x = np.linspace(0, 4*np.pi, 100)
y = np.sin(x)

output_file("legend_labels.html")

p = figure()

p.circle(x, y, legend_label="sin(x)")
p.line(x, y, legend_label="sin(x)")

p.line(x, 2*y, legend_label="2*sin(x)",
       line_dash=[4, 4], line_color="orange", line_width=2)

p.square(x, 3*y, legend_label="3*sin(x)", fill_color=None, line_color="green")
p.line(x, 3*y, legend_label="3*sin(x)", line_color="green")

p.legend.label_text_font = "times"
p.legend.label_text_font_style = "italic"
p.legend.label_text_color = "navy"

show(p)

Border#

To control the visual appearance of the legend border, use a collection of line properties, prefixed with border_. For instance, to set the color of the border, use border_line_color. To make the border invisible, set the border line color to None.

import numpy as np

from bokeh.plotting import figure, output_file, show

x = np.linspace(0, 4*np.pi, 100)
y = np.sin(x)

output_file("legend_border.html")

p = figure()

p.circle(x, y, legend_label="sin(x)")
p.line(x, y, legend_label="sin(x)")

p.line(x, 2*y, legend_label="2*sin(x)",
       line_dash=[4, 4], line_color="orange", line_width=2)

p.square(x, 3*y, legend_label="3*sin(x)", fill_color=None, line_color="green")
p.line(x, 3*y, legend_label="3*sin(x)", line_color="green")

p.legend.border_line_width = 3
p.legend.border_line_color = "navy"
p.legend.border_line_alpha = 0.5

show(p)

Background#

To control the visual appearance of the legend background, use a collection of fill properties, prefixed with background_. For instance, to set the color of the background, use background_fill_color. To make the background transparent, set the background_fill_alpha to 0.

import numpy as np

from bokeh.plotting import figure, output_file, show

x = np.linspace(0, 4*np.pi, 100)
y = np.sin(x)

output_file("legend_background.html")

p = figure()

p.circle(x, y, legend_label="sin(x)")
p.line(x, y, legend_label="sin(x)")

p.line(x, 2*y, legend_label="2*sin(x)",
       line_dash=[4, 4], line_color="orange", line_width=2)

p.square(x, 3*y, legend_label="3*sin(x)", fill_color=None, line_color="green")
p.line(x, 3*y, legend_label="3*sin(x)", line_color="green")

#  3*sin(x) curve should be under this legend at initial viewing, so
# we can see that the legend is transparent
p.legend.location = "bottom_right"
p.legend.background_fill_color = "navy"
p.legend.background_fill_alpha = 0.5

show(p)

Dimensions#

To control dimensions such as the layout or spacing of label components, use the following properties:

There are several properties that can be used to control the layout, spacing, etc. of the legend components:

label_standoff = 5#

Type

Int

The distance (in pixels) to separate the label from its associated glyph.

label_width = 20#

Type

Int

The minimum width (in pixels) of the area that legend labels should occupy.

label_height = 20#

Type

Int

The minimum height (in pixels) of the area that legend labels should occupy.

glyph_width = 20#

Type

Int

The width (in pixels) that the rendered legend glyph should occupy.

glyph_height = 20#

Type

Int

The height (in pixels) that the rendered legend glyph should occupy.

padding = 10#

Type

Int

Amount of padding around the contents of the legend. Only applicable when border is visible, otherwise collapses to 0.

spacing = 3#

Type

Int

Amount of spacing (in pixels) between legend entries.

margin = 10#

Type

Int

Amount of margin around the legend.

import numpy as np

from bokeh.plotting import figure, output_file, show

x = np.linspace(0, 4*np.pi, 100)
y = np.sin(x)

output_file("legend_labels.html")

p = figure()

p.circle(x, y, legend_label="sin(x)")
p.line(x, y, legend_label="sin(x)")

p.line(x, 2*y, legend_label="2*sin(x)",
       line_dash=[4, 4], line_color="orange", line_width=2)

p.square(x, 3*y, legend_label="3*sin(x)", fill_color=None, line_color="green")
p.line(x, 3*y, legend_label="3*sin(x)", line_color="green")

p.legend.label_standoff = 5
p.legend.glyph_width = 50
p.legend.spacing = 10
p.legend.padding = 50
p.legend.margin = 50

show(p)

LaTeX#

To use LaTeX notation, you can pass a string directly to any supported element. This string needs to begin and end with one of the MathJax default delimiters. These delimiters are $$...$$, \[...\], and \(...\). For example: r"$$\sin(x)$$".

LaTeX and axis labels

To use LaTeX notation as an axis label, pass a raw string literal beginning and ending with MathJax default delimiters and containing LaTeX notation to the axis_label property of an axis. For example:

from numpy import arange, pi, sin

from bokeh.plotting import figure, show

x = arange(-2*pi, 2*pi, 0.1)
y = sin(x)

plot = figure(height=200)
plot.circle(x, y, alpha=0.6, size=7)

plot.yaxis.axis_label = r"\[\sin(x)\]"
plot.xaxis.axis_label = r"\[x\cdot\pi\]"

show(plot)

LaTeX and tick labels

To add LaTeX notations to your tick labels, use the major_label_overrides() function with an axis.

This function is used to replace values for existing tick labels with custom text. It accepts a dictionary with the tick label’s original value as the key and your custom value as the dict’s value.

Use this function to replace any plain text tick labels with LaTeX notation:

from numpy import arange

from bokeh.plotting import figure, show

x = arange(1, 4.5, 0.25)
y = 1 / x

plot = figure(height=200)
plot.circle(x, y, fill_color="blue", size=5)
plot.line(x, y, color="darkgrey")

plot.xaxis.axis_label = "Resistance"
plot.xaxis.ticker = [1, 2, 3, 4]
plot.yaxis.axis_label = "Current at 1 V"

plot.xaxis.major_label_overrides = {
    1: r"$$1\Omega$$",
    2: r"$$2\Omega$$",
    3: r"$$3\Omega$$",
    4: r"$$4\Omega$$",
}

show(plot)

LaTeX with div and paragraph widgets

To include LaTeX notation in the text of a div widget or paragraph widget, use the standard MathJax default delimiters anywhere within your string:

from bokeh.io import show
from bokeh.models import Div

div = Div(
    width=400, height=100, background="#fafafa",
    text="The Pythagorean identity is $$\sin^2(x) + \cos^2(x) = 1$$"
)

show(div)

The Pythagorean identity is

To disable LaTeX rendering for a div or paragraph widget, set the widget’s disable_math property to True.