Skip to content

add itemboxalign option to legend constructor #29197

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions doc/users/next_whats_new/legend_itemboxalign.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
Adding itembox alignment option for legends
---------------------------------------------------------

`~.Legend` previously always aligns items using the "baseline" option, which results in

Check warning on line 4 in doc/users/next_whats_new/legend_itemboxalign.rst

View workflow job for this annotation

GitHub Actions / sphinx

[sphinx] doc/users/next_whats_new/legend_itemboxalign.rst#L4

py:obj reference target not found: itemboxalign [ref.obj]
Raw output
doc/users/next_whats_new/legend_itemboxalign.rst:4: WARNING: py:obj reference target not found: itemboxalign [ref.obj]
the appearance of vertical centering of the artist and label for multi-line labels.
This is sometimes hard to read. The introduction of the `itemboxalign` parameter allows
the user to change this behavior and choose a different desired vertical alignment.

.. plot::
:include-source: true
:alt: A legend with artist and label aligned to 'top' rather than 'baseline'

import matplotlib.pyplot as plt

fig, ax = plt.subplots(1, 2)

ax[0].plot([5, 2, 8], label='long\nlabel')
ax[0].plot([4, 9, 1], label='another\nlong\nlabel')
ax[0].legend(title="align=baseline (default)")

ax[1].plot([5, 2, 8], label='long\nlabel')
ax[1].plot([4, 9, 1], label='another\nlong\nlabel')
ax[1].legend(title="align=top", itemboxalign='top')

plt.show()
10 changes: 9 additions & 1 deletion lib/matplotlib/legend.py
Original file line number Diff line number Diff line change
Expand Up @@ -246,6 +246,11 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
columnspacing : float, default: :rc:`legend.columnspacing`
The spacing between columns, in font-size units.

itemboxalign : str, default: 'baseline'
The vertical alignment for each item box consisting of an artist and a label.

..versionadded:: 3.10

handler_map : dict or None
The custom dictionary mapping instances or types to a legend
handler. This *handler_map* updates the default handler map
Expand Down Expand Up @@ -374,6 +379,7 @@ def __init__(
handletextpad=None, # pad between the legend handle and text
borderaxespad=None, # pad between the Axes and legend border
columnspacing=None, # spacing between columns
itemboxalign="baseline", # vertical alignment of each entry in legend

ncols=1, # number of columns
mode=None, # horizontal distribution of columns: None or "expand"
Expand Down Expand Up @@ -455,6 +461,8 @@ def __init__(
self.columnspacing = mpl._val_or_rc(columnspacing, 'legend.columnspacing')
self.shadow = mpl._val_or_rc(shadow, 'legend.shadow')

self.itemboxalign = itemboxalign

if reverse:
labels = [*reversed(labels)]
handles = [*reversed(handles)]
Expand Down Expand Up @@ -908,7 +916,7 @@ def _init_legend_box(self, handles, labels, markerfirst=True):
itemboxes = [HPacker(pad=0,
sep=self.handletextpad * fontsize,
children=[h, t] if markerfirst else [t, h],
align="baseline")
align=self.itemboxalign)
for h, t in handles_and_labels_column]
# pack columnbox
alignment = "baseline" if markerfirst else "right"
Expand Down
Loading