Skip to content

legend

legend

Legend pydantic-model

Bases: HashableBase

Configuration container for Matplotlib legend styling and placement.

The Legend class controls the appearance and position of the plot legend. Placement is governed by a combination of the loc and bbox_to_anchor parameters, mirroring Matplotlib's Axes.legend().

Attributes:

Name Type Description
visible bool

Whether the legend should be displayed. Defaults to True.
title str | None

Title displayed above the legend entries.
framealpha float

Opacity of the legend background. 1 = fully opaque, 0 = fully transparent.
loc LegendLocation

Anchor point for the legend (e.g., upper right, lower left). See LegendLocation enum for options.
ncol int

Number of columns to arrange legend entries into.
fancybox bool

Whether to draw a rounded (True) or square (False) legend frame.
edgecolor str

Color of the legend frame border. Default is "black".
bbox_to_anchor tuple[float, float] | None

Offset position of the legend in figure or axes coordinates. If None, the legend is placed inside the axes using loc.

Good starter values for common placements:

  • Inside (default): 
    bbox_to_anchor=None
  • Outside right: 
    loc=LegendLocation.CENTER_LEFT
bbox_to_anchor=(1.02, 0.5)
  • Outside left: 
    loc=LegendLocation.CENTER_RIGHT
bbox_to_anchor=(-0.02, 0.5)
  • Outside top: 
    loc=LegendLocation.LOWER_CENTER
bbox_to_anchor=(0.5, 1.02)
  • Outside bottom: 
    loc=LegendLocation.UPPER_CENTER
bbox_to_anchor=(0.5, -0.02)
Show JSON schema: 
{
  "$defs": {
    "LegendLocation": {
      "enum": [
        "best",
        "upper right",
        "upper left",
        "lower left",
        "lower right",
        "right",
        "center left",
        "center right",
        "lower center",
        "upper center",
        "center"
      ],
      "title": "LegendLocation",
      "type": "string"
    }
  },
  "description": "Configuration container for Matplotlib legend styling and placement.\n\nThe `Legend` class controls the appearance and position of the plot legend.\nPlacement is governed by a combination of the `loc` and `bbox_to_anchor`\nparameters, mirroring Matplotlib's `Axes.legend()`.\n\nAttributes:\n    visible (bool): Whether the legend should be displayed. Defaults to True.\n    title (str | None): Title displayed above the legend entries.\n    framealpha (float): Opacity of the legend background. 1 = fully opaque, 0 = fully transparent.\n    loc (LegendLocation): Anchor point for the legend (e.g., upper right, lower left). See `LegendLocation` enum for options.\n    ncol (int): Number of columns to arrange legend entries into.\n    fancybox (bool): Whether to draw a rounded (True) or square (False) legend frame.\n    edgecolor (str): Color of the legend frame border. Default is \"black\".\n    bbox_to_anchor (tuple[float, float] | None): Offset position of the legend in figure or axes coordinates. If None, the legend is placed inside the axes using `loc`.\n\n        Good starter values for common placements:\n\n        - **Inside (default)**:\n            ```python\n            bbox_to_anchor=None\n            ```\n        - **Outside right**:\n            ```python\n            loc=LegendLocation.CENTER_LEFT\n            bbox_to_anchor=(1.02, 0.5)\n            ```\n        - **Outside left**:\n            ```python\n            loc=LegendLocation.CENTER_RIGHT\n            bbox_to_anchor=(-0.02, 0.5)\n            ```\n        - **Outside top**:\n            ```python\n            loc=LegendLocation.LOWER_CENTER\n            bbox_to_anchor=(0.5, 1.02)\n            ```\n        - **Outside bottom**:\n            ```python\n            loc=LegendLocation.UPPER_CENTER\n            bbox_to_anchor=(0.5, -0.02)\n            ```",
  "properties": {
    "visible": {
      "default": true,
      "title": "Visible",
      "type": "boolean"
    },
    "title": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Title"
    },
    "framealpha": {
      "default": 1,
      "title": "Framealpha",
      "type": "number"
    },
    "loc": {
      "$ref": "#/$defs/LegendLocation",
      "default": "best"
    },
    "ncol": {
      "default": 1,
      "title": "Ncol",
      "type": "integer"
    },
    "fancybox": {
      "default": true,
      "title": "Fancybox",
      "type": "boolean"
    },
    "edgecolor": {
      "default": "black",
      "title": "Edgecolor",
      "type": "string"
    },
    "bbox_to_anchor": {
      "anyOf": [
        {
          "maxItems": 2,
          "minItems": 2,
          "prefixItems": [
            {
              "type": "number"
            },
            {
              "type": "number"
            }
          ],
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Bbox To Anchor"
    }
  },
  "title": "Legend",
  "type": "object"
}

Fields: