Add quiver trace type for vector field visualization by degzhaus · Pull Request #7710 · plotly/plotly.js · GitHub

Overview

This PR adds a new quiver trace type to Plotly.js for visualizing 2D vector fields using arrows.

Continuation of #7584

Features

Vector positioning: Arrows placed at x, y coordinates with direction/magnitude from u, v components
Sizing modes: scaled (normalized), or raw vector lengths via
- Fixed scale factor can be applied via sizeref
Angle modes: Use anglemode to set arrow angle based on data axis scales (data) or visual angle on page
Arrow anchoring: Position arrows by tail, tip, or center
Colorscale support: Color arrows by magnitude or custom scalar field (c array)
Styling: Configurable line color, width, dash patterns via marker.line.* attributes
Arrowhead sizing: Adjustable arrowhead size via marker.arrowsize
Full interactivity: Hover support with customizable hovertemplate and point selection
Animation support: Animatable x, y, u, v, and c arrays

API

Plotly.newPlot('div', [{
  type: 'quiver',
  x: [0, 1, 2],
  y: [0, 1, 2],
  u: [1, 0, -1],  // x-component of vectors
  v: [0, 1, 0],   // y-component of vectors
  sizemode: 'scaled',  //  'scaled' | 'raw'
  anglemode: 'data',  // 'data' | 'paper'
  sizeref: 0.5,
  anchor: 'tail',  // 'tail' | 'tip' | 'center'
  marker: {
    line: { width: 2 },
    colorscale: 'Viridis',
  },
}]);

Screenshots

Examples taken from plotly.com/python/quiver-plots

Gist with example code

Quiver Plot, vector field with mesh grid (colored by magnitude)

Quiver plot, vector field with mesh grid (colored by independent color array)

Testing

✅ Jasmine unit tests
✅ Image tests

Files Changed

New files (src/traces/quiver/)

index.js - Trace module definition
attributes.js - Attribute schema
defaults.js - Default value handling
calc.js - Data calculation
plot.js - SVG rendering
style.js - Styling
hover.js - Hover behavior
select_points.js - Selection support
event_data.js - Event data formatting
format_labels.js - Label formatting

Modified

lib/index.js & lib/index-strict.js - Build integration

Tests

test/jasmine/tests/quiver_test.js - Unit tests
test/image/mocks/quiver_*.json - New image mocks
test/image/baselines/quiver_*.png - Baseline images

Known issues

Axes autorange when anglemode is 'paper' is not quite correct, especially when vectors are long and/or axes aspect ratio is very different from plot aspect ratio.
The squishing/stretching of existing arrows that happens during drag when resizing the plot area is correct when anglemode is 'data', but incorrect when anglemode is 'paper'. Arrows should not be squished/stretched in that case. There's no quiver-specific drag code that I can see, so I think the behavior is implemented at a lower level and we may need to override it under certain conditions. In any case, though, after the drag is released, the arrows adjust to their correct positions.
The arrow-scaling heuristic based on point density works OK, but could probably be improved. In particular, for grids, as the size of the grid increases, arrow size approaches the distance between two adjacent grid points, so at the very least, the computed scale factor should probably be reduced by 5-10%. This heuristic probably also doesn't produce good results for very irregularly-spaced points, but I'm not sure what metric would be better in that case.
Arrow scaling could be improved when a trace has just a single point, or all points share a single x/y value. Right now we just scale so that the longest vector has magnitude 1 in x*y space. For the case of a single data point, I'm not sure we can do much better, but for the case of multiple points in a line we can definitely choose a better scale factor (use "distance between points" rather than "point density").
Log axes aren't really handled, but I'm not sure quiver traces on log axes make sense anyway. We should probably explicitly disallow log axes.
Animations do not work (Plotly.animate() ultimately updates the plot with the new data, but the transition is not animated)

Remaining TODOs (in addition to the above)

Increase coverage of Jasmine and image tests
Reflect on attribute naming for anglemode / sizemode / sizeref

Thanks again for the great comments, @emilykl !

I will attempt to reference commits inline from this comment here:
#7584 (comment)

-- Bug Fixes --

"The axis ranges don't automatically adjust to include the full length of the arrows" fixed here:
96845a8

"Colorscale seems broken in the latest version" fixed here:
3cd525c

