Nov 26, 2024 · Nov 26, 2024
diff --git a/doc/users/next_whats_new/legend_itemboxalign.rst b/doc/users/next_whats_new/legend_itemboxalign.rst
 Adding itembox alignment option for legends
 ---------------------------------------------------------

 `~.Legend` previously always aligns items using the "baseline" option, which results in
 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()
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
 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
        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"
        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)]
            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"
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()
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 DownExpand 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 DownExpand 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 DownExpand 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