Legend Marker Vertical Alignment

src/components/legend/attributes.js

@@ -120,5 +120,15 @@ module.exports = {
             'or *bottom* of the legend.'
         ].join(' ')
     },
-    editType: 'legend'
+    editType: 'legend',
+    valign: {
+        valType: 'enumerated',
+        values: ['top', 'middle', 'bottom'],
+        dflt: 'middle',
+        role: 'style',
+        editType: 'legend',
+        description: [
+            'Sets the vertical alignment of the symbols with respect to their associated text.',
+        ].join(' ')
+    }
 };

src/components/legend/defaults.js

@@ -103,5 +103,6 @@ module.exports = function legendDefaults(layoutIn, layoutOut, fullData) {
     coerce('xanchor', defaultXAnchor);
     coerce('y', defaultY);
     coerce('yanchor', defaultYAnchor);
+    coerce('valign');
     Lib.noneOrAll(containerIn, containerOut, ['x', 'y']);
 };

src/components/legend/draw.js

@@ -536,6 +536,7 @@ function computeTextDimensions(g, gd) {
         // to avoid getBoundingClientRect
         var textY = lineHeight * (0.3 + (1 - textLines) / 2);
         svgTextUtils.positionText(text, constants.textOffsetX, textY);
+        legendItem.lineHeight = lineHeight;
     }
 
     height = Math.max(height, 16) + 3;

src/components/legend/style.js

@@ -25,6 +25,13 @@ module.exports = function style(s, gd) {
         var layers = Lib.ensureSingle(traceGroup, 'g', 'layers');
         layers.style('opacity', d[0].trace.opacity);
 
+        // Marker vertical alignment
+        var valignFactor = 0;
+        if(gd._fullLayout.legend.valign === 'top') valignFactor = 1.0;
+        if(gd._fullLayout.legend.valign === 'bottom') valignFactor = -1.0;
+        var markerOffsetY = valignFactor * (0.5 * (d[0].lineHeight - d[0].height + 3));
+        if(!isNaN(markerOffsetY)) layers.attr('transform', 'translate(0,' + markerOffsetY + ')');
+
         var fill = layers
             .selectAll('g.legendfill')
                 .data([d]);

test/image/mocks/legend_valign_middle.json

@@ -0,0 +1,25 @@
+{
+  "data": [{
+      "y": [1, 5, 3, 4, 5],
+      "name": "Super long name<br>Super long name<br>Super long name<br>Super long name",
+      "type": "scatter",
+      "showlegend": true
+    },
+    {
+      "y": [3, 2, 5, 1, 5],
+      "name": "Also super long name<br>Also super long name<br>Also super long name",
+      "type": "scatter",
+      "showlegend": true
+    }
+  ],
+  "layout": {
+    "width": 800,
+    "legend": {
+      "bgcolor": "rgba(0,255,255,1)",
+      "valign": "middle",
+      "font": {
+        "size": 20
+      }
+    }
+  }
+}

test/image/mocks/legend_valign_top.json

@@ -0,0 +1,25 @@
+{
+  "data": [{
+      "y": [1, 5, 3, 4, 5],
+      "name": "Super long name<br>Super long name<br>Super long name<br>Super long name",
+      "type": "scatter",
+      "showlegend": true
+    },
+    {
+      "y": [3, 2, 5, 1, 5],
+      "name": "Also super long name<br>Also super long name<br>Also super long name",
+      "type": "scatter",
+      "showlegend": true
+    }
+  ],
+  "layout": {
+    "width": 800,
+    "legend": {
+      "bgcolor": "rgba(0,255,255,1)",
+      "valign": "top",
+      "font": {
+        "size": 20
+      }
+    }
+  }
+}

test/jasmine/tests/legend_test.js

@@ -665,6 +665,43 @@ describe('legend relayout update', function() {
         .catch(failTest)
         .then(done);
     });
+
+    describe('should update legend valign', function() {
+        var mock = require('@mocks/legend_valign_top.json');
+        var gd;
+
+        beforeEach(function() {
+            gd = createGraphDiv();
+        });
+        afterEach(destroyGraphDiv);
+
+        function markerOffsetY() {
+            var translateY = d3.select('.legend .traces .layers').attr('transform').match(/translate\(\d+,(-?\d+)\)/)[1];
+            return parseFloat(translateY);
+        }
+
+        it('it should translate markers', function(done) {
+            var mockCopy = Lib.extendDeep({}, mock);
+
+            var top, middle, bottom;
+            Plotly.plot(gd, mockCopy.data, mockCopy.layout)
+            .then(function() {
+                top = markerOffsetY();
+                return Plotly.relayout(gd, 'legend.valign', 'middle');
+            })
+            .then(function() {
+                middle = markerOffsetY();
+                expect(middle).toBeGreaterThan(top);
+                return Plotly.relayout(gd, 'legend.valign', 'bottom');
+            })
+            .then(function() {
+                bottom = markerOffsetY();
+                expect(bottom).toBeGreaterThan(middle);
+            })
+            .catch(failTest)
+            .then(done);
+        });
+    });
 });
 
 describe('legend orientation change:', function() {