Improve legend loc and bbox_to_anchor documentation (#26620) (#31422)

amanparganiha · timhoffm · web-flow · commit 7820a63f84cd · 2026-03-30T13:44:31.000+02:00
* Improve legend loc and bbox_to_anchor documentation (#26620) * Update lib/matplotlib/legend.py Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> * Update lib/matplotlib/legend.py Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> --------- Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -98,9 +98,11 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
 _legend_kw_doc_base = """
 bbox_to_anchor : `.BboxBase`, 2-tuple, or 4-tuple of floats
     Box that is used to position the legend in conjunction with *loc*.
+    This is an advanced option for free placement of the legend. For
+    most use cases, *loc* alone is sufficient.
+
     Defaults to ``axes.bbox`` (if called as a method to `.Axes.legend`) or
-    ``figure.bbox`` (if ``figure.legend``).  This argument allows arbitrary
-    placement of the legend.
+    ``figure.bbox`` (if ``figure.legend``).
 
     Bbox coordinates are interpreted in the coordinate system given by
     *bbox_transform*, with the default transform
@@ -119,6 +121,9 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
 
         loc='upper right', bbox_to_anchor=(0.5, 0.5)
 
+    For more details on legend positioning, see the
+    :ref:`legend_guide`.
+
 ncols : int, default: 1
     The number of columns that the legend has.
 
@@ -265,15 +270,19 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
 loc : str or pair of floats, default: {default}
     The location of the legend.
 
-    The strings ``'upper left'``, ``'upper right'``, ``'lower left'``,
-    ``'lower right'`` place the legend at the corresponding corner of the
-    {parent}.
+    The string locations place the legend at the corresponding position
+    within the bounding box, which by default is the full {parent} area.
+    The bounding box can be changed via *bbox_to_anchor*.
 
-    The strings ``'upper center'``, ``'lower center'``, ``'center left'``,
-    ``'center right'`` place the legend at the center of the corresponding edge
-    of the {parent}.
+    The positions are visualized below::
 
-    The string ``'center'`` places the legend at the center of the {parent}.
+        +--------------+--------------+---------------+
+        | 'upper left' |'upper center'| 'upper right' |
+        +--------------+--------------+---------------+
+        |'center left' |   'center'   |'center right' |
+        +--------------+--------------+---------------+
+        | 'lower left' |'lower center'| 'lower right' |
+        +--------------+--------------+---------------+
 {best}
     The location can also be a 2-tuple giving the coordinates of the lower-left
     corner of the legend in {parent} coordinates (in which case *bbox_to_anchor*
