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

degzhaus · 2026-02-16T20:09:29Z

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), absolute, or raw vector lengths via sizemode/sizeref
Arrow anchoring: Position arrows by tail, tip, or center/cm/middle
Colorscale support: Color arrows by magnitude or custom scalar field (c array)
Styling: Configurable line color, width, dash patterns via line.* attributes
Arrowhead sizing: Adjustable arrowhead size via arrowsize
Full interactivity: Hover support with customizable hovertemplate, 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' | 'absolute' | 'raw'
  sizeref: 0.5,
  anchor: 'tail',  // 'tail' | 'tip' | 'center'
  colorscale: 'Viridis',
  line: { width: 2 }
}]);

Screenshots

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

Gist with example code

Basic Quiver Plot

With Colorscale

Testing

✅ Jasmine unit tests
✅ 9 visual regression test mocks

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 - 9 mock files
test/image/baselines/quiver_*.png - Baseline images

degzhaus · 2026-03-09T19:35:20Z

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

degzhaus · 2026-03-09T19:39:22Z

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

degzhaus · 2026-03-09T19:40:42Z

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 🤞

emilykl · 2026-03-10T15:32:50Z

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.

degzhaus · 2026-04-06T21:29:53Z

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

i just rebased and pushed again 🥳

camdecoster · 2026-04-22T23:03:59Z

@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.

emilykl · 2026-04-28T20:16:51Z

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.

camdecoster · 2026-04-28T20:02:55Z

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


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

camdecoster · 2026-04-28T20:14:20Z

+};
+
+// Extend with base attributes (includes hoverinfo, etc.)
+extendFlat(attrs, baseAttrs);


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

camdecoster · 2026-04-30T20:33:41Z

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


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!

camdecoster · 2026-04-30T20:42:08Z

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


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

camdecoster · 2026-04-30T20:45:50Z

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


Could you delete these unused imports?

Absolutely, removed here:

eba15eb

camdecoster · 2026-06-08T19:46:08Z

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

degzhaus · 2026-06-08T20:29:48Z

@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 🤞

camdecoster · 2026-06-08T20:31:10Z

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

camdecoster · 2026-06-23T18:13:29Z

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.

degzhaus · 2026-06-24T02:17:49Z

test/jasmine/tests/quiver_test.js

Thank you so much for validating and calling these out, @emilykl !

Fix for Adjust axis ranges automatically to include full length of arrows:
a2799e2

Fix for Colorscale:
3344864

degzhaus · 2026-06-24T02:23:53Z

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.

Amazing, that is so exciting! Thanks so much for y'all's direction, @emilykl and @camdecoster, I learned a lot working with each of you.

I responded inline with what I think are the remaining outstanding points. Very excited for final steps.

Thanks so much for reaching out to be sure this is included in the release, that means a lot.

Feel free to ping with any remaining tasks, I will keep my eyes peeled for updates.

All the best.

camdecoster · 2026-06-24T22:09:41Z

I believe that you've addressed all of my comments. I'll let @emilykl take a look and give the final review. I'm going to edit this PR to target our 4.0 branch instead of master. Then I'll merge the 4.0 changes into your branch and cross my fingers that it just works. I'll push those changes and then it should good to go for Emily to look at.

camdecoster · 2026-06-24T22:23:19Z

Hey! It worked! It looks like you just need to update the baseline images, address the failing test, and add a draftlog entry (plus whatever Emily comments on). Almost there!

degzhaus · 2026-06-24T23:00:32Z

Hey! It worked! It looks like you just need to update the baseline images, address the failing test, and add a draftlog entry (plus whatever Emily comments on). Almost there!

Great news, and thank you so much for hopping on this today and taking care of those requisite commits, @camdecoster !

I just pushed 3 more commits as well, hopefully CI will be as happy as me 🥳

Is there something I can do to initiate the pipeline or will that happen automatically?

Thanks again for everything, Cam and Emily 🙌

camdecoster · 2026-06-24T23:54:16Z

I approved the workflows. All green.

emilykl · 2026-06-25T21:26:20Z

@degzhaus Exciting news! I'm starting to review, I'll get back to you ASAP with any comments.

emilykl · 2026-06-26T22:00:05Z

@degzhaus I think it would be OK to remove this image test (and the associated PNG) since as far as I can tell it doesn't test any properties which aren't covered by the other mocks.

emilykl · 2026-06-26T22:02:05Z

@degzhaus Instead of testing this in a separate mock, could you edit one of the other mocks to include zero-length vectors and remove this one?

(Each image test adds a bit of CI time, so we want to strike a balance between having comprehensive tests while also keeping the number of image tests down.)

emilykl · 2026-06-26T22:02:50Z

    ['layout-colorway', require('../../image/mocks/layout-colorway.json')],
    ['multicategory', require('../../image/mocks/multicategory.json')],
    ['polar_categories', require('../../image/mocks/polar_categories.json')],
+    ['quiver_simple', require('../../image/mocks/quiver_simple.json')],


I don't think this is needed

Suggested change

['quiver_simple', require('../../image/mocks/quiver_simple.json')],

emilykl · 2026-06-26T22:04:41Z

+            // Depending on prior tests, the suppression warning may already be reached once.
+            expect(Lib.warn.calls.count()).toBeGreaterThanOrEqual(10);
+            expect(Lib.warn.calls.count()).toBeLessThanOrEqual(11);


@camdecoster what do you think about this patch for this flaky test? It loosens the test, but we already re-run until it passes anyway, so maybe it's fine to just loosen the test a bit to maintain our sanity.

