Plotly · Module

fig.add_vline

Adds a vertical reference line at an x coordinate to a Plotly figure or subplot. It can be targeted to subplot cells, annotated, and styled through shape-related options.

Since: 4.12

How it works

Call add_vline on a figure with the x-coordinate where the line should appear. The method adds a layout shape that is anchored to that x value and extends across the plot in the y direction; optional subplot, annotation, and shape-styling arguments control where and how it is displayed.

Syntax

fig.add_vline(x, row='all', col='all', exclude_empty_subplots=True, annotation=None, **kwargs)

Parameters

Name	Type	Description
`x`	`number`	A number representing the x coordinate of the vertical line.
`row`	`or 'all'`	Subplot row indexed starting at 1, or `all`.
`col`	`or 'all'`	Subplot column indexed starting at 1, or `all`.
`exclude_empty_subplots`	`boolean`	When true, omit the shape from subplots without plotted data.
`annotation`	`dict or None`	Optional annotation configuration for the line.
`**kwargs`	`keyword arguments`	Additional shape and annotation properties.

Returns

The updated plotly.graph_objects.Figure.

Key points

Use this method for a reference line fixed at one x coordinate and spanning the plot vertically.
The required x argument determines where the line is positioned along the x-axis.
row uses one-based subplot indexing; use it to target a specific subplot row.
col also uses one-based indexing and can narrow placement to a particular subplot column.
The line is stored as a layout shape, so shape-related keyword arguments can control its appearance.

Common mistakes

With subplot figures, the default excludes empty subplots; set exclude_empty_subplots=False if the line should also appear there.
When targeting subplots explicitly, provide row and/or col; leaving both unset does not address every subplot.

Example: Add a styled vertical reference line

import plotly.express as px

fig = px.scatter(px.data.iris(), x="petal_length", y="petal_width")
fig.add_vline(x=2.5, line_width=3, line_dash="dash", line_color="green")
fig.show()

Creates a scatter plot and adds a styled vertical reference line at x = 2.5.

When to use it

Reference markers

Mark a threshold, target, or event time on a chart.

Subplot guides

Show a vertical guide across selected cells in a subplot layout.

Styled boundaries

Visually distinguish a cutoff using dash, width, and color options.

Interview questions

QWhat does fig.add_vline(x=...) do?

add_vline adds a vertical line at the supplied x coordinate and makes it extend infinitely in the y dimension. It returns the figure, so calls can be chained or the updated figure can be assigned.

Follow-up: How would you restrict it to one subplot? Pass the target subplot's row and col values, and control empty-subplot behavior with exclude_empty_subplots.

QWhich arguments are most useful beyond x?

x is the numeric x coordinate of the line. row and col select subplot positions, while annotation and additional keyword arguments can add labeling and style the underlying shape.

Follow-up: How can the line be styled? Use shape options such as line_width, line_dash, and line_color through keyword arguments.

QHow does subplot selection work?

By default, row and col are both all, and empty subplots are excluded. The method can therefore place the line across applicable subplot cells without adding it to cells that contain no plotted data.

Follow-up: What happens when only one of row or col is specified? The unspecified dimension remains addressed according to its default subplot selection behavior.

Figure.add_hline
Figure.add_vrect
Figure.add_hrect
Figure.add_shape

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