"Legends are missing icons" fixed here:
6a37260

"selected and unselected styling options" fixed here:
96bb82c

"The text property also seems broken in the latest iteration" fixed here:
69516db

"Display of colorbars does not seem to work" fixed here:
b19cce2

-- API Refinements --

"c should become marker.color" fixed here:
3cd525c

"The line options should be nested under marker.line",
"Move arrowheadsize under marker so that it becomes marker.arrowheadsize",
"No need for duplicate arrowwidth property",
"arrow_scale should be removed as well" all fixed here:
c7f073d

Here are the followups for the remaining 3 comments from: #7584, @emilykl :

"Could we plausibly reuse the src/traces/scatter/select.js selectPoints() function" fixed here:
4f91255

"Should probably call the hasColorscale() function here" fixed here:
82e6bc1

"Can you look into whether we can/should use the handleXYDefaults() function here" fixed here:
7135b52

Alrighty, @emilykl , thanks again for your great feedback and patience as I addressed it!

I have pushed all my fixes and tested locally, I think we're close 🤞

Great news @degzhaus ! Thank you for the continued work and the clear summary. I will try to take another look within the next week. Feel free to ping me next Tuesday if I haven't gotten back to you by then.

hey there, @emilykl, hope you are having a great start to the week!

i just rebased and pushed again 🥳

@degzhaus would you be able to merge/rebase one more time? Sorry for the extra work. We just changed how our test images are generated and that led to the baseline conflicts with this branch.

Hi @degzhaus ! I've run down the list of issues from my previous review, and most seem to be fixed 🥳 However I am still seeing these two issues:

The axis ranges don't automatically adjust to include the full length of the arrows. See example here. By default if no axis range is specified in the layout, the entirety of all arrows should be visible.

The baseline images quiver_anchor.png, quiver_arrow-styling.png, quiver_sizemode.png, and quiver_zero-vectors.png show cut-off arrows.

Colorscale seems broken in the latest version, unless I'm missing something. The arrows in quiver_colorscale.png and quiver_custom-colorscale.png seem to be all the same color.

The baseline images in quiver_colorscale.png and quiver_custom-colorscale.png are still all the same color. Also the quiver_colorscale should provide a value for marker.color; otherwise the arrows will not display a colorscale even if there was no bug.

I'm still doing a bit more testing so I will leave another comment if I find anything else. @camdecoster is taking a look as well, so keep an eye out for his comments.

Finally when you have a chance please merge/rebase against the master branch! We recently overhauled the CI pipeline and you will need to merge/rebase in order to run the new pipeline.

Could you please remove 'cm' and 'center' as values? One term for the middle should be fine.

Much simpler, thanks, removed redundant anchor value options:

94dc00d

Did you mean to pasate baseAttrs on top of attrs? I think it would be safer to handle it this way. That's what is typically done when building attributes.

Suggested change

      
            extendFlat(attrs, baseAttrs);
          
            attrs = extendFlat({}, baseAttrs, attrs);

Good call, thank you, changed here:

2e214c7

If marker.color is an array, lineColor will be undefined. This would result in the unselected color being undefined as well. Could you update the code to handle this situation and apply a dim version (via opacity) of the selected color?

Thanks for pointing this out. I was not able to figure out exactly how to do that with opacity, so I styled the path with stroke-opacity here:

f3789e6

Happy to adjust if you have something else in mind!

Could you add a guard (here or elsewhere) that handles if normMin and normMax are infinite? This is an edge case that would require all invalid data, but we should guard against it.

Good callout, thank you, Cam, added guard here:

dd71b94

Could you delete these unused imports?

Absolutely, removed here:

eba15eb

@degzhaus are you still interested in finishing up this PR?

@degzhaus are you still interested in finishing up this PR?

i am, and pardon my delay, Cam! i have begun working through the recent comments, hope to be ready for another round of review this week 🤞

Great to hear! Ping us when you're ready for another review.

Hello @degzhaus! We're working toward a new major release and we're interested in including this new trace as part of that. If we want that to happen, this PR will need to be merged in the next week or so. Do you think you'll have time to finish it up by then? We're happy to help if you need some assistance.

…ategorical

@emilykl Thanks again for your diligence and help getting this across the finish line, especially the commits you've been pushing!

I believe I have addressed all the open comments that you have not already addressed.

Looking forward to next steps!

(cc @camdecoster)

Thanks @degzhaus, the updates look good! Doing a final review pass now, I might push a few additional commits if needed.

…arrowhead drawing logic

…ta.v key name collision

…le it (determines whether arrow angle is affected by data scales of axes)

Looks good to me!

…tly.js into degzhaus-add-quiver

I’m excited - are we close to merging, and is it looking like we’re going to make it into v4?

I’m excited - are we close to merging, and is it looking like we’re going to make it into v4?

@degzhaus Yes! There are a still a few outstanding issues I'm aware of, which I've noted in the PR description, but we're planning to release a v4.0 release candidate imminently, so we'd like to go ahead and merge this PR and address remaining issues in a follow-up PR. That means we're on track for quiver to make it into 4.0.

@degzhaus Congratulations, we've merged this PR into the v4.0 branch! 🥳 🎉

We'll be putting out a release candidate for v4.0 very shortly.

That doesn't mean no more changes can be made: the quiver API can be modified up until the v4.0 full release, and bug fixes can happen anytime. If you find anything that should be changed, go ahead and open up an issue, and a PR into v4.0 if you like. We'll continue working through any issues we identify as well.

Thanks again for all your work on this trace type, it's been a lot of fun collaborating and we're excited to get quiver out to the public in the near future.

@degzhaus Congratulations, we've merged this PR into the v4.0 branch! 🥳 🎉

We'll be putting out a release candidate for v4.0 very shortly.

That doesn't mean no more changes can be made: the quiver API can be modified up until the v4.0 full release, and bug fixes can happen anytime. If you find anything that should be changed, go ahead and open up an issue, and a PR into v4.0 if you like. We'll continue working through any issues we identify as well.

Thanks again for all your work on this trace type, it's been a lot of fun collaborating and we're excited to get quiver out to the public in the near future.

Eeeeek, so exciting! Thank you so much, @emilykl for all your mentorship along the way, I learned so much on this project. And thank you @camdecoster for your help and direction as well. Really great working with you both!

And thank you so much for your patience and enthusiasm @gpdf! Hope this is useful to you and your team.

All the best,

John

@degzhaus @emilykl @camdecoster @gpdf

Congrats on getting this merged - This is so exciting!

There is a Plotly community forum post about this feature if you would like to chime in over there 🙂
https://community.plotly.com/t/quiver-plots-preview-new/97450/

degzhaus changed the title Degzhaus/add quiver Add quiver trace type for vector field visualization Feb 16, 2026

degzhaus mentioned this pull request Feb 16, 2026

Add quiver trace type for vector field visualization #7584

Closed

camdecoster assigned degzhaus Feb 20, 2026

degzhaus force-pushed the degzhaus/add_quiver branch 3 times, most recently from 1262c1e to f327f5d Compare March 9, 2026 19:22

degzhaus force-pushed the degzhaus/add_quiver branch 3 times, most recently from acfd7f0 to 1a15aa3 Compare April 6, 2026 21:24

camdecoster reviewed Apr 30, 2026

View reviewed changes

camdecoster added this to the v4.0.0 milestone Jun 8, 2026

emilykl mentioned this pull request Jun 11, 2026

Consolidate and add deprecation notice to figure factory plotly/plotly.py#5622

Open

degzhaus added 6 commits June 23, 2026 17:37

Add scatterquiver trace type

7c74abe

Ensure no-gl-jasmine tests pass

100bd88

Name plot type quiver not scatterquiver

3f24d4a

Model quiver api closer to 3d cone trace

ec6a266

Match arrowhead attributes for annotations

68a7608

Derive scaling from axes

1d8d74e

degzhaus added 2 commits July 5, 2026 12:33

Fold zero-length vector coverage into quiver_simple mock

aad037a

Remove redundant quiver_simple mock, fold text coverage into quiver_c…

ad4e647

…ategorical

emilykl added 12 commits July 6, 2026 14:41

fix merge conflict in src/types/generated/schema.d.ts

8645092

update plot-schema

2ce0bed

update image baselines for quiver

f802db0

update jasmine test

6f6aeb5

set default marker.line.width to 2 for visibility; small refactor of …

1c0908c

