docs: Update docs for v7 by camdecoster · Pull Request #5708 · plotly/plotly.py

camdecoster · 2026-08-21T23:12:35Z

Link to issue

Closes #(issue number)

Description of change

Update docs to reflect the changes from v7 (and plotly.js v4).

Demo

Testing strategy

Additional information (optional)

Guidelines

I have reviewed the pull request guidelines and the Code of Conduct and confirm that this PR follows them.
I have added an entry to the changelog if needed (not required for documentation PRs).

emilykl

📖 👍

emilykl · 2026-08-25T19:38:40Z

 #### LaTeX Typesetting

-Figure titles, axis labels and annotations all accept LaTeX directives for rendering mathematical formulas and notation, when the entire label is surrounded by dollar signs `$...$`. This rendering is handled by the [MathJax library](https://www.npmjs.com/package/mathjax?activeTab=versions), which must be loaded in the environment where figures are being rendered. MathJax is included by default in Jupyter-like environments. When embedding Plotly figures in other contexts it may be required to ensure that MathJax is separately loaded, for example via a `<script>` tag pointing to a content-delivery network (CDN). Versions 2 and 3 are supported.
+Figure titles, axis labels and annotations all accept LaTeX directives for rendering mathematical formulas and notation, when the entire label is surrounded by dollar signs `$...$`. This rendering is handled by the [MathJax library](https://www.npmjs.com/package/mathjax?activeTab=versions), which must be loaded in the environment where figures are being rendered. MathJax is included by default in Jupyter-like environments. When embedding Plotly figures in other contexts it may be required to ensure that MathJax is separately loaded, for example via a `<script>` tag pointing to a content-delivery network (CDN). Version 7 supports MathJax versions 3 and 4. Earlier versions support MathJax versions 2 and 3.


Alas, another pitfall of not having docs versioning...

Suggesting some slightly clearer wording

Suggested change

Figure titles, axis labels and annotations all accept LaTeX directives for rendering mathematical formulas and notation, when the entire label is surrounded by dollar signs `$...$`. This rendering is handled by the [MathJax library](https://www.npmjs.com/package/mathjax?activeTab=versions), which must be loaded in the environment where figures are being rendered. MathJax is included by default in Jupyter-like environments. When embedding Plotly figures in other contexts it may be required to ensure that MathJax is separately loaded, for example via a `<script>` tag pointing to a content-delivery network (CDN). Version 7 supports MathJax versions 3 and 4. Earlier versions support MathJax versions 2 and 3.

Figure titles, axis labels and annotations all accept LaTeX directives for rendering mathematical formulas and notation, when the entire label is surrounded by dollar signs `$...$`. This rendering is handled by the [MathJax library](https://www.npmjs.com/package/mathjax?activeTab=versions), which must be loaded in the environment where figures are being rendered. MathJax is included by default in Jupyter-like environments. When embedding Plotly figures in other contexts it may be required to ensure that MathJax is separately loaded, for example via a `<script>` tag pointing to a content-delivery network (CDN). plotly.py v7 and above supports MathJax versions 3 and 4. (Earlier plotly.py versions support MathJax versions 2 and 3.)

emilykl · 2026-08-25T19:42:56Z


 1. GPU requirement: WebGL is a GPU (graphics card) technology and therefore requires specific hardware which is available in most but not all cases and is supported by most but not all browsers.
-2. Rasterization: WebGL-rendered data is drawn as a grid of pixels rather than as individual shapes, so can appear pixelated or fuzz in certain cases, and when exported to static file formats will appear pixelated on zoom. In addition, text rendering will differ between SVG and WebGL-powered traces.
+2. Rasterization: WebGL-rendered data is drawn as a grid of pixels rather than as individual shapes, so can appear pixelated or fuzzy in certain cases. This also applies to static export: when a figure with WebGL traces is exported to a *vector* format such as SVG or PDF, the WebGL traces are embedded as an encapsulated raster (a bitmap) rather than as true vectors, so those parts will appear pixelated on zoom. To force fully-vector output, use `render_mode="svg"` (see [WebGL with Plotly Express](#webgl-with-plotly-express) below). In addition, text rendering will differ between SVG and WebGL-powered traces.


Suggested change

2. Rasterization: WebGL-rendered data is drawn as a grid of pixels rather than as individual shapes, so can appear pixelated or fuzzy in certain cases. This also applies to static export: when a figure with WebGL traces is exported to a *vector* format such as SVG or PDF, the WebGL traces are embedded as an encapsulated raster (a bitmap) rather than as true vectors, so those parts will appear pixelated on zoom. To force fully-vector output, use `render_mode="svg"` (see [WebGL with Plotly Express](#webgl-with-plotly-express) below). In addition, text rendering will differ between SVG and WebGL-powered traces.

2. Rasterization: WebGL-rendered data is drawn as a grid of pixels rather than as individual shapes, so can appear pixelated or fuzzy in certain cases. This also applies to static export: when a figure with WebGL traces is exported to a *vector* format such as SVG or PDF, the WebGL traces are embedded as an encapsulated raster (a bitmap) rather than as true vectors, so those parts will appear pixelated on zoom. To force fully-vector output, use `render_mode="svg"` to supported Plotly Express functions (see [WebGL with Plotly Express](#webgl-with-plotly-express) below). In addition, text rendering will differ between SVG and WebGL-powered traces.

emilykl · 2026-08-25T19:45:33Z

+
+`anchor` sets which part of the arrow sits at its `(x, y)` position: `"tail"` (the default), `"tip"`, or `"center"`.

+Arrow length is controlled by `sizemode` and `sizeref`. With `sizemode="scaled"` (the default), lengths are normalized against the longest vector in the field and the density of points, so a dense grid stays readable whatever the underlying values are. `sizemode="raw"` draws each arrow at its own magnitude instead. `sizeref` is a multiplier applied on top: values below 1 shorten every arrow, above 1 lengthen them.


Suggested change

Arrow length is controlled by `sizemode` and `sizeref`. With `sizemode="scaled"` (the default), lengths are normalized against the longest vector in the field and the density of points, so a dense grid stays readable whatever the underlying values are. `sizemode="raw"` draws each arrow at its own magnitude instead. `sizeref` is a multiplier applied on top: values below 1 shorten every arrow, above 1 lengthen them.

Arrow length is controlled by `lengthmode` and `lengthfactor`. With `lengthmode="scaled"` (the default), lengths are normalized against the longest vector in the field and the density of points, so a dense grid stays readable whatever the underlying values are. `lengthmode="raw"` draws each arrow at its specified magnitude determined by `u` and `v`. `lengthfactor` is a multiplier applied on top: values below 1 shorten every arrow, above 1 lengthen them.

emilykl · 2026-08-25T19:45:50Z

-fig = ff.create_quiver(x, y, u, v)
+fig = go.Figure(go.Quiver(x=x.flatten(), y=y.flatten(),
+                          u=u.flatten(), v=v.flatten(),
+                          anchor="center", sizeref=0.8))


Suggested change

anchor="center", sizeref=0.8))

anchor="center", lengthfactor=0.8))

emilykl · 2026-08-25T19:46:48Z

 fig.show()
 ```

+#### Quiver Plots with the Figure Factory


Suggested change

#### Quiver Plots with the Figure Factory

#### Quiver Plots with Figure Factory

emilykl · 2026-08-25T20:07:11Z

+Two new attributes let you override the automatic ordering:
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Sankey(
+    node=dict(label=["A", "B", "C", "D", "Z", "Y", "X", "W"], pad=15, thickness=20,
+              sort="input"),
+    link=dict(source=[0, 1, 2, 3], target=[4, 5, 6, 7], value=[4, 3, 2, 1],
+              sort="input"),
+))
+
+fig.show()
+```
+
+With the default `"auto"`, the layout reorders nodes within a column, and links within a node, to reduce crossings. `"input"` keeps the order given in `node.label` and in `link.source` / `link.target`, which is useful when the order carries meaning or you need a layout that is stable across renders.
+
+A third attribute, `sankey.direction`, flips the flow along the `orientation` axis. Set it to `"reversed"` to put sources on the right of a horizontal diagram, or at the bottom of a vertical one. See [Sankey Diagram](/python/sankey-diagram/).


Suggested change

Two new attributes let you override the automatic ordering:

```python

import plotly.graph_objects as go

fig = go.Figure(go.Sankey(

node=dict(label=["A", "B", "C", "D", "Z", "Y", "X", "W"], pad=15, thickness=20,

sort="input"),

link=dict(source=[0, 1, 2, 3], target=[4, 5, 6, 7], value=[4, 3, 2, 1],

sort="input"),

))

fig.show()

```

With the default `"auto"`, the layout reorders nodes within a column, and links within a node, to reduce crossings. `"input"` keeps the order given in `node.label` and in `link.source` / `link.target`, which is useful when the order carries meaning or you need a layout that is stable across renders.

A third attribute, `sankey.direction`, flips the flow along the `orientation` axis. Set it to `"reversed"` to put sources on the right of a horizontal diagram, or at the bottom of a vertical one. See [Sankey Diagram](/python/sankey-diagram/).

Two new Sankey attributes let you override the automatic ordering: `node.sort` and `link.sort`.

For both attributes, the default value `"auto"` reorders nodes within a column, and links within a node, to reduce crossings. `"input"` keeps the order given in `node.label` and in `link.source` / `link.target`, which is useful when the order carries meaning or you need a layout that is stable across renders.

```python

import plotly.graph_objects as go

fig = go.Figure(go.Sankey(

node=dict(label=["A", "B", "C", "D", "Z", "Y", "X", "W"], pad=15, thickness=20,

sort="input"),

link=dict(source=[0, 1, 2, 3], target=[4, 5, 6, 7], value=[4, 3, 2, 1],

sort="input"),

))

fig.show()

A third attribute, direction, controls the flow along the orientation axis. The default value of "forward" results in a chart which flows from left to right horizontally, or top to bottom vertically. Set it to "reversed" to create a chart which flows from right to left or bottom to top. See Sankey Diagram.

emilykl · 2026-08-25T20:07:44Z

+
+### `go.Quiver`
+
+Version 7 adds a `Quiver` trace type for 2D vector fields, which replaces the `create_quiver` figure factory as the recommended approach. See [Quiver Plots](/python/quiver-plots/).


Suggested change

Version 7 adds a `Quiver` trace type for 2D vector fields, which replaces the `create_quiver` figure factory as the recommended approach. See [Quiver Plots](/python/quiver-plots/).

Version 7 adds a `Quiver` trace type for 2D vector fields, which supercedes the `create_quiver` figure factory as the recommended approach for creating quiver plots. See [Quiver Plots](/python/quiver-plots/) for more detail.

emilykl · 2026-08-25T20:09:13Z

+
+### Geo zoom limits
+
+`layout.geo.projection.minscale` and `maxscale` clamp how far users can zoom a `geo` subplot. Both are multipliers of `projection.scale`:


Suggested change

`layout.geo.projection.minscale` and `maxscale` clamp how far users can zoom a `geo` subplot. Both are multipliers of `projection.scale`:

New attributes `layout.geo.projection.minscale` and `maxscale` clamp how far users can zoom a `geo` subplot. Both are multipliers of `projection.scale`:

emilykl · 2026-08-25T20:10:56Z

  * [Dendrograms](/python/dendrogram/)
  * [Hexagonal Binning Tile Map](/python/hexbin-map/)
-  * [Quiver Plots](/python/quiver-plots/)
+  * [Quiver Plots](/python/quiver-plots/) — since version 7.0, quiver plots are better made with the `go.Quiver` trace type. `create_quiver` remains available for its `angle` and `scaleratio` options.


Suggested change

* [Quiver Plots](/python/quiver-plots/) — since version 7.0, quiver plots are better made with the `go.Quiver` trace type. `create_quiver` remains available for its `angle` and `scaleratio` options.

* [Quiver Plots](/python/quiver-plots/) — since version 7.0, the recommended function for creating quiver plots is `go.Quiver`, but `create_quiver` remains available.

emilykl · 2026-08-25T20:24:18Z

Needs a section on the arrowref property. After the ### Arrow Anchor and Length section seems like a reasonable place. Suggested content:

### Setting Arrow Reference The `arrowref` property controls how the `u` and `v` vector components are interpreted, and how the vector arrows respond to zooming along a single axis. By default, `arrowref="data"`, meaning that `u` and `v` are interpreted as data values. This means that the angle of the vectors depends on the relative scale of the two axes, and the apparent angle will change when zooming along one axis. This is the appropriate behavior when `u` and `v` represent data-space values, such as when illustrating a magnetic field. To instead interpret `u` and `v` in pixel values, set `arrowref="paper"`, which will always draw vectors at the same angle regardless of the axis scales. This is the correct behavior when the vectors correspond to abstract values which are not linked to the data space.

docs: Update docs for v7

bf349c8

Base automatically changed from v7.0 to main August 25, 2026 17:07

emilykl approved these changes Aug 25, 2026

View reviewed changes

Navigation Menu

Uh oh!

Uh oh!

docs: Update docs for v7 - #5708

docs: Update docs for v7#5708
camdecoster wants to merge 1 commit into
mainfrom
cam/update-docs-v7

camdecoster commented Aug 21, 2026

Uh oh!

emilykl left a comment

Uh oh!

emilykl Aug 25, 2026

Uh oh!

emilykl Aug 25, 2026

Uh oh!

emilykl Aug 25, 2026

Uh oh!

emilykl Aug 25, 2026

Uh oh!

emilykl Aug 25, 2026

Uh oh!

emilykl Aug 25, 2026

Uh oh!

emilykl Aug 25, 2026

Uh oh!

emilykl Aug 25, 2026

Uh oh!

emilykl Aug 25, 2026

Uh oh!

emilykl Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		`anchor` sets which part of the arrow sits at its `(x, y)` position: `"tail"` (the default), `"tip"`, or `"center"`.

		Arrow length is controlled by `sizemode` and `sizeref`. With `sizemode="scaled"` (the default), lengths are normalized against the longest vector in the field and the density of points, so a dense grid stays readable whatever the underlying values are. `sizemode="raw"` draws each arrow at its own magnitude instead. `sizeref` is a multiplier applied on top: values below 1 shorten every arrow, above 1 lengthen them.

	anchor="center", sizeref=0.8))
	anchor="center", lengthfactor=0.8))

	#### Quiver Plots with the Figure Factory
	#### Quiver Plots with Figure Factory


		### `go.Quiver`

		Version 7 adds a `Quiver` trace type for 2D vector fields, which replaces the `create_quiver` figure factory as the recommended approach. See [Quiver Plots](/python/quiver-plots/).


		### Geo zoom limits

		`layout.geo.projection.minscale` and `maxscale` clamp how far users can zoom a `geo` subplot. Both are multipliers of `projection.scale`:

	`layout.geo.projection.minscale` and `maxscale` clamp how far users can zoom a `geo` subplot. Both are multipliers of `projection.scale`:
	New attributes `layout.geo.projection.minscale` and `maxscale` clamp how far users can zoom a `geo` subplot. Both are multipliers of `projection.scale`:

	* [Quiver Plots](/python/quiver-plots/) — since version 7.0, quiver plots are better made with the `go.Quiver` trace type. `create_quiver` remains available for its `angle` and `scaleratio` options.
	* [Quiver Plots](/python/quiver-plots/) — since version 7.0, the recommended function for creating quiver plots is `go.Quiver`, but `create_quiver` remains available.

Uh oh!

Uh oh!

Conversation

camdecoster commented Aug 21, 2026

Link to issue

Description of change

Demo

Testing strategy

Additional information (optional)

Guidelines

Uh oh!

emilykl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants