legend — Show and configure plot legends in MATLAB and RunMat.
legend creates or updates the legend for the current axes (or an explicit axes handle). Returned handle behavior, display-name sourcing, and style controls follow MATLAB semantics.
Syntax
h = legend()
h = legend(ax)
h = legend(mode)
h = legend(ax, mode)
h = legend(labels..., Name, Value, ...)
h = legend(ax, labels..., Name, Value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
ax | AxesHandle | Yes | — | Target axes handle. |
mode | StringScalar | Yes | — | Legend mode token: 'on'|'off'|'show'|'hide'|'boxon'|'boxoff'. |
labels_or_pairs | Any | Variadic | — | Labels (string/cell/string-array) with optional trailing Name/Value legend style pairs. |
Returns
| Name | Type | Description |
|---|---|---|
h | NumericScalar | Legend object handle. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:legend:InvalidArgument | Legend arguments are malformed, unsupported, or have invalid labels/properties. | legend: invalid argument |
RunMat:legend:InvalidAxes | Resolved axes target is invalid or out of range. | legend: invalid axes target |
RunMat:legend:Internal | Internal legend state operation fails. | legend: internal operation failed |
How legend works
- Calling
legendwith 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
legendworkflows. - 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
getandsetto inspect or update location, orientation, box visibility, font styling, and related legend properties.
Examples
Build a legend from display names
x = linspace(0, 2*pi, 200);
h1 = plot(x, sin(x));
set(h1, 'DisplayName', 'sin(x)');
hold on;
h2 = plot(x, cos(x));
set(h2, 'DisplayName', 'cos(x)');
legend;Pass labels explicitly and position the legend
plot(1:5, [1 2 3 4 5]);
hold on;
plot(1:5, [5 4 3 2 1]);
lg = legend('rising', 'falling', 'Location', 'southwest');
get(lg, 'Type')Expected output:
ans =
'legend'Keep legends subplot-local
subplot(1, 2, 1);
plot(1:5, 1:5);
legend('left');
subplot(1, 2, 2);
plot(1:5, [5 4 3 2 1]);Expected output:
% Only the left subplot shows a legendUsing legend with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how legend changes the result.
Run a small legend example, explain the result, then change one input and compare the output.
FAQ
How do I move the legend to a specific corner?⌄
Pass the 'Location' property when creating the legend, or update it afterward with set. Standard MATLAB location strings work: 'northeast', 'southwest', 'northwest', 'southeast', etc.
lg = legend('a', 'b');
set(lg, 'Location', 'northwest');Can I show only some series in the legend?⌄
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.
Do I need to call legend again after adding more series with hold on?⌄
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.
Related Plotting functions
More plotting resources
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how legend is executed, line by line, in Rust.
- View the source for legend in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.