Plotting Options#

hvPlot offers many ways to control the appearance and behavior of your plots. This page documents all of the generic options that can be applied to most plots (hvplot.hvPlot.scatter(), hvplot.hvPlot.line(), etc.) regardless of which plotting backend you are using (Bokeh, Matplotlib, etc.). Most plot types also offer additional options beyond the generic ones documented here. Those additional options depend on the specific type of plot (e.g. marker for hvplot.hvPlot.scatter()) and the specific plotting backend (e.g. line_width for hvplot.hvPlot.line() with Bokeh). The latter group of options is often styling related. These additional options are documented in the reference page for the plot type (e.g. hvplot.hvPlot.scatter() for a scatter plot).

The plotting options can be displayed interactively for a plot type and the active plotting backend using hvplot.help(), e.g. hvplot.help('scatter'). The function prints all the options by default. Its output can be reduced by setting to False the keywords generic (to exclude the generic options), docstring (to exclude the plot type docstring), and style (to exclude the backend-specific styling options).

The sections below cover the generic options available for all plots, grouped into categories depending on what the options control.

Data Options#

For organizing, grouping, and transforming the dataset before visualization, including labels, sorting, and indexing:

Parameters

Description

attr_labels (bool or None, default=None)

Whether to use an xarray object’s attributes as labels, defaults to None to allow best effort without throwing a warning. Set to True to see warning if the attrs can’t be found, set to False to disable the behavior.

by (str or list of str or None, default=None)

Dimension(s) by which to group the data categories. An NdOverlay is returned by default unless subplots=True, then an NdLayout is returned.

dynamic (bool, default=True)

Whether to return a dynamic plot which sends updates on widget and zoom/pan events or whether all the data should be embedded (warning: for large groupby operations embedded data can become very large if dynamic=False).

fields (dict, default={})

A dictionary of fields for renaming or transforming data dimensions.

groupby (str or list or None, default=None)

Dimension(s) by which to group data, enabling widgets. Returns a DynamicMap if dynamic=True, else returns a HoloMap. See dynamic for more information.

group_label (str or None, default=None)

Sets a custom label for the dimension created when plotting multiple columns. When multiple columns are plotted (e.g., multiple y values), hvPlot automatically reshapes the data from wide to long format. It creates a new grouping dimension that holds the original column names. By default, this grouping dimension is labeled 'Variable'. Setting group_label overrides this default label.

Note

group_label only applies when plotting multiple columns and does not control grouping with by.

kind (str, default=’line’)

The type of plot to generate. Should only be set when calling hvplot() directly.

label (str or None, default=None)

Label for the data, typically used in the plot title or legends.

persist (bool, default=False)

Whether to persist the data in memory when using dask.

row (str or None, default=None)

Column name to use for splitting the plot into separate subplots by rows.

col (str or None, default=None)

Column name to use for splitting the plot into separate subplots by columns.

sort_date (bool, default=True)

Whether to sort the x-axis by date before plotting

subplots (bool, default=False)

Whether to display data in separate subplots when using the by parameter.

transforms (dict, default={})

A dictionary of HoloViews dim transforms to apply before plotting

use_dask (bool, default=False)

Enables support for Dask-backed xarray datasets, allowing out-of-core computation and parallel processing. Only applicable when the input data is an xarray object. Has no effect on Pandas or other non-xarray data structures.

use_index (bool, default=True)

Whether to use the data’s index for the x-axis by default.

value_label (str, default=’value’)

Sets a custom label for the values when the data is reshaped from wide to long format (e.g., when plotting multiple columns). This label is typically used for the y-axis, colorbar, or in hover tooltips.

See this page for more information on these options.

Size And Layout Options#

Customization options for plot sizes and overall layout, including responsive mode and widget location:

Parameters

Description

aspect (float or {‘equal’, ‘square’} or None, default=None)

Sets the width-to-height ratio of the plot. When None (the default), hvPlot chooses an appropriate aspect automatically. Use 'equal' or 'square' to modify the unit ratio between axes, or supply a numeric value (e.g. 2.0) for a custom ratio. To control the scaling of individual axis units, use the data_aspect option instead.

