Use case diagrams (<MERMAID_RELEASE_VERSION>+)

Use case diagrams show how actors interact with a system and its use cases. Start a diagram with the usecase-beta keyword. Put each statement on its own physical line.

In UML prose, use case is two words. Mermaid's exact syntax keyword is the single token usecase-beta; this page uses the two-word form everywhere else.

Code:

Ctrl + Enter|

Use direction with TD, TB, BT, LR, or RL to choose the layout direction.

Default theme, look and layout (v<MERMAID_RELEASE_VERSION>+)

Use case diagrams use the redux-color theme and the neo look by default, and are laid out by ELK rather than Dagre. Not every diagram type does — see Per-diagram defaults for the list and for the order in which Mermaid decides.

The same diagram, drawn both ways:

With the defaults

Code:

Ctrl + Enter|

The previous appearance

Both are only defaults, so anything you set yourself wins. Naming the previous theme and look in a diagram's front matter draws it the way Mermaid did before:

Code:

Ctrl + Enter|

Passing the same three keys to mermaid.initialize() does it for every diagram on the page, and scoping the theme and look to one diagram type — mermaid.initialize({ layout: 'dagre', usecase: { theme: 'default', look: 'classic' } }) — does it for that type alone. layout is a top-level option, so it applies to every diagram.

Actors and use cases

Actor and use case identifiers match [A-Za-z0-9_]+, so they may start with a digit — 1, 1mg, and 3rd are all valid. Identifiers are diagram-wide and are shared by actors, use cases, boundaries, JSON nodes, and explicit edges.

A bare actor uses its identifier as its label. An actor can also have an explicit identifier and display label. Use cases use parentheses for an ellipse and square brackets for a rectangle.

Code:

Ctrl + Enter|

Login("Sign in") has the stable identifier Login and the display label Sign in. A quoted declaration such as "Reset password" gets a deterministic identifier by replacing each non-word character with _. Use an explicit identifier when other statements need a readable, stable reference.

A relationship endpoint can appear before its declaration. Final declaration order does not affect the resolved kind, shape, or label. An endpoint that has no explicit declaration becomes an ellipse use case. Actors are never inferred from their position in a relationship and require an actor declaration somewhere in the diagram.

Actor variants

Actors support four variants. The normal stick actor is the default. Set type to hollow or awesome for the other built-in variants. Set icon to an icon name for an icon actor.

Code:

Ctrl + Enter|

Icon actors use Mermaid's icon registry. Register the required icon pack before using an icon name from that pack. If an icon is not available, Mermaid renders the standard unknown-icon fallback instead of failing the diagram.

Actor metadata accepts only type, icon, and business. An icon cannot be combined with a non-normal type or with business: true.

Business elements and stereotypes

Set business: true to add the conventional business slash to a normal or hollow actor or to an ellipse use case. Rectangular use cases, awesome actors, and icon actors cannot be business elements.

An actor or use case can have one visible stereotype. Put <<...>> after metadata and before a ::: class suffix. The stereotype keeps its case and appears above the main label.

Code:

Ctrl + Enter|

Stereotypes provide visible semantics but do not create CSS classes or automatic stereotype selectors. Use classes or direct styles to control their appearance.

Labels

Labels can be unquoted text inside parentheses or brackets, a single-line plain string, or a Mermaid Markdown string. The same forms apply to actor labels, use case labels, boundary titles, relationship labels, and notes.

An unquoted label is taken literally from the source, so it can hold digits, Markdown markers, punctuation, and non-ASCII characters. It has to stay on one physical line, and leading and trailing spaces are dropped. Only what the syntax already reserves stays out: the delimiters (, ), [, ], {, and }, the quote characters " and ', and the sequences --, -->, <--, --o, --x, --|>, ..>, :::, @{, and <<. A lone -, ., :, @, <, or > is ordinary text. Quote the label when a reserved character has to appear in it.

Code:

Ctrl + Enter|

Plain strings remain plain text. Markdown markers in a plain string are displayed literally. Mermaid Markdown strings use an outer pair of double quotes and an inner pair of backticks. Markdown strings can contain physical newlines.

Code:

Ctrl + Enter|

Use Mermaid entity codes when a reserved character must appear in a label. Common codes include #quot;, #39;, #40;, #41;, #91;, #93;, and #96;. Plain strings do not process backslash escapes. For example, "First\nSecond" displays the backslash and n; use a physical newline inside a Markdown string for multiline content.

Lines and comments

Each statement occupies one physical line unless it contains a Markdown string, multiline metadata block, JSON object, accessibility description block, or system boundary block. The final statement does not need a trailing newline.

After optional indentation, %% starts a whole-line comment. Blank lines and comments retain their source order in the public AST.

Code:

Ctrl + Enter|

%% inside a string is label data. // and # are not comments. A semicolon is not a statement separator. Any token after a complete statement on the same physical line is an error.

System boundaries

A systemBoundary block groups actor and use case declarations. Give the boundary a short identifier followed by an optional display title, then optional metadata and classes. The suffixes are ordered systemBoundary <id><title>@{ … }:::<classes>, the same order actors and use cases use.

