{
"title": "legend",
"category": "plotting",
"keywords": [
"legend",
"chart legend",
"display names",
"matlab legend",
"series labels"
],
"summary": "Show and configure plot legends for labeled series, display names, and MATLAB `legend` workflows.",
"requires_feature": null,
"tested": {
"unit": "builtins::plotting::legend::tests"
},
"description": "`legend` creates or updates the legend attached to the current axes, or to an explicit axes handle when one is passed. In RunMat, legends are subplot-local and participate in the plotting object system: the builtin returns a legend handle, display names from plotted objects are used automatically, and legend styling can be inspected or updated through `get` and `set`.",
"behaviors": [
"Calling `legend` with no label arguments uses plotted object display names when they are available.",
"Labels can be passed as separate strings, string arrays, or cell arrays, following common MATLAB `legend` workflows.",
"Legend visibility and style are axes-local, so enabling or hiding a legend in one subplot does not mutate every axes in the figure.",
"The returned handle can be used with `get` and `set` to inspect or update location, orientation, box visibility, font styling, and related legend properties."
],
"examples": [
{
"description": "Build a legend from display names",
"input": "x = linspace(0, 2*pi, 200);\nh1 = plot(x, sin(x));\nset(h1, 'DisplayName', 'sin(x)');\nhold on;\nh2 = plot(x, cos(x));\nset(h2, 'DisplayName', 'cos(x)');\nlegend;"
},
{
"description": "Pass labels explicitly and position the legend",
"input": "plot(1:5, [1 2 3 4 5]);\nhold on;\nplot(1:5, [5 4 3 2 1]);\nlg = legend('rising', 'falling', 'Location', 'southwest');\nget(lg, 'Type')",
"output": "ans =\n 'legend'"
},
{
"description": "Keep legends subplot-local",
"input": "subplot(1, 2, 1);\nplot(1:5, 1:5);\nlegend('left');\nsubplot(1, 2, 2);\nplot(1:5, [5 4 3 2 1]);",
"output": "% Only the left subplot shows a legend"
}
],
"faqs": [
{
"question": "How do I move the legend to a specific corner?",
"answer": "Pass the `'Location'` property when creating the legend, or update it afterward with `set`. Standard MATLAB location strings work: `'northeast'`, `'southwest'`, `'northwest'`, `'southeast'`, etc.\n\n```matlab\nlg = legend('a', 'b');\nset(lg, 'Location', 'northwest');\n```"
},
{
"question": "Can I show only some series in the legend?",
"answer": "Set `'DisplayName'` only on the series you want labeled, then call `legend` with no arguments. Series without a display name are excluded. Alternatively, pass explicit label strings to `legend` — only the first N plotted objects get entries."
},
{
"question": "Do I need to call legend again after adding more series with hold on?",
"answer": "Yes. The legend snapshot is taken when `legend` is called, so new series added after the initial `legend` call won't appear until you call `legend` again. Set display names on all series first, then call `legend` once at the end."
}
],
"links": [
{
"label": "subplot",
"url": "./subplot"
},
{
"label": "get",
"url": "./get"
},
{
"label": "set",
"url": "./set"
},
{
"label": "plot",
"url": "./plot"
},
{
"label": "Choosing the right plot type",
"url": "/docs/plotting/choosing-the-right-plot-type"
},
{
"label": "Styling plots and axes",
"url": "/docs/plotting/styling-plots-and-axes"
},
{
"label": "Plot replay and export",
"url": "/docs/plotting/plot-replay-and-export"
},
{
"label": "Complete plotting guide",
"url": "/blog/matlab-plotting-guide"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/plotting/ops/legend.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/legend.rs"
}
}