How to Style Plots by Backend#

This guide shows how to style plots with the options of the active plotting extension (Bokeh, Matplotlib or Plotly), and how to reuse Bokeh styling options with another extension thanks to the compatibility mode.

Load hvPlot and the extensions#

Importing hvplot.pandas loads Bokeh. The second line loads Matplotlib too, keeping Bokeh as the active extension:

import hvplot.pandas  # noqa

hvplot.extension('bokeh', 'matplotlib')

penguins = hvplot.sampledata.penguins('pandas')

Find the styling options#

Styling options control how the plot elements are drawn, such as the dash pattern of a line or the outline color of markers. They are not defined by hvPlot but by HoloViews, which hvPlot uses to render plots, and they follow the naming of each plotting library. As a result, they depend on both the plot type and the extension:

Line plots accept line_dash and line_width with Bokeh, linestyle and linewidth with Matplotlib, and dash and line_width with Plotly.
Scatter plots accept line_color for the marker outline with Bokeh, and edgecolor with Matplotlib.
Histograms accept fill_alpha with Bokeh, an option Matplotlib histograms don’t have.

Styling options come on top of hvPlot’s generic options, like title, width or color, which work with all the extensions.

The reference page of each plot method lists its styling options for each extension, e.g. hvplot.hvPlot.scatter(). You can also print them with hvplot.help(), where style sets the extension (the active one by default):

hvplot.help('scatter', docstring=False, generic=False, style='matplotlib')

Matplotlib Styling options
---------------
alpha
c
cmap
color
ec
ecolor
edgecolor
edgecolors
facecolors
linewidth
lw
marker
norm
s
visible
vmax
vmin

Style a plot with Bokeh options#

Bokeh is the active extension, so pass Bokeh styling options:

penguins.hvplot.scatter(
    x='bill_length_mm', y='bill_depth_mm', by='species',
    line_color='black', line_width=1
)

Style a plot with Matplotlib options#

Switch to Matplotlib and pass the Matplotlib equivalents:

hvplot.output(backend='matplotlib')

penguins.hvplot.scatter(
    x='bill_length_mm', y='bill_depth_mm', by='species',
    edgecolor='black', linewidth=1
)

hvPlot ignores options that are not valid for the active extension and warns about them. With Matplotlib active, line_color='black' prints a warning.

penguins.hvplot.scatter(
    x='bill_length_mm', y='bill_depth_mm', by='species',
    line_color='black', linewidth=1
)

WARNING:param.main: line_color option not found for scatter plot with matplotlib; similar options include: ['ecolor', 'color', 'edgecolor']

Reuse Bokeh options with the compatibility mode#

Code written with Bokeh styling options doesn’t need to be rewritten to get the same styling with Matplotlib or Plotly. Load the extension with compatibility='bokeh': hvPlot then accepts Bokeh styling options and translates them for the active extension.

hvplot.extension('matplotlib', compatibility='bokeh')

penguins.hvplot.scatter(
    x='bill_length_mm', y='bill_depth_mm', by='species',
    line_color='black', line_width=1
)

Here line_color became edgecolor and line_width became linewidth. Good to know about this mode:

Bokeh is the only source supported: compatibility='bokeh' works with Matplotlib and Plotly, compatibility='matplotlib' or 'plotly' is not implemented.
Styling options are checked against Bokeh’s, so pass Bokeh options only. Matplotlib options like edgecolor are ignored with a warning.
The translation is partial. Options without an equivalent are dropped silently. Only a few values are translated (e.g. line_dash='dashed'), others are passed unchanged.