…arrowhead drawing logic

set both vector components to 0 if either is invalid; also fix calcda…

06aa85c

…ta.v key name collision

update plot-schema and generated types

a800f01

add new attribute 'anglemode' and refactor arrow-drawing code to hand…

9cf22f1

…le it (determines whether arrow angle is affected by data scales of axes)

update mocks after anglemode refactor

0b83d62

update plot-schema and generated types

05c0bc6

update image baselines

80ccb77

update jasmine tests

3d1b217

emilykl reviewed Jul 20, 2026

View reviewed changes

Comment thread draftlogs/7710_add.md Outdated

add attribution to draftlog

d2ba006

camdecoster approved these changes Jul 20, 2026

View reviewed changes

Comment thread draftlogs/7710_add.md Outdated

update a few mocks

a556e16

emilykl force-pushed the degzhaus/add_quiver branch from 0d490dc to 731112d Compare July 20, 2026 22:36

Merge branch 'degzhaus/add_quiver' of https://github.com/degzhaus/plo…

d8d8697

…tly.js into degzhaus-add-quiver

emilykl force-pushed the degzhaus/add_quiver branch from 731112d to d8d8697 Compare July 20, 2026 23:09

update image baselines

36b0e92

emilykl merged commit aa868bb into plotly:v4.0 Jul 21, 2026
244 of 246 checks passed

+                  },
+                  anchor: {
+                      valType: 'enumerated',
+                      values: ['tip', 'tail', 'cm', 'center', 'middle'],

+                  var trace = cd[0].trace;
+                  var marker = trace.marker || {};
+                  var markerLine = marker.line || {};
+                  var lineColor = Lib.isArrayOrTypedArray(marker.color) ? undefined : marker.color;

	extendFlat(attrs, baseAttrs);
	attrs = extendFlat({}, baseAttrs, attrs);

+                  // Colorscale cmin/cmax computation: prefer provided marker.color, else magnitude
+                  if(trace._hasColorscale) {
+                      var vals = hasMarkerColorArray ? [cMin, cMax] : [normMin, normMax];

		var Lib = require('../../../src/lib');
		var d3Select = require('../../strict-d3').select;

Add quiver trace type for vector field visualization by degzhaus · Pull Request #7710 · plotly/plotly.js · GitHub

Uh oh!

Uh oh!

Add quiver trace type for vector field visualization - #7710

Add quiver trace type for vector field visualization#7710emilykl merged 77 commits intoplotly:v4.0plotly/plotly.js:v4.0from degzhaus:degzhaus/add_quiverdegzhaus/plotly.js:degzhaus/add_quiverCopy head branch name to clipboard

Conversation

degzhaus commented Feb 16, 2026 • edited by emilykl Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Features

API

Screenshots

Quiver Plot, vector field with mesh grid (colored by magnitude)

Quiver plot, vector field with mesh grid (colored by independent color array)

Testing

Files Changed

New files (src/traces/quiver/)

Modified

Tests

Known issues

Remaining TODOs (in addition to the above)

Uh oh!

degzhaus commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

degzhaus commented Mar 9, 2026

Uh oh!

degzhaus commented Mar 9, 2026

Uh oh!

emilykl commented Mar 10, 2026

Uh oh!

degzhaus commented Apr 6, 2026

Uh oh!

camdecoster commented Apr 22, 2026

Uh oh!

emilykl commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

camdecoster commented Jun 8, 2026

Uh oh!

degzhaus commented Jun 8, 2026

Uh oh!

camdecoster commented Jun 8, 2026

Uh oh!

camdecoster commented Jun 23, 2026

Uh oh!

degzhaus commented Jul 5, 2026

Uh oh!

emilykl commented Jul 6, 2026

Uh oh!

Uh oh!

camdecoster left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gpdf commented Jul 20, 2026

Uh oh!

emilykl commented Jul 20, 2026

Uh oh!

Uh oh!

Add quiver trace type for vector field visualization#7710
emilykl merged 77 commits into
plotly:v4.0from
degzhaus:degzhaus/add_quiver

degzhaus commented Feb 16, 2026 •
edited by emilykl
Loading

degzhaus commented Mar 9, 2026 •
edited
Loading

emilykl commented Apr 28, 2026 •
edited
Loading