Plotly · Module

fig.add_hline

Adds a horizontal layout line at a specified y-coordinate, spanning infinitely in the x-dimension. It supports subplot targeting, optional annotation, and line styling.

How it works

add_hline inserts a horizontal layout shape whose y-coordinate is expressed in data units while it spans the plot in the x-dimension. It can target selected subplot rows and columns, skip empty subplots, and accept line or annotation options through its arguments.

Syntax

fig.add_hline(y, row="all", col="all", exclude_empty_subplots=True, annotation=None, **kwargs)

Parameters

Name	Type	Description
`y`	`float or int`	A number representing the y coordinate of the horizontal line.
`row`	`None, int, or "all"`	Subplot row for the shape, indexed starting at 1; `"all"` addresses all rows in the specified columns.
`col`	`None, int, or "all"`	Subplot column for the shape, indexed starting at 1; `"all"` addresses all columns in the specified rows.
`exclude_empty_subplots`	`Boolean`	When true, omit the shape from subplots that contain no plotted data.
`annotation`	`dict or compatible annotation object`	Annotation object to associate with the shape.
`**kwargs`	`keyword arguments`	Additional shape properties; annotation properties can be supplied with the `annotation_` prefix.

Returns

The modified plotly.graph_objects.Figure.

Key points

Use it for a reference, threshold, or baseline that should span the complete horizontal plotting extent.
The required y argument places the line at a numeric y-value in the plot's data coordinate system.
Subplot row and column indices are one-based when selecting a specific subplot.
By default, the line is applied across all applicable subplot rows and columns.
Add a visible label with annotation_text, and control its placement using annotation positioning options.
The line becomes part of the figure layout's shapes collection, not a separate plotted data series.

Common mistakes

With the default setting, an added line is omitted from empty subplots; set exclude_empty_subplots=False when every addressed subplot should receive it.
The special row="all" value targets every row in the chosen column or columns, so use a numeric row when the line belongs in only one subplot.
Annotation properties must be supplied with the annotation_ prefix, such as annotation_text and annotation_position.

Example: Add a labelled threshold line

import plotly.express as px

fig = px.scatter(px.data.iris(), x="petal_length", y="petal_width")
fig.add_hline(y=0.9, line_dash="dash", line_color="red", annotation_text="threshold")
fig.show()

Adds a dashed red horizontal threshold at y = 0.9 and labels it.

When to use it

Mark a target, limit, or alert threshold across a chart.

Monitoring and dashboards

Show a baseline or reference level over plotted observations.

Statistical graphics

Apply one common horizontal reference to selected or all subplot cells.

Subplot figures

Interview questions

QWhat does add_hline do?

It adds a horizontal line at the supplied y-coordinate and extends infinitely in the x-dimension. The line is added as a layout shape rather than as a data trace.

Follow-up: How would you limit it to one subplot? Pass the target subplot's numeric row and col values instead of using their default "all" values.

QWhat are the main parameters?

y is the number representing the horizontal line's y-coordinate. row and col select subplot locations, while exclude_empty_subplots controls whether empty addressed subplots are skipped.

Follow-up: How can the line be labelled? Use annotation_text and other annotation options, or pass an annotation object.

QWhat does the method return and how is it styled?

The method returns the plotly.graph_objects.Figure, allowing calls to be chained or followed by additional figure modifications. Styling is supplied through keyword arguments, including line properties.

Follow-up: How can annotation styling be passed? Prefix layout annotation properties with annotation_, for example annotation_font_size.

add_vline
add_hrect
add_vrect
add_shape
plotly.graph_objects.Figure

Source: plotly.graph_objects.Figure. Checked 2026-10-15.