Skip to content

Commit e55081e

Browse files
committed
Improve legend loc and bbox_to_anchor documentation (matplotlib#26620)
1 parent 6871ecc commit e55081e

1 file changed

Lines changed: 22 additions & 9 deletions

File tree

‎lib/matplotlib/legend.py‎

Lines changed: 22 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -98,9 +98,12 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
9898
_legend_kw_doc_base = """
9999
bbox_to_anchor : `.BboxBase`, 2-tuple, or 4-tuple of floats
100100
Box that is used to position the legend in conjunction with *loc*.
101+
This is an advanced option for free placement of the legend and is
102+
typically used when placing the legend outside of the Axes or at a
103+
custom position. For most use cases, *loc* alone is sufficient.
104+
101105
Defaults to ``axes.bbox`` (if called as a method to `.Axes.legend`) or
102-
``figure.bbox`` (if ``figure.legend``). This argument allows arbitrary
103-
placement of the legend.
106+
``figure.bbox`` (if ``figure.legend``).
104107
105108
Bbox coordinates are interpreted in the coordinate system given by
106109
*bbox_transform*, with the default transform
@@ -119,6 +122,12 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
119122
120123
loc='upper right', bbox_to_anchor=(0.5, 0.5)
121124
125+
For placing the legend outside the Axes, see
126+
`.Figure.legend`, which supports ``'outside right upper'``
127+
and similar location strings.
128+
For more details on legend positioning, see the
129+
:ref:`legend_guide`.
130+
122131
ncols : int, default: 1
123132
The number of columns that the legend has.
124133
@@ -265,15 +274,19 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
265274
loc : str or pair of floats, default: {default}
266275
The location of the legend.
267276
268-
The strings ``'upper left'``, ``'upper right'``, ``'lower left'``,
269-
``'lower right'`` place the legend at the corresponding corner of the
270-
{parent}.
277+
The string locations place the legend at the corresponding position
278+
within the bounding box, which by default is the full {parent} area.
279+
The bounding box can be changed via *bbox_to_anchor*.
271280
272-
The strings ``'upper center'``, ``'lower center'``, ``'center left'``,
273-
``'center right'`` place the legend at the center of the corresponding edge
274-
of the {parent}.
281+
The positions are visualized below::
275282
276-
The string ``'center'`` places the legend at the center of the {parent}.
283+
+--------------+--------------+---------------+
284+
| 'upper left' |'upper center'| 'upper right' |
285+
+--------------+--------------+---------------+
286+
|'center left' | 'center' |'center right' |
287+
+--------------+--------------+---------------+
288+
| 'lower left' |'lower center'| 'lower right' |
289+
+--------------+--------------+---------------+
277290
{best}
278291
The location can also be a 2-tuple giving the coordinates of the lower-left
279292
corner of the legend in {parent} coordinates (in which case *bbox_to_anchor*

0 commit comments

Comments
 (0)