Code:

Ctrl + Enter|

Titles accept the same label forms as use cases — unquoted text, a plain string, or a Markdown string — inside either […] or (…). Unlike a use case, the bracket form does not select a shape: boundary geometry comes from the type metadata only.

A boundary declared with a quoted title and no identifier gets a deterministic one instead. Below, the title Payment service produces the identifier Payment_service, which the separate metadata statement then targets.

Code:

Ctrl + Enter|

The default boundary type is rect. Set type: package, inline or in a later metadata statement, to render a package title tab. A later statement overrides inline metadata for the same key. Boundary IDs are diagram-wide, while their titles are display labels.

Boundaries are one level deep. Their contents can contain only actor and use case declarations, blank lines, and %% comments. Relationships, notes, JSON nodes, direction statements, class and style statements, boundary metadata, and nested boundaries remain at the top level. An actor or use case can belong to at most one boundary. Contained elements can be referenced by top-level relationships, notes, classes, and styles.

Relationships

Associations

Seven solid association operators are supported. The marker direction and type are preserved.

Code:

Ctrl + Enter|

Solid associations can have a label. A label containing include or extend is still an ordinary association.

Code:

Ctrl + Enter|

JSON nodes can use only point, reversed-point, or markerless solid associations. Circle, cross, include, extend, and generalization relationships cannot connect to JSON nodes.

Include, extend, and generalization

Use explicit operators for UML relationship semantics.

Code:

Ctrl + Enter|

For include, the source use case includes the target use case. For extend, the source use case extends the target base use case. Generalization points from the specialized actor or use case to the general actor or use case. Include and extend require use case endpoints. Generalization requires two actors or two use cases.

Edge IDs, styles, animation, and length

Place an explicit edge ID followed by @ immediately before an operator. Explicit edge IDs share the diagram-wide ID namespace and can be targeted by class, style, and metadata statements.

Code:

Ctrl + Enter|

Anonymous edges receive internal IDs but cannot be styled or configured by ID. Use animate: true for the default speed, animation: fast or animation: slow to select a speed and enable animation, and animate: false to disable it.

Extra dashes request greater minimum layout length on point, reversed-point, and markerless solid associations. The two-dash form has minlen = 1; three dashes give minlen = 2, and each additional dash adds one. For example, A --> B, A ---> B, and A ----> B request progressively longer edges. In a labelled association, put the extra dashes on the right side of the label, as in A -- "longer" ----> B. Circle, cross, include, extend, and generalization operators have fixed length and reject extra dashes.

Notes

A note attaches to one actor or use case. The target can be declared after the note. A note uses the shared note shape, a plain rectangle in the theme note colors, and is connected to its target by a dotted, markerless line.

A note is an ordinary node in the graph. The layout algorithm places it together with the actors and use cases, so a note has no fixed side relative to its target: its position follows the diagram direction and the rest of the layout, and adding a note can move the other elements.

Code:

Ctrl + Enter|

Notes cannot target JSON nodes, boundaries, edges, or other notes. Notes do not have placement keywords, aliases, direct links, standalone forms, or multiple attachments.

JSON tables

A top-level JSON declaration creates a table whose title is its identifier. Its body must be a strict JSON object.

Code:

Ctrl + Enter|

Object properties appear in source order, including integer-like keys. Arrays keep index order. Nested leaves use paths such as address.city and items[0].name. Empty objects and arrays get one row. If a JSON object repeats a property, the last value wins while the property's first source position is retained. Strings render without JSON quote marks; numbers, booleans, and null use JSON spelling.

JSON declarations must stay at the top level. Arrays and scalar values are not valid roots. JSON strings and table cells use the shared text sanitization path.

Styling

Actors, use cases, boundaries, JSON nodes, and explicit edges support Mermaid classes and direct styles. Use classDef to define one or more classes, class to assign them, style for direct declarations, or ::: on an actor, use case, boundary, or JSON declaration.

Code:

Ctrl + Enter|

CSS declarations are comma-separated property:value items. Use \, for a literal comma in a value. Semicolons are rejected. Style precedence is theme variables, the default class, named classes in assignment order, then direct style declarations. Later declarations win per property within the same layer.

Backgrounds come from the active theme, so a hardcoded fill is tied to the theme you wrote it for. A fill on a boundary paints its body and, on a package boundary, its title tab, while the title text keeps the theme's title color. A light fill therefore hides the title in a dark theme, exactly as it does on a flowchart subgraph. Pair the fill with a color declaration when you set one, as in classDef system fill:#f8f8ff,color:#333.

Actor metadata is typed and is not a style map. fillColor, strokeColor, strokeWidth, and arbitrary actor metadata keys are errors. Use classDef, class, or style instead.

Colors

Colour is keyed to the kind of element, not to the order elements are declared. Actors take one colour, use cases another, and system boundaries a third, so the colour of an element says what it is and does not change when you edit the diagram around it. Adding a use case in the middle of a document leaves every other element exactly as it was, which keeps diffs, documentation screenshots, and visual baselines stable.