data_aspect (float or None, default=None)

Defines the aspect of the axis scaling, i.e. the ratio of y-unit to x-unit.

frame_width/frame_height (int)

The width and height of the data area of the plot

max_width/max_height (int)

The maximum width and height of the plot for responsive modes

min_width/min_height (int)

The minimum width and height of the plot for responsive modes

height (int, default=300)

The height of the plot in pixels

width (int, default=700)

The width of the plot in pixels

padding (number or tuple)

Fraction by which to increase auto-ranged extents to make datapoints more visible around borders. Supports tuples to specify different amount of padding for x- and y-axis and tuples of tuples to specify different amounts of padding for upper and lower bounds.

responsive (bool, default=False)

Whether the plot should responsively resize depending on the size of the browser. Responsive mode will only work if at least one dimension of the plot is left undefined, e.g. when width and height or width and aspect are set the plot is set to a fixed size, ignoring any responsive option. Only supported by the interactive plotting backends.

widget_location (str, optional)

Specifies where to place widgets generated by options like groupby. Valid values are: 'right' (default), 'left', 'bottom', 'right', 'top', 'top_left', 'top_right', 'bottom_left', 'bottom_right', 'left_top', 'left_bottom', 'right_top', 'right_bottom'. Only applies if the plot generates widgets (e.g. via groupby).

See this page for more information on these options.

Axis Options#

Customization options for axis appearance and behavior, including labels, limits, tick formatting, and axis scaling:

Parameters

Description

autorange (Literal[‘x’, ‘y’] or None, default=None)

Whether to enable auto-ranging along the x- or y-axis when zooming. Only supported by the Bokeh backend.

Added in version 0.9.0.

flip_xaxis/flip_yaxis (bool or None, default=None)

Whether to flip the axis left to right or up and down respectively.

framewise (bool, default=True)

Whether to compute the axis ranges frame-by-frame when using dynamic plots.

invert (bool, default=False)

Swaps x- and y-axis.

logx/logy (bool, default=False)

Enables logarithmic x- and y-axis respectively.

loglog (bool or None, default=None)

Enables logarithmic x- and y-axis.

rot (number or None, default=None)

Rotates the axis ticks along the x-axis by the specified number of degrees.

shared_axes (bool, default=True)

Whether to link axes between plots.

subcoordinate_y (bool or dict or None, default=None)

Whether to enable sub-coordinate y systems for this plot. Accepts also a dictionary of related options to pass down to HoloViews, e.g. {'subcoordinate_scale': 2}.

Added in version 0.11.0.

title (str or None, default=None)

Title for the plot.

xaxis (str or bool or None)

Whether to show the x-axis and whether to place it at the top or bottom. A bare axis means that an axis line is still displayed but there are no axis ticks and labels. Valid options include: bottom (default), bottom-bare, top, top-bare, None (no axis at all), True (same as bottom), and False (same as None).

yaxis (str or bool or None)

Whether to show the y-axis and whether to place it at the left or right. A bare axis means that an axis line is still displayed but there are no axis ticks and labels. Valid options include: left (default), left-bare, right, right-bare, None (no axis at all), True (same as left), and False (same as None).

xformatter/yformatter (str or bokeh.TickFormatter or None, default=None)

Formatter for the x-axis and y-axis (accepts printf formatter, e.g. ‘%.3f’, and bokeh TickFormatter).

xlabel/ylabel/clabel (str or None, default=None)

Axis labels for the x-axis, y-axis, and colorbar.

xlim/ylim (tuple or None, default=None)

Plot limits of the x- and y-axis. One bound can be left unset by using None (e.g. xlim=(10, None) means there is no upper bound).

xticks/yticks/cticks (int or list or np.ndarray or None, default=None)

Ticks along x-axis and y-axis, as an integer, list of ticks positions, Numpy ndarray, or list of tuples of the tick positions and labels. Also accepts a Bokeh Ticker instance when the Bokeh plotting backend is enabled.

