If you've ever tried to explain a codebase to a teammate using only words, you know how fast things get confusing. UML class diagrams solve that problem by showing classes, their properties, methods, and relationships in a single visual. Mermaid.js makes creating these diagrams even easier because you write them as plain text scripts no dragging boxes around in a design tool. That means your diagrams live right inside your documentation, version control, and markdown files. Learning how to write UML class diagram scripts in Mermaid.js saves time, reduces miscommunication, and keeps your docs in sync with your code.

What does a UML class diagram script in Mermaid.js actually look like?

A Mermaid.js class diagram starts with the keyword classDiagram and then defines classes, their members, and the relationships between them. The syntax is lightweight. You don't need special software just a text editor and a Mermaid renderer.

Here's the simplest possible example:

classDiagram
  class Animal
  class Dog

That defines two empty classes. Not very useful yet, but it shows how the structure works. Everything under classDiagram describes your class model line by line.

How do you add attributes and methods to a class?

You define a class's properties and methods using curly braces. Inside, each line is either an attribute or a method, written in a shorthand UML style:

classDiagram
  class Animal {
    +String name
    +int age
    +makeSound() void
  }

The + means public. Here are the visibility markers Mermaid supports:

  • + Public
  • - Private
  • # Protected
  • ~ Package/internal

Methods use parentheses. If a method returns nothing, you can write void or leave the return type out. Attributes use a type before the name, like String name or int age.

How do you show relationships like inheritance and composition?

This is where class diagrams become genuinely useful. Mermaid.js uses simple arrow syntax to represent UML relationships:

  • Inheritance: Dog --|> Animal (Dog extends Animal)
  • Composition: Room -- Wall (Room is composed of Walls)
  • Aggregation: Team o-- Player (Team has Players)
  • Association: Student -- Course (Student is linked to Course)
  • Dependency: Service ..> Repository (Service depends on Repository)
  • Realization (interface): Dog ..|> Pet (Dog implements Pet)

A fuller example combining classes and relationships:

classDiagram
  class Shape {
    +double area()
  }
  class Circle {
    +double radius
    +double area()
  }
  class Rectangle {
    +double width
    +double height
    +double area()
  }
  Circle --|> Shape
  Rectangle --|> Shape

This renders a clean inheritance diagram with three classes. If you need a broader reference on the full syntax, our UML diagram scripting syntax guide covers every relationship type in detail.

How do you represent abstract classes and interfaces?

Mermaid.js marks abstract classes by wrapping the class name or method in a way that signals abstraction. You use the abstract keyword or apply italic styling implicitly. The most direct approach is:

classDiagram
  abstract class Shape {
    +double area() double
  }
  class Square {
    +double side
    +double area() double
  }
  Square --|> Shape

For interfaces, use the <<interface>> stereotype:

classDiagram
  class Drawable {
    <<interface>>
    +draw() void
  }
  class Canvas {
    +draw() void
  }
  Canvas ..|> Drawable

You can also use <<enumeration>> and <<service>> stereotypes to label classes with specific roles. These stereotypes render as annotations above the class name in the diagram.

Can you add cardinality and multiplicity to relationships?

Yes, and you should. Cardinality tells readers how many instances are involved in a relationship. Mermaid.js supports this with a simple notation on either side of the arrow:

classDiagram
  class Order {
    +String orderId
  }
  class LineItem {
    +int quantity
    +double price
  }
  Order "1" -- "many" LineItem

Common cardinality labels include "1", "0..1", "1..", "many", and "". You place them in quotes on each side of the relationship arrow.

How do you render and test your Mermaid.js class diagrams?

There are several ways to preview your diagrams:

  • The Mermaid Live Editor lets you paste scripts and see results instantly in a browser.
  • VS Code extensions like "Mermaid Preview" render diagrams inside your editor.
  • GitHub, GitLab, and Notion natively render Mermaid code blocks in markdown.
  • Static site tools like Docusaurus and MkDocs support Mermaid through plugins.

For teams working on API or service architecture, sequence diagrams often complement class diagrams. If you're documenting REST API workflows alongside your class models, our PlantUML sequence diagram examples for REST APIs provide a good starting point for that.

What are the most common mistakes when writing class diagram scripts?

Having written dozens of these scripts and reviewed many more, here are the errors I see most often:

  • Forgetting the arrow direction. In Mermaid, A --|> B means A inherits from B. Swapping the direction gives the wrong meaning entirely.
  • Missing curly braces. If you list attributes without wrapping them in braces, Mermaid won't parse them as class members.
  • Using unsupported characters in names. Class names should be alphanumeric. Underscores work, but special characters and spaces cause parsing errors.
  • Overloading a single diagram. Trying to show 20 classes in one diagram creates a visual mess. Split complex systems into multiple focused diagrams.
  • Ignoring stereotypes. Without <<interface>> or <<abstract>>, readers can't tell class types apart from the rendered output alone.

How do you keep class diagram scripts readable as they grow?

A few practical habits make a real difference:

  • Group related classes together in the script with comments like %% User management above the relevant block.
  • Use consistent naming. Pick a convention (PascalCase for classes, camelCase for methods) and stick with it.
  • Add cardinality labels to every relationship. Without them, readers have to guess.
  • Keep one diagram per concept. A "User Management" diagram, a "Payment Processing" diagram, and so on.
  • Version your diagrams alongside your code. Store the .mmd files or markdown blocks in the same repo so they stay current.

For a deeper dive into script organization for larger projects, check out our guide on writing UML class diagram scripts in Mermaid.js which covers advanced patterns and multi-diagram workflows.

Quick reference: complete class diagram example

Here's a realistic script you can copy, paste into the Mermaid Live Editor, and modify for your own project:

classDiagram
  class User {
    +String id
    +String email
    +String name
    +login() void
    +logout() void
  }
  class Post {
    +String id
    +String title
    +String body
    +Date createdAt
    +publish() void
  }
  class Comment {
    +String id
    +String text
    +Date createdAt
  }
  class Tag {
    +String label
  }
  User "1" -- "many" Post : writes
  Post "1" -- "many" Comment : has
  User "1" -- "many" Comment : writes
  Post "many" -- "many" Tag : tagged with

This script models a simple blog platform. Notice the relationship labels after the colon : writes, : has which describe the nature of each connection in plain language.

Start here: a practical checklist

  1. Open the Mermaid Live Editor so you can test as you write.
  2. List the classes your diagram needs. Don't add methods yet just names.
  3. Define each class block with attributes and methods inside curly braces.
  4. Draw relationships using the correct arrow syntax for each type (inheritance, composition, etc.).
  5. Add cardinality labels to every relationship line.
  6. Use stereotypes like <<interface>> and abstract where they apply.
  7. Review the rendered diagram for layout clarity. Split into multiple diagrams if needed.
  8. Commit the script to version control alongside your source code.