Each role reads a pair of theme variables. A theme that sets none of them renders as it always did, and you can override any of them through themeVariables.

Theme variable	Applies to
usecaseActorBkg	Actor glyph fill
usecaseActorBorder	Actor glyph stroke
usecaseBkg	Use case body fill
usecaseBorder	Use case body stroke
usecaseBoundaryBkg	System boundary fill, when not numbered
usecaseBoundaryBorder	System boundary stroke, when not numbered
usecaseIncludeLine	include relationship stroke
usecaseExtendLine	extend relationship stroke

include and extend are both dashed, which is hard to tell apart at small sizes, so the colour themes give them separate hues as well.

System boundaries are the exception to the rule above: they are numbered rather than given one shared colour. The first boundary in the document takes the first colour of the theme's palette, the second takes the second, and so on, exactly as flowchart subgraphs are numbered. For a container the number means something — it says which group an element belongs to — and it stays put as long as the order of the boundaries does, so adding an actor or a use case anywhere leaves it alone. usecaseBoundaryBkg and usecaseBoundaryBorder are the fallback for themes that carry no palette to number with.

Code:

Ctrl + Enter|

Per-element colour rotation

Set colorScheme: rotate to extend the numbering from the boundaries to the actors and use cases as well, so every element takes its own slot from the theme's categorical palette, the way entity relationship and class diagrams are coloured. Actors and use cases share one cycle, with the actors numbered first and the use cases after them, each in declaration order. An actor A, usecase U, actor B written in that order is therefore numbered A, B, U rather than A, U, B. This buys per-element variety at the cost of the stability described above: inserting an element shifts the colour of every later element of its own kind, and inserting an actor shifts the use cases too. Boundaries keep their own numbering either way. Only the colour themes (redux-color and redux-dark-color) carry a palette, so on any other theme the two settings render identically.

Code:

Ctrl + Enter|

classDef and style override both schemes, so per-element semantic colour stays available whichever one is active. See Styling.

Configuration

Use case diagrams accept these diagram configuration keys:

Key	Default	Purpose
actorFontSize	14	Actor label font size
actorFontFamily	"Open Sans", sans-serif	Actor label font family
actorFontWeight	normal	Actor label font weight
usecaseFontSize	12	Use case label font size
usecaseFontFamily	"Open Sans", sans-serif	Use case label font family
usecaseFontWeight	normal	Use case label font weight
nodeSpacing	50	Spacing between nodes on the same level
rankSpacing	50	Spacing between layout ranks
diagramPadding	20	Padding around the diagram
colorScheme	role	How the diagram takes colour from the theme
useMaxWidth	true	Whether the SVG scales to the available width

Code:

Ctrl + Enter|

Classes and direct styles override theme and diagram font configuration for the properties they set. See Mermaid configuration for global initialization and frontmatter configuration.

Accessibility

Use accTitle and accDescr to give the diagram an accessible title and description. accDescr accepts a single-line value after : or a multiline block.

Code:

Ctrl + Enter|

Rendered actors, use cases, boundaries, notes, JSON tables, and relationships include semantic accessible names. Actor variants, business roles, stereotypes, and relationship types are included in those names. See Accessibility for the diagram title and description syntax.

Complete example

Features can be combined in one diagram. This example uses accessibility metadata, actor variants, a package boundary, stereotypes, classes, a JSON table, a note, a labelled long association, an include relationship, an animated edge, and a directly styled edge.

Code:

Ctrl + Enter|

Migrating from PlantUML

A PlantUML use case diagram needs these changes before it renders as Mermaid:

• Put one statement on each physical line. A second statement on the same line is a parse error.
• Undeclared relationship endpoints become ellipse use cases. Declare every actor with actor ID somewhere in the document because source position does not imply an actor.
• An association label containing include or extend remains an association. Use ..> : include or ..> : extend for UML include and extend semantics.
• Replace actor fillColor, strokeColor, strokeWidth, and other arbitrary metadata with classDef, class, or style.
• Replace these constructs, which are outside the grammar and raise a parse error: separators and titled separators, as aliases, colon actors, standalone package and rectangle blocks, skinparam, <style> blocks, allowmixing, left, right, up, or down link hints, note placement keywords, standalone notes, multi-target notes, and newpage. Style the diagram with classDef, class, style, and ::: instead, as described under Styling.
• Rewrite backslash escapes and plain \n multiline text. They parse, so no error points at them. See Constructs that parse but mean something else.

Constructs that parse but mean something else

Unsupported syntax raises a parse error, with two exceptions. These parse without an error and render differently from PlantUML:

• A("Line1\nLine2") keeps the backslash and the n as literal text on a single line. Use a Markdown string containing a physical newline for a real line break.
• A("Paren \( x") keeps the backslash as literal text, because a backslash never escapes the character after it. Write the character directly inside a quoted or Markdown string, or use an entity code such as #40; and #41;.

Code:

Ctrl + Enter|