Added in version 0.11.0: cticks was added in this version and is only supported by the Bokeh plotting backend.

See this page for more information on these options.

Color And Colormap Options#

Visual styling options to adjust colors and colormapping:

Parameters

Description

bgcolor (str or None, default=None)

Background color of the data area of the plot

color (str or list or column name or None, default=None)

Defines the color(s) to use for the plot. Accepts:

  • a single color name (e.g., 'red', 'blue')

  • a HEX color code (e.g., '#ff5733')

  • a list of colors for multiple elements

  • a column name from the dataset to map colors based on values.

c (str or list or column name or None, default=None)

Alias for color. If both color and c are provided, the color keyword takes precedence.

cmap (str or list or dict or colormap object or None, default=None)

The colormap to use for continuous or categorical color mapping.

Accepts:

  • a predefined colormap name from Bokeh, Matplotlib, or Colorcet (e.g., 'viridis', 'plasma')

  • a list of named colors or HEX color codes.

  • a dictionary mapping categories to colors for discrete colormaps.

  • A colormap object from HoloViews or Matplotlib.

If not specified, a default colormap is automatically chosen based on the data type:

  • Linear data: Uses the kbc_r colormap.

  • Categorical data: Uses glasbey_category10 colormap from Colorcet.

  • Cyclic data: Uses colorwheel colormap.

  • Diverging data: Uses coolwarm colormap.

You can override these defaults by explicitly setting cmap=<colormap_name>. Only one of cmap, colormap, or color_key can be specified at a time.

colorbar (bool or None, default=None)

Enables a colorbar. Enabled by default for these plots: bivariate, contour, contourf, heatmap, image, hexbin, quadmesh, polygons. Enabled by default for rasterized plots.

colormap (str or list or colormap object or None, default=None)

Alias for cmap. Accepts the same values as cmap. See cmap for more details. Only one of cmap, colormap, or color_key can be specified at a time.

color_key (str or list or dict or None, default=None)

Alias for cmap. Accepts the same values as cmap. See cmap for more details. Only one of cmap, colormap, or color_key can be specified at a time.

clim (tuple or None, default=None)

Lower and upper bound of the color scale

cnorm (str, default=’linear’)

Color scaling which must be one of 'linear', 'log' or 'eq_hist'.

rescale_discrete_levels (bool or None, default=None)

