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
|
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 |
aspect#
The aspect option controls the frame shape—that is, the rectangular drawing area that contains only the plotted data (excluding axes, labels, legends, and margins)—by setting the ratio of its width to its height. By default (aspect=None), HoloViews does not enforce any new ratio: it simply uses whatever frame_height and frame_width you’ve provided or falls back to its built-in defaults of 300 × 700 px if neither is set.
Use:
'square': Forces a square frame.If you set only
frame_width, the height will be made equal to it.If you set only
frame_height, the width will be matched to it.If you set both, the aspect value will be ignored with a warning displayed.
'equal': Ensures the frame maintains the default height to width ratios (300:700).If you specify
frame_widthbut omitframe_height, the height is re-computed to match the original ratios.If you specify
frame_heightbut omitframe_width, the width is re-computed to match the original ratios.If you explicitly set both
frame_widthandframe_height, those values are respected and the aspect value ignored.
A float, e.g.
2.0: Directly sets the width : height ratio (soaspect=2.0makes it twice as wide as it is tall).
If you need to control the data-unit scaling (so that one y-unit equals one x-unit), use the data_aspect option instead.
Keeping aspect and data_aspect distinct lets you manage both your plot’s pixel proportions and your data-unit proportions independently.
import hvplot.pandas # noqa
df = hvplot.sampledata.penguins("pandas")
opts = dict(x='bill_length_mm', y='bill_depth_mm', frame_width=200)
(
df.hvplot.scatter(aspect=None, title="Default aspect", **opts)
+ df.hvplot.scatter(aspect=0.6, title="3:5 ratio", **opts)
+ df.hvplot.scatter(aspect='square', title="Square plot (1:1 ratio)", **opts)
+ df.hvplot.scatter(aspect='equal', title="Re-computed frame_height", **opts)
).cols(2)
See also
data_aspect#
The data_aspect option sets the scaling between axis units, i.e., the ratio of the number of y-units per x-unit.
This is particularly useful for geographic or image data where you want equal distances on both axes (e.g., a degree of latitude and longitude should appear equal).
Unlike aspect which controls plot shape, data_aspect affects the visual scaling of the data itself.
import hvplot.xarray # noqa
ds = hvplot.sampledata.air_temperature("xarray").sel(time="2014-02-25 12:00")
ds.hvplot.image(data_aspect=1)
frame_width / frame_height#
The frame_width and frame_height options determine the width and height of the data area within the plot. They define the size of the plot’s core region (excluding axes, legends, and margins), allowing precise control over how the data is displayed.
import hvplot.pandas # noqa
df = hvplot.sampledata.penguins("pandas")
df.hvplot.scatter(
"bill_length_mm", "bill_depth_mm", by="species",
frame_width=300, frame_height=200
)
Setting width and height to the same values, notice how the plot below ends up much smaller than the one above, as width and height affect the whole plot area.
import hvplot.pandas # noqa
df = hvplot.sampledata.penguins("pandas")
df.hvplot.scatter(
"bill_length_mm", "bill_depth_mm", by="species",
width=300, height=200
)
max_width / max_height#
The max_width and max_height options set the maximum allowed dimensions for the plot. These options come into play in responsive or dynamic layouts to ensure that the plot does not grow beyond the specified limits when the browser window is resized.
import hvplot.xarray # noqa
df = hvplot.sampledata.air_temperature("xarray").sel(time="2014-02-25 12:00")
df.hvplot.image(max_width=600, max_height=400, height=400, responsive=True)
By setting max_width=600, the plot cannot extend beyond 600 pixel units horizontally no matter the screen size the plot is being viewed in.
Tip
Try to view this plot on the largest screen you can find and see if the plot width extends beyond 600 pixel units.
See also
min_width / min_height#
Similar to max_width and max_height, these options define the minimum width and height for the plot. They ensure that the plot will not shrink below the specified dimensions in responsive layouts, helping maintain legibility even on smaller screens.
import hvplot.xarray # noqa
df = hvplot.sampledata.air_temperature("xarray").sel(time="2014-02-25 12:00")
df.hvplot.image(min_width=300, min_height=200, height=400, responsive=True)
Tip
View this plot using your phone screen to see how the plot resizes
See also
height#
The height and width option sets the overall height and width of the plot in pixels. By default, this is usually set to 300 and 700 pixels respectively. This dimension includes all components of the plot such as titles, labels, and margins.
import hvplot.xarray # noqa
df = hvplot.sampledata.air_temperature("xarray").sel(time="2014-02-25 12:00")
df.hvplot.image(height=300, width=600)
width#
See height option above.
padding#
The padding option expands the plot’s automatically computed axis limits by a given fraction. When hvPlot determines the x and y ranges based on your data, it finds the minimum and maximum values needed to display all points. With padding applied, these ranges are extended by the specified fraction so that data points near the edges have more space. The padding value can be given as a single number for uniform padding, a tuple to specify different padding for the x- and y-axes, or even a nested tuple to set distinct padding for the upper and lower bounds of each axis.
import pandas as pd
import hvplot.pandas # noqa
df = pd.DataFrame({'x': [0, 1, 0, -1], 'y': [-1, 0, 1, 0]})
# Add 20% extra space around the auto-determined axis ranges
df.hvplot.scatter(x='x', y='y', padding=0.2, height=200)
import pandas as pd
import hvplot.pandas # noqa
df = pd.DataFrame({'x': [0, 1, 0, -1], 'y': [-1, 0, 1, 0]})
# Add 20% on the x-axis and 5% on the y-axis
df.hvplot.scatter(x='x', y='y', padding=(0.2, 0.05), height=200)
responsive#
When set to True, the responsive option allows the plot to automatically adjust its size based on the browser window. Note that responsive mode works only if at least one dimension (width or height) is left undefined; otherwise, the plot size remains fixed. This option is not supported by the static plotting backend Matplotlib.
import hvplot.pandas # noqa
df = hvplot.sampledata.penguins("pandas")
df.hvplot.scatter(
x='bill_length_mm', y='bill_depth_mm', by='species',
height=300, responsive=True
)
widget_location#
Control where widgets appear. 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'.
Important
When this option is set the object returned is no longer a HoloViews object but a Panel layout. In the future we intend to address that, follow this issue for more information.
import hvplot.pandas # noqa
df = hvplot.sampledata.penguins("pandas")
df.hvplot.scatter(
x='bill_length_mm', y='bill_depth_mm', frame_width=250,
groupby='species', title='Default widget location'
)
import hvplot.pandas # noqa
df = hvplot.sampledata.penguins("pandas")
df.hvplot.scatter(
x='bill_length_mm', y='bill_depth_mm', frame_width=250,
groupby='species', title='Widget on the top',
widget_location='top',
)