I'm okay with it. I ran into that test with the hovertemplate work I did. It's not a great test and should be updated when we switch to a new testing library.

emilykl · 2026-06-26T22:14:42Z

+    hoverdistance: {
+        valType: 'number',
+        min: -1,
+        dflt: 20,
+        editType: 'calc',
+        description: 'Maximum distance (in pixels) to look for nearby arrows on hover.'
+    },


No other trace type has a hoverdistance attribute (it's a layout property) so I'd suggest to remove it unless there's a good reason to define it at the trace level here.

Suggested change

hoverdistance: {

valType: 'number',

min: -1,

dflt: 20,

editType: 'calc',

description: 'Maximum distance (in pixels) to look for nearby arrows on hover.'

},

emilykl · 2026-06-26T22:21:17Z

+    text: {
+        valType: 'data_array',
+        editType: 'calc',
+        anim: true,
+        description: 'Sets text elements associated with each (x,y) pair.'
+    },
+    textposition: {
+        valType: 'enumerated',
+        values: [
+            'top left', 'top center', 'top right',
+            'middle left', 'middle center', 'middle right',
+            'bottom left', 'bottom center', 'bottom right'
+        ],
+        dflt: 'middle center',
+        editType: 'calc',
+        description: 'Sets the positions of the `text` elements with respects to the (x,y) coordinates.'
+    },
+    // Text font
+    textfont: fontAttrs({
+        editType: 'calc',
+        colorEditType: 'style',
+        arrayOk: true,
+        description: 'Sets the text font.'
+    }),


Preference for reusing the scatter attributes here if possible. Can use extendFlat if a few attribute properties need to be changed.

Of course if the whole attribute definition really does need to be different, it's OK to redefine here.

Suggested change

text: {

valType: 'data_array',

editType: 'calc',

anim: true,

description: 'Sets text elements associated with each (x,y) pair.'

},

textposition: {

valType: 'enumerated',

values: [

'top left', 'top center', 'top right',

'middle left', 'middle center', 'middle right',

'bottom left', 'bottom center', 'bottom right'

],

dflt: 'middle center',

editType: 'calc',

description: 'Sets the positions of the `text` elements with respects to the (x,y) coordinates.'

},

// Text font

textfont: fontAttrs({

editType: 'calc',

colorEditType: 'style',

arrayOk: true,

description: 'Sets the text font.'

}),

text: scatterAttrs.text,

textposition: scatterAttrs.textposition,

textfont: scatterAttrs.textfont,

emilykl · 2026-06-26T22:29:03Z

+attrs.hoverinfo = extendFlat({}, baseAttrs.hoverinfo, {
+    flags: ['x', 'y', 'u', 'v', 'text', 'name'],
+    dflt: 'all'
+});
+
+// Add hovertemplate
+attrs.hovertemplate = extendFlat({}, hovertemplateAttrs({}, {
+    keys: ['x', 'y', 'u', 'v', 'text', 'name']
+}));


@degzhaus Is there a reason why these are added afterwards, rather than defined in the main body of attrs?

emilykl · 2026-06-26T22:35:49Z

    var y;

-    var hasOnlyLines = (!subtypes.hasMarkers(trace) && !subtypes.hasText(trace));
+    var hasOnlyLines = trace.mode && !subtypes.hasMarkers(trace) && !subtypes.hasText(trace);


IMO it would be clearer to modify the subtypes.hasMarkers(trace) logic such that it returns true for quiver traces, rather than adding a trace.mode escape hatch here.

emilykl · 2026-06-26T22:36:39Z

FYI @degzhaus I've left some comments but haven't quite finished my review yet, I'll continue on Monday!

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 6 commits June 23, 2026 18:45

Honor colorscale

3344864

Use center, Remove redundant anchor value options

94dc00d

Idiomatic extendFlat usage

2e214c7

Fallback to arrow color with opacity

f3789e6

Guard against infinite values

dd71b94

Remove unused imports

eba15eb

Merge remote-tracking branch 'origin/v4.0' into degzhaus/add_quiver

5d3e198

camdecoster changed the base branch from master to v4.0 June 24, 2026 22:09

Update schema and types

813ab71

degzhaus added 3 commits June 24, 2026 15:48

Regenerate image baselines

0a76daf

Add quiver mock to svgMockList

c694a02

Add draftlog/7710_add.md for quiver trace type

601ca45

camdecoster added 2 commits June 25, 2026 11:21

Merge remote-tracking branch 'origin/v4.0' into degzhaus/add_quiver

86030c3

Update types

d92fd9b

emilykl reviewed Jun 26, 2026

View reviewed changes

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

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

Uh oh!

Uh oh!

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

Basic Quiver Plot

With Colorscale

Testing

Files Changed

New files (src/traces/quiver/)

Modified

Tests

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 Jun 24, 2026

Uh oh!

degzhaus commented Jun 24, 2026

Uh oh!

camdecoster commented Jun 24, 2026

Uh oh!

camdecoster commented Jun 24, 2026

Uh oh!

degzhaus commented Jun 24, 2026

Uh oh!

camdecoster commented Jun 24, 2026

Uh oh!

emilykl commented Jun 25, 2026

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

degzhaus commented Feb 16, 2026 •

edited by emilykl

Loading

New files (`src/traces/quiver/`)

degzhaus commented Mar 9, 2026 •

edited

Loading

emilykl commented Apr 28, 2026 •

edited

Loading