If cnorm='eq_hist' and there are only a few discrete values, then rescale_discrete_levels=True (the default) decreases the lower limit of the autoranged span so that the values are rendering towards the (more visible) top of the cmap range, thus avoiding washout of the lower values. Has no effect if cnorm!=`eq_hist.

robust (bool or None, default=None)

If this option is True and no clim was provided, the colormap range is computed with 2nd and 98th percentiles instead of the extreme values for image elements. For RGB elements, clips the “RGB”, or raw reflectance values between 2nd and 98th percentiles. Follows the same logic as xarray’s robust option.

symmetric (bool or None, default=None)

Whether the data are symmetric around zero. If left unset, the data will be checked for symmetry as long as the size is less than check_symmetric_max.

check_symmetric_max (int, default=1000000)

Size above which to stop checking for symmetry by default on the data.

See this page for more information on these options.

Styling Options#

Note

These are the styling options shared by all the supported plotting backends. Backend-specific options can be found on the reference page of each plotting method (e.g. hvplot.hvPlot.scatter()) or by executing hvplot.help('scatter', docstring=False, generic=False, style=True).

Visual styling options to adjust colors, fonts, and other aesthetic elements of the plot:

Parameters

Description

backend_opts (dict or None, optional)

A dictionary of custom options to apply to the plot or subcomponents of the plot. The keys in the dictionary mirror attribute access on the underlying plotting backend objects stored in the plot’s handles, e.g. {'hover.attachment': 'vertical'} will index the hover in the handles and then set the attachment.

fontscale (number)

Scales the size of all fonts by the same amount, e.g. fontscale=1.5 enlarges all fonts (title, xticks, labels etc.) by 50%.

fontsize (number or dict or None, default=None)

Set title, label and legend text to the same fontsize. Finer control by using a dict: {'title': '15pt', 'ylabel': '5px', 'ticks': 20}.

grid (bool or None, default=None)

Whether to show a grid.

See this page for more information on these options.

Legend Options#

Options for setting the grid or legend of plots as well as colorbar options:

Parameters

Description

legend (bool or str or None, default=None)

Whether to show a legend, or a legend position. A cardinal position ('top', 'bottom', 'left', 'right' (default)) or a corner placement ('top_left', 'top_right', 'bottom_left', 'bottom_right').

legend_cols (int or None, default=None)

Number of columns in the legend.

legend_opts (dict or None, default=None)

Allows setting specific styling options for the legend. They keys should be attributes of the Legend model for Bokeh and keyword arguments of the Axes.legen method for Matplotlib.

See this page for more information on these options.

Interactivity Options#

Note

These options only apply to the interactive plotting backends (e.g. Bokeh), not to the static backend Matplotlib.

Bokeh specific options for adding hover tools as well as other interactive tools like tap tool and box select tool:

Parameters

Description

hover (bool or str or None, default=None)

Whether to show hover tooltips, default is True unless datashade=True in which case hover is False by default. Also accepts 'hline' and 'vline' to change the hit-testing mode.

hover_cols (list or str, default=[])

Additional columns to add to the hover tool or ‘all’ which will include all columns (including indexes if use_index=True).

hover_formatters (dict or None, default=None)

A dict of formatting options for the hover tooltip.

Deprecated since version 0.12: Use hover_tooltips instead.

hover_tooltips (list[str] or list[tuple] or None, default=None)

A list of dimensions to be displayed in the hover tooltip.

toolbar (str or bool or None, optional)

Whether to display a toolbar and where to place it. Displayed by default, disabled with 'disable', None or False. Location must be one 'above', 'below', 'left', or 'right' (the default).

autohide_toolbar (bool, optional)

Whether to automatically hide the toolbar until the user hovers over the plot. This keyword has no effect if the toolbar is disabled (toolbar=None). Default is False.

tools (list, default=[])

List of tool instances or strings (e.g. [‘tap’, ‘box_select’])

See this page for more information on these options.

Resampling Options#

Performance related options for handling large datasets, including downsampling, rasterization, and dynamic plot updates (most of these options require Datashader to be installed):

Parameters

Description

aggregator (str, datashader.Reduction, or None, default=None)

Aggregator to use when applying rasterize or datashade operation (valid options include 'mean', 'count', 'min', 'max' and more, and datashader reduction objects)

datashade (bool, default=False)

Whether to apply rasterization and shading (colormapping) using the Datashader library, returning an RGB object instead of individual points

downsample (bool or str or None, default=None)

Controls the application of downsampling to the plotted data, which is particularly useful for large timeseries datasets to reduce the amount of data sent to browser and improve visualization performance.

Acceptable values:

  • False: No downsampling is applied.

  • True: Applies downsampling using HoloViews’ default algorithm (LTTB - Largest Triangle Three Buckets).

  • 'lttb': Explicitly applies the Largest Triangle Three Buckets algorithm. Uses tsdownsample if installed.

  • 'minmax': Applies the MinMax algorithm, selecting the minimum and maximum values in each bin. Requires tsdownsample.

  • 'm4': Applies the M4 algorithm, selecting the minimum, maximum, first, and last values in each bin. Requires tsdownsample.

  • 'minmax-lttb': Combines MinMax and LTTB algorithms for downsampling, first applying MinMax to reduce to a preliminary set of points, then LTTB for further reduction. Requires tsdownsample.

Other string values corresponding to supported algorithms in HoloViews may also be used.

dynspread (bool, default=False)

For plots generated with datashade=True or rasterize=True, automatically increase the point size when the data is sparse so that individual points become more visible.

max_px (int, default=3)

The maximum size in pixels for dynamically spreading elements in sparse data using dynspread. This helps to increase the visibility of sparse data points.

pixel_ratio (number or None, default=None)

Pixel ratio applied to the height and width, used when rasterizing or datashading. When not set explicitly, the ratio is automatically obtained from the browser device pixel ratio. Default is 1 when the browser information is not available. Useful when the browser information is not available (pixel_ratio=2 can give better results on Retina displays) or for using lower resolution for speed.

precompute (bool, default=False)

Whether to precompute aggregations when using rasterize or datashade.

rasterize (bool, default=False)

Whether to apply rasterization using the Datashader library, returning an aggregated Image (to be colormapped by the plotting backend) instead of individual points.

resample_when (int or None, default=None)

Applies a resampling operation (datashade, rasterize or downsample) if the number of individual data points present in the current viewport is above this threshold. The raw plot is displayed otherwise.

selector (datashader.Reduction | str | tuple | None, default=None)

Datashader reduction to apply during a rasterize or datashade operation, used to select additional information for inclusion in the hover tooltip. Supported options include:

  • string: only 'first' and 'last'

  • tuple of two strings: (<reduction>, <column>), e.g. ('min', 'value').

  • Datashader object: ds.first, ds.last, ds.min, and ds.max.

Added in version 0.12.0: Requires holoviews>=1.21. Requires bokeh>=3.7.

threshold (float, default=0.5)

When using dynspread, this value defines the minimum density of overlapping points required before the spreading operation is applied. Values between 0 and 1, where 1 means always spread and 0 means never spread.

x_sampling/y_sampling (number or None, default=None:)

Specifies the smallest allowed sampling interval along the x/y axis. Used when rasterizing or datashading.

See this page for more information on these options.

Geographic Options#

Options for geographic plots, including map projections, tile overlays, and geographic features like coastlines and borders (most of these options require GeoViews to be installed):

Parameters

Description

coastline (bool, default=False)

Whether to display a coastline on top of the plot, setting coastline=’10m’/’50m’/’110m’ specifies a specific scale.

crs (str or int or pyproj.CRS or pyproj.Proj or cartopy.CRS or None)

Coordinate reference system of the data (input projection) specified as a string or integer EPSG code, a CRS or Proj pyproj object, a Cartopy CRS object or class name, a WKT string, or a proj.4 string. Defaults to PlateCarree.

features (dict or list or None, default=None)

A list of features or a dictionary of features and the scale at which to render it. Available features include ‘borders’, ‘coastline’, ‘lakes’, ‘land’, ‘ocean’, ‘rivers’ and ‘states’. Available scales include ‘10m’/’50m’/’110m’.

geo (bool, default=False)

Whether the plot should be treated as geographic (and assume PlateCarree, i.e. lat/lon coordinates).

global_extent (bool, default=False)

Whether to expand the plot extent to span the whole globe.

project (bool, default=False)

Whether to project the data before plotting (adds initial overhead but avoids projecting data when plot is dynamically updated).

projection (str or int or pyproj.CRS or pyproj.Proj or cartopy.CRS or bool or None)

Coordinate reference system of the plot (output projection) specified as a string or integer EPSG code, a CRS or Proj pyproj object, a Cartopy CRS object or class name, a WKT string, or a proj.4 string. Defaults to PlateCarree.

tiles (bool or str or xyzservices.TileProvider or holoviews.Tiles or geoviews.WMTS or None, default=False)

Whether to overlay the plot on a tile source. If coordinate values fall within lat/lon bounds, auto-projects to EPSG:3857, unless projection=False:

  • True: OpenStreetMap layer

  • xyzservices.TileProvider instance (requires xyzservices to be installed)

  • a map string name based on one of the default layers made available by HoloViews or GeoViews.

  • a holoviews.Tiles or geoviews.WMTS instance or class

tiles_opts (dict or None, default=None)

Options to customize the tiles layer created when tiles is set, e.g. dict(alpha=0.5).

See this page for more information on these options.

Streaming Options#

Options for handling live data streams:

Parameters

Description

backlog (int, default=1000)

Maximum number of rows to keep in the stream buffer when using a streaming data source.

stream (holoviews.streams.Stream or None, default=None)

A stream object for streaming plots, allowing data updates without re-rendering the entire plot.

See this page for more information on these options.