Mermaid Class Diagrams for UML — Developer Guide
Create UML class diagrams with Mermaid.js. Learn classes, attributes, methods, relationships, inheritance, interfaces, and design patterns with examples.
What Are Class Diagrams?
Class diagrams are the backbone of UML (Unified Modeling Language) and the most common diagram for modeling object-oriented systems. They show classes, their attributes and methods, and the relationships between them.
Mermaid lets you create class diagrams from text, making them perfect for documenting codebases, planning architectures, and communicating designs in pull requests.
Basic Class Syntax
classDiagram
class Animal {
+String name
+int age
+makeSound() void
+move(distance) void
}Visibility Modifiers
Mermaid follows UML conventions:
- + Public
- - Private
- # Protected
- ~ Package/Internal
classDiagram
class User {
+String username
-String passwordHash
#String email
~int loginAttempts
+login(password) bool
-hashPassword(raw) String
#validateEmail() bool
}Relationships
Inheritance (Generalization)
classDiagram
Animal <|-- Dog
Animal <|-- Cat
Animal <|-- Bird
class Animal {
+String name
+makeSound() void
}
class Dog {
+fetch() void
}
class Cat {
+purr() void
}
class Bird {
+fly() void
}All Relationship Types
classDiagram
classA <|-- classB : Inheritance
classC *-- classD : Composition
classE o-- classF : Aggregation
classG --> classH : Association
classI -- classJ : Link
classK ..> classL : Dependency
classM ..|> classN : RealizationWhen to use each:
- Inheritance (
<|--): "is a" — Dog is an Animal - Composition (
*--): "owns, can't exist without" — Car owns Engine - Aggregation (
o--): "has, can exist independently" — Department has Employees - Association (
-->): "uses" — Order references Customer - Dependency (
..>): "temporarily uses" — Service depends on Logger - Realization (
..|>): "implements" — UserService implements IUserService
Cardinality (Multiplicity)
Show how many instances relate:
classDiagram
Customer "1" --> "*" Order : places
Order "1" --> "1..*" OrderItem : contains
OrderItem "*" --> "1" Product : referencesCommon multiplicities:
- 1 — exactly one
- 0..1 — zero or one
- * or 0..* — zero or more
- 1..* — one or more
Interfaces and Abstract Classes
classDiagram
class IRepository {
<<interface>>
+findById(id) Entity
+save(entity) void
+delete(id) void
}
class AbstractRepository {
<<abstract>>
#DataSource connection
+findById(id) Entity
#getConnection() DataSource
}
class UserRepository {
+findById(id) User
+findByEmail(email) User
+save(user) void
+delete(id) void
}
IRepository <|.. AbstractRepository
AbstractRepository <|-- UserRepositoryAnnotations
Use < for stereotypes:
classDiagram
class PaymentService {
<<service>>
}
class UserDTO {
<<dto>>
}
class Colors {
<<enumeration>>
RED
GREEN
BLUE
}Practical Example: E-Commerce Domain Model
classDiagram
class Customer {
+String id
+String name
+String email
+Address[] addresses
+placeOrder(items) Order
+getOrderHistory() Order[]
}
class Order {
+String id
+Date createdAt
+OrderStatus status
+Customer customer
+OrderItem[] items
+getTotal() Decimal
+cancel() void
}
class OrderItem {
+Product product
+int quantity
+Decimal unitPrice
+getSubtotal() Decimal
}
class Product {
+String id
+String name
+String description
+Decimal price
+int stockCount
+isInStock() bool
}
class Address {
+String street
+String city
+String state
+String zipCode
+String country
}
class OrderStatus {
<<enumeration>>
PENDING
CONFIRMED
SHIPPED
DELIVERED
CANCELLED
}
Customer "1" --> "*" Order : places
Customer "1" --> "*" Address : has
Order "1" --> "1..*" OrderItem : contains
Order --> OrderStatus
OrderItem "*" --> "1" Product : referencesDesign Pattern: Repository Pattern
classDiagram
class IRepository~T~ {
<<interface>>
+findById(id) T
+findAll() T[]
+save(entity) T
+delete(id) void
}
class UserRepository {
-DataSource db
+findById(id) User
+findAll() User[]
+save(user) User
+delete(id) void
+findByEmail(email) User
}
class ProductRepository {
-DataSource db
+findById(id) Product
+findAll() Product[]
+save(product) Product
+delete(id) void
+findByCategory(cat) Product[]
}
class UserService {
-UserRepository userRepo
+getUser(id) User
+createUser(data) User
+updateUser(id, data) User
}
IRepository~T~ <|.. UserRepository
IRepository~T~ <|.. ProductRepository
UserService --> UserRepository : usesGenerics
Mermaid supports generic types with tilde syntax:
classDiagram
class List~T~ {
+add(item T) void
+get(index int) T
+size() int
}
class Map~K, V~ {
+put(key K, value V) void
+get(key K) V
}Namespaces
Group related classes:
classDiagram
namespace Domain {
class User {
+String name
}
class Order {
+Date date
}
}
namespace Infrastructure {
class Database {
+connect() void
}
class Cache {
+get(key) String
}
}
User --> Order
Order ..> DatabaseStyling
classDiagram
class Service {
+process() void
}
class Entity {
+String id
}
style Service fill:#e1f5fe,stroke:#0288d1
style Entity fill:#f3e5f5,stroke:#7b1fa2Best Practices
- Focus on the domain. Don't diagram every utility class — show the important domain entities and their relationships.
- Use correct relationship types. Composition vs. aggregation vs. association matters for communicating intent.
- Include cardinality on associations — it clarifies the data model significantly.
- Show key methods only. Skip getters/setters and boilerplate. Show the methods that define behavior.
- Use interfaces to show contracts. This communicates the architecture's extension points.
- Group with namespaces for large models. Separate domain, infrastructure, and application layers.
- Add annotations (
<,> <,> <) to clarify the role of each class.>
- Keep diagrams focused. One diagram per bounded context or module. A single diagram with 30+ classes helps nobody.
Conclusion
Mermaid class diagrams bring UML into your codebase. They're ideal for documenting domain models, communicating design decisions in pull requests, and maintaining architecture docs that stay current. The text-based format means they're diffable, reviewable, and version-controlled — everything a developer needs.