Skip to content
MermaidViewer

Software diagram

Mermaid class diagram

Mermaid class diagram syntax for fields, methods, visibility and UML relationships, with examples you can paste into a README.

By MermaidViewer editorsPublished Updated

Basic class diagram example

Basic class diagram example diagram
mermaid
classDiagram
    class Animal {
      <<abstract>>
      +String name
      +int age
      +makeSound()* void
    }
    class Dog {
      +String breed
      +fetch() void
    }
    class Cat {
      -int lives
      +purr() void
    }
    class Owner {
      +String name
      +adopt(Animal a) void
    }
    Animal <|-- Dog
    Animal <|-- Cat
    Owner "1" --> "0..*" Animal : owns
Open in the live editor

Mermaid class diagrams describe the structure of object-oriented systems using UML notation: classes with attributes and methods, and the relationships between them such as inheritance, composition and association.

They are ideal for domain modelling, design reviews and documenting libraries. Because the diagram is text, you can keep it in the same repository as the code it describes and update it in the same pull request.

When to use a class diagram

  • Domain-driven design and modelling sessions
  • Documenting SDKs, libraries and public APIs
  • Planning refactors and explaining design patterns
  • Teaching object-oriented programming

Class Diagram syntax reference

SyntaxWhat it does
classDiagramStart a class diagram.
class Name { +type field \n +method() ret }Declare a class with members.
+ - # ~Visibility: public, private, protected, package/internal.
method()* / field$Abstract method (*) / static member ($).
<<interface>> / <<abstract>>Annotations shown above the class name.
A <|-- BInheritance: B extends A.
A *-- B / A o-- BComposition / aggregation.
A --> B / A ..> BAssociation / dependency.
A ..|> BRealization: A implements interface B.
A "1" --> "*" B : labelCardinality and relationship label.
class Box~T~Generic type parameter.
namespace Core { class A }Group classes into a namespace.

Class Diagram examples

Interface and generics

Repositories implementing a generic interface — a common pattern in backend code.

Interface and generics diagram
mermaid
classDiagram
    class Repository~T~ {
      <<interface>>
      +findById(id) T
      +save(entity T) void
    }
    class UserRepository {
      +findByEmail(email) User
    }
    class User {
      +UUID id
      +String email
    }
    Repository~T~ <|.. UserRepository
    UserRepository ..> User
Open in the live editor

Composition vs aggregation

A house is composed of rooms (they die with it); a team aggregates players.

Composition vs aggregation diagram
mermaid
classDiagram
    House *-- "1..*" Room : has
    Team o-- "11..*" Player : includes
    class Room { +int area }
    class Player { +String name }
Open in the live editor

Types, fields, and the lines between them are the whole job. A mermaid class diagram is how you show that shape in a README without opening a drawing tool. The table above lists the markers. Here the useful part is which marker means which kind of relationship, on a small billing model.

What the four lines mean

A class body is a name plus members. + is public, - is private, # is protected. You can skip the marks when you're sketching a domain and add them when the diagram is about an API. A field reads as a type and a name, +int total. A method keeps parentheses, +send().

Relationships aren't interchangeable. Account <|-- TeamAccount means TeamAccount is a kind of Account. The arrowhead sits on the parent. Reversing the arrow is the most common modeling bug, and the parser won't catch it, because both directions are legal syntax.

Invoice *-- Line is composition. The line item doesn't outlive the invoice. Account o-- Invoice is aggregation. The account groups invoices, and you can still talk about an invoice on its own. "1" --> "*" is a plain association with cardinality. Quote both numbers. An unquoted * is read as the composition token, and the line fails to parse.

Put a verb on the association when the cardinality alone is ambiguous. : settles tells you the invoice is the thing that has many payments. Without the verb, a reader has to invent the direction.

Worked example

A team account is a special account. Accounts group invoices. An invoice is composed of lines, and it settles one or more payments. That's the whole model.

Mermaid diagram
mermaid
classDiagram
    class Account {
      +string name
    }
    class Invoice {
      +int total
      +send()
    }
    class Line {
      +string sku
    }
    class Payment {
      +int amount
    }
    Account <|-- TeamAccount
    Account o-- Invoice
    Invoice *-- Line
    Invoice "1" --> "*" Payment : settles
Open in the live editor

TeamAccount has no body. Mermaid still draws it, which is handy while you're naming subtypes and not ready to list fields. Invoice shows one field and one method so the box stays short. The composition line to Line has no cardinality text because *-- already says the invoice owns the parts. The payment line uses quotes and a verb because "many payments" is the fact a finance reviewer came to check.

Sketch the type names first, then fill only the members you would review. If you need the database keys next, this diagram will start lying by omission. Primary keys and foreign keys belong on an ER diagram. Keep the class diagram on the language types.

When this is the wrong diagram

An ER diagram is the right page when the boxes are tables and the question is crow's foot cardinality. A sequence diagram is the right page when the question is which method runs, in what order, across services. A class diagram answers "what exists and how the types hold each other." It doesn't answer "what happens at checkout."

Common mistakes

  1. Pointing <|-- at the child. Account <|-- TeamAccount puts the triangle on Account, the parent. Swap the names and the subtype looks like the base class.
  2. Writing Invoice "1" --> * Payment without quotes around the star. The parser treats the bare star as composition and rejects the line. Use "1" --> "*".
  3. Stuffing getters, setters, and constructors into every box. The diagram becomes a class listing. Keep the members that change a design review.
  4. Drawing both *-- and "1" --> "*" between the same pair. Pick composition or a numbered association so the pair has one meaning.

Where to go next

The AI class diagram generator will turn a noun list into boxes. Correct the arrowheads in the editor before you trust them, and the cheat sheet has the relationship markers on one line each. The blog class template is a larger domain if you want to see inheritance used on posts and comments.

If you want the workflow of writing the model rather than the marker table, the class diagram creator post is that pass.

Tips and best practices

  • Use generics with tildes (List~String~) because angle brackets are reserved.
  • Show only the members that matter for the discussion; full class listings get noisy fast.
  • Use namespaces to separate bounded contexts in larger models.
  • Add cardinality on associations so the diagram also communicates data constraints.

Generate a class diagram with AI

Not sure where to start? Describe what you need and the AI class diagram generator writes the Mermaid code for you. Try prompts like:

  • “E-commerce domain model with orders, products and customers”
  • “Observer design pattern”
  • “Library management system”

Class Diagram templates

Class Diagram FAQ

How do I show inheritance in a Mermaid class diagram?

Use Parent <|-- Child. The hollow triangle points at the parent class. For interfaces use Interface <|.. Implementation (dotted line).

How do I mark a class as an interface?

Add the annotation <<interface>> inside the class body, or write <<interface>> ClassName on its own line.

Can Mermaid class diagrams show static and abstract members?

Yes. Append $ to make a member static (count$) and * to make a method abstract (draw()*).

Is a Mermaid class diagram valid UML?

It follows UML class diagram notation for visibility, relationships and cardinality, which is enough for most documentation and design work.