diff --git a/README.md b/README.md
index 31c6d62c6..941e1fd18 100644
--- a/README.md
+++ b/README.md
@@ -165,6 +165,13 @@ class Class10 {
   int id
   size()
 }
+namespace Namespace01 {
+  class Class11
+  class Class12 {
+    int id
+    size()
+  }
+}
 ```
 
 ```mermaid
@@ -184,6 +191,13 @@ class Class10 {
   int id
   size()
 }
+namespace Namespace01 {
+  class Class11
+  class Class12 {
+    int id
+    size()
+  }
+}
 ```
 
 ### State diagram [<a href="https://mermaid-js.github.io/mermaid/#/stateDiagram">docs</a> - <a href="https://mermaid.live/edit#pako:eNpdkEFvgzAMhf8K8nEqpYSNthx22Xbcqcexg0sCiZQQlDhIFeK_L8A6TfXp6fOz9ewJGssFVOAJSbwr7ByadGR1n8T6evpO0vQ1uZDSekOrXGFsPqJPO6q-2-imH8f_0TeHXm50lfelsAMjnEHFY6xpMdRAUhhRQxUlFy0GTTXU_RytYeAx-AdXZB1ULWovdoCB7OXWN1CRC-Ju-r3uz6UtchGHJqDbsPygU57iysb2reoWHpyOWBINvsqypb3vFMlw3TfWZF5xiY7keC6zkpUnZIUojwW-FAVvrvn51LLnvOXHQ84Q5nn-AVtLcwk">live editor</a>]
diff --git a/cypress/integration/rendering/classDiagram-v2.spec.js b/cypress/integration/rendering/classDiagram-v2.spec.js
index a11571814..2e7a1cbd7 100644
--- a/cypress/integration/rendering/classDiagram-v2.spec.js
+++ b/cypress/integration/rendering/classDiagram-v2.spec.js
@@ -548,4 +548,18 @@ class C13["With Città foreign language"]
 `
     );
   });
+  it('should add classes namespaces', function () {
+    imgSnapshotTest(
+      `
+      classDiagram
+      namespace Namespace1 {
+        class C1
+        class C2
+      }
+      C1 --> C2
+      class C3
+      class C4
+      `
+    );
+  });
 });
diff --git a/docs/syntax/classDiagram.md b/docs/syntax/classDiagram.md
index 1287908c9..a6109149a 100644
--- a/docs/syntax/classDiagram.md
+++ b/docs/syntax/classDiagram.md
@@ -421,6 +421,34 @@ And `Link` can be one of:
 | --   | Solid       |
 | ..   | Dashed      |
 
+## Define Namespace
+
+A namespace groups classes.
+
+Code:
+
+```mermaid-example
+classDiagram
+namespace BaseShapes {
+    class Triangle
+    class Rectangle {
+      double width
+      double height
+    }
+}
+```
+
+```mermaid
+classDiagram
+namespace BaseShapes {
+    class Triangle
+    class Rectangle {
+      double width
+      double height
+    }
+}
+```
+
 ## Cardinality / Multiplicity on relations
 
 Multiplicity or cardinality in class diagrams indicates the number of instances of one class that can be linked to an instance of the other class. For example, each company will have one or more employees (not zero), and each employee currently works for zero or one companies.
diff --git a/packages/mermaid/src/diagrams/class/classDb.ts b/packages/mermaid/src/diagrams/class/classDb.ts
index a2121f69e..d9e17db54 100644
--- a/packages/mermaid/src/diagrams/class/classDb.ts
+++ b/packages/mermaid/src/diagrams/class/classDb.ts
@@ -14,7 +14,14 @@ import {
   setDiagramTitle,
   getDiagramTitle,
 } from '../../commonDb.js';
-import { ClassRelation, ClassNode, ClassNote, ClassMap } from './classTypes.js';
+import {
+  ClassRelation,
+  ClassNode,
+  ClassNote,
+  ClassMap,
+  NamespaceMap,
+  NamespaceNode,
+} from './classTypes.js';
 
 const MERMAID_DOM_ID_PREFIX = 'classId-';
 
@@ -22,6 +29,8 @@ let relations: ClassRelation[] = [];
 let classes: ClassMap = {};
 let notes: ClassNote[] = [];
 let classCounter = 0;
+let namespaces: NamespaceMap = {};
+let namespaceCounter = 0;
 
 let functions: any[] = [];
 
@@ -100,6 +109,8 @@ export const clear = function () {
   notes = [];
   functions = [];
   functions.push(setupToolTips);
+  namespaces = {};
+  namespaceCounter = 0;
   commonClear();
 };
 
@@ -237,7 +248,11 @@ const setTooltip = function (ids: string, tooltip?: string) {
   });
 };
 
-export const getTooltip = function (id: string) {
+export const getTooltip = function (id: string, namespace?: string) {
+  if (namespace) {
+    return namespaces[namespace].classes[id].tooltip;
+  }
+
   return classes[id].tooltip;
 };
 /**
@@ -395,6 +410,52 @@ const setDirection = (dir: string) => {
   direction = dir;
 };
 
+/**
+ * Function called by parser when a namespace definition has been found.
+ *
+ * @param id - Id of the namespace to add
+ * @public
+ */
+export const addNamespace = function (id: string) {
+  if (namespaces[id] !== undefined) {
+    return;
+  }
+
+  namespaces[id] = {
+    id: id,
+    classes: {},
+    children: {},
+    domId: MERMAID_DOM_ID_PREFIX + id + '-' + namespaceCounter,
+  } as NamespaceNode;
+
+  namespaceCounter++;
+};
+
+const getNamespace = function (name: string): NamespaceNode {
+  return namespaces[name];
+};
+
+const getNamespaces = function (): NamespaceMap {
+  return namespaces;
+};
+
+/**
+ * Function called by parser when a namespace definition has been found.
+ *
+ * @param id - Id of the namespace to add
+ * @param classNames - Ids of the class to add
+ * @public
+ */
+export const addClassesToNamespace = function (id: string, classNames: string[]) {
+  if (namespaces[id] !== undefined) {
+    classNames.map((className) => {
+      namespaces[id].classes[className] = classes[className];
+      delete classes[className];
+      classCounter--;
+    });
+  }
+};
+
 export default {
   parseDirective,
   setAccTitle,
@@ -428,4 +489,8 @@ export default {
   setDiagramTitle,
   getDiagramTitle,
   setClassLabel,
+  addNamespace,
+  addClassesToNamespace,
+  getNamespace,
+  getNamespaces,
 };
diff --git a/packages/mermaid/src/diagrams/class/classDiagram.spec.ts b/packages/mermaid/src/diagrams/class/classDiagram.spec.ts
index f2492e5cc..a43ed2fcd 100644
--- a/packages/mermaid/src/diagrams/class/classDiagram.spec.ts
+++ b/packages/mermaid/src/diagrams/class/classDiagram.spec.ts
@@ -816,6 +816,37 @@ describe('given a class diagram with generics, ', function () {
 
       parser.parse(str);
     });
+
+    it('should handle "namespace"', function () {
+      const str = `classDiagram
+namespace Namespace1 { class Class1 }
+namespace Namespace2 { class Class1
+}
+namespace Namespace3 {
+class Class1 {
+int : test
+string : foo
+test()
+foo()
+}
+}
+namespace Namespace4 {
+class Class1 {
+int : test
+string : foo
+test()
+foo()
+}
+class Class2 {
+int : test
+string : foo
+test()
+foo()
+}
+}
+`;
+      parser.parse(str);
+    });
   });
 
   describe('when parsing invalid generic classes', function () {
@@ -1051,5 +1082,487 @@ describe('given a class diagram with relationships, ', function () {
       expect(relations[3].relation.type2).toBe('none');
       expect(relations[3].relation.lineType).toBe(classDb.lineType.DOTTED_LINE);
     });
+
+    it('should handle generic class with relation definitions', function () {
+      const str = 'classDiagram\n' + 'Class01~T~ <|-- Class02';
+
+      parser.parse(str);
+
+      const relations = parser.yy.getRelations();
+
+      expect(parser.yy.getClass('Class01').id).toBe('Class01');
+      expect(parser.yy.getClass('Class01').type).toBe('T');
+      expect(parser.yy.getClass('Class02').id).toBe('Class02');
+      expect(relations[0].relation.type1).toBe(classDb.relationType.EXTENSION);
+      expect(relations[0].relation.type2).toBe('none');
+      expect(relations[0].relation.lineType).toBe(classDb.lineType.LINE);
+    });
+
+    it('should handle class annotations', function () {
+      const str = 'classDiagram\n' + 'class Class1\n' + '<<interface>> Class1';
+      parser.parse(str);
+
+      const testClass = parser.yy.getClass('Class1');
+      expect(testClass.annotations.length).toBe(1);
+      expect(testClass.members.length).toBe(0);
+      expect(testClass.methods.length).toBe(0);
+      expect(testClass.annotations[0]).toBe('interface');
+    });
+
+    it('should handle class annotations with members and methods', function () {
+      const str =
+        'classDiagram\n' +
+        'class Class1\n' +
+        'Class1 : int test\n' +
+        'Class1 : test()\n' +
+        '<<interface>> Class1';
+      parser.parse(str);
+
+      const testClass = parser.yy.getClass('Class1');
+      expect(testClass.annotations.length).toBe(1);
+      expect(testClass.members.length).toBe(1);
+      expect(testClass.methods.length).toBe(1);
+      expect(testClass.annotations[0]).toBe('interface');
+    });
+
+    it('should handle class annotations in brackets', function () {
+      const str = 'classDiagram\n' + 'class Class1 {\n' + '<<interface>>\n' + '}';
+      parser.parse(str);
+
+      const testClass = parser.yy.getClass('Class1');
+      expect(testClass.annotations.length).toBe(1);
+      expect(testClass.members.length).toBe(0);
+      expect(testClass.methods.length).toBe(0);
+      expect(testClass.annotations[0]).toBe('interface');
+    });
+
+    it('should handle class annotations in brackets with members and methods', function () {
+      const str =
+        'classDiagram\n' +
+        'class Class1 {\n' +
+        '<<interface>>\n' +
+        'int : test\n' +
+        'test()\n' +
+        '}';
+      parser.parse(str);
+
+      const testClass = parser.yy.getClass('Class1');
+      expect(testClass.annotations.length).toBe(1);
+      expect(testClass.members.length).toBe(1);
+      expect(testClass.methods.length).toBe(1);
+      expect(testClass.annotations[0]).toBe('interface');
+    });
+
+    it('should add bracket members in right order', function () {
+      const str =
+        'classDiagram\n' +
+        'class Class1 {\n' +
+        'int : test\n' +
+        'string : foo\n' +
+        'test()\n' +
+        'foo()\n' +
+        '}';
+      parser.parse(str);
+
+      const testClass = parser.yy.getClass('Class1');
+      expect(testClass.members.length).toBe(2);
+      expect(testClass.methods.length).toBe(2);
+      expect(testClass.members[0]).toBe('int : test');
+      expect(testClass.members[1]).toBe('string : foo');
+      expect(testClass.methods[0]).toBe('test()');
+      expect(testClass.methods[1]).toBe('foo()');
+    });
+
+    it('should handle abstract methods', function () {
+      const str = 'classDiagram\n' + 'class Class1\n' + 'Class1 : someMethod()*';
+      parser.parse(str);
+
+      const testClass = parser.yy.getClass('Class1');
+      expect(testClass.annotations.length).toBe(0);
+      expect(testClass.members.length).toBe(0);
+      expect(testClass.methods.length).toBe(1);
+      expect(testClass.methods[0]).toBe('someMethod()*');
+    });
+
+    it('should handle static methods', function () {
+      const str = 'classDiagram\n' + 'class Class1\n' + 'Class1 : someMethod()$';
+      parser.parse(str);
+
+      const testClass = parser.yy.getClass('Class1');
+      expect(testClass.annotations.length).toBe(0);
+      expect(testClass.members.length).toBe(0);
+      expect(testClass.methods.length).toBe(1);
+      expect(testClass.methods[0]).toBe('someMethod()$');
+    });
+
+    it('should associate link and css appropriately', function () {
+      const str =
+        'classDiagram\n' +
+        'class Class1\n' +
+        'Class1 : someMethod()\n' +
+        'link Class1 "google.com"';
+      parser.parse(str);
+
+      const testClass = parser.yy.getClass('Class1');
+      expect(testClass.link).toBe('google.com');
+      expect(testClass.cssClasses.length).toBe(1);
+      expect(testClass.cssClasses[0]).toBe('clickable');
+    });
+
+    it('should associate click and href link and css appropriately', function () {
+      const str =
+        'classDiagram\n' +
+        'class Class1\n' +
+        'Class1 : someMethod()\n' +
+        'click Class1 href "google.com"';
+      parser.parse(str);
+
+      const testClass = parser.yy.getClass('Class1');
+      expect(testClass.link).toBe('google.com');
+      expect(testClass.cssClasses.length).toBe(1);
+      expect(testClass.cssClasses[0]).toBe('clickable');
+    });
+
+    it('should associate link with tooltip', function () {
+      const str =
+        'classDiagram\n' +
+        'class Class1\n' +
+        'Class1 : someMethod()\n' +
+        'link Class1 "google.com" "A tooltip"';
+      parser.parse(str);
+
+      const testClass = parser.yy.getClass('Class1');
+      expect(testClass.link).toBe('google.com');
+      expect(testClass.tooltip).toBe('A tooltip');
+      expect(testClass.cssClasses.length).toBe(1);
+      expect(testClass.cssClasses[0]).toBe('clickable');
+    });
+
+    it('should associate click and href link with tooltip', function () {
+      const str =
+        'classDiagram\n' +
+        'class Class1\n' +
+        'Class1 : someMethod()\n' +
+        'click Class1 href "google.com" "A tooltip"';
+      parser.parse(str);
+
+      const testClass = parser.yy.getClass('Class1');
+      expect(testClass.link).toBe('google.com');
+      expect(testClass.tooltip).toBe('A tooltip');
+      expect(testClass.cssClasses.length).toBe(1);
+      expect(testClass.cssClasses[0]).toBe('clickable');
+    });
+
+    it('should associate click and href link with tooltip and target appropriately', function () {
+      spyOn(classDb, 'setLink');
+      spyOn(classDb, 'setTooltip');
+      const str =
+        'classDiagram\n' +
+        'class Class1\n' +
+        'Class1 : someMethod()\n' +
+        'click Class1 href "google.com" "A tooltip" _self';
+      parser.parse(str);
+
+      expect(classDb.setLink).toHaveBeenCalledWith('Class1', 'google.com', '_self');
+      expect(classDb.setTooltip).toHaveBeenCalledWith('Class1', 'A tooltip');
+    });
+
+    it('should associate click and href link appropriately', function () {
+      spyOn(classDb, 'setLink');
+      const str =
+        'classDiagram\n' +
+        'class Class1\n' +
+        'Class1 : someMethod()\n' +
+        'click Class1 href "google.com"';
+      parser.parse(str);
+
+      expect(classDb.setLink).toHaveBeenCalledWith('Class1', 'google.com');
+    });
+
+    it('should associate click and href link with target appropriately', function () {
+      spyOn(classDb, 'setLink');
+      const str =
+        'classDiagram\n' +
+        'class Class1\n' +
+        'Class1 : someMethod()\n' +
+        'click Class1 href "google.com" _self';
+      parser.parse(str);
+
+      expect(classDb.setLink).toHaveBeenCalledWith('Class1', 'google.com', '_self');
+    });
+
+    it('should associate link appropriately', function () {
+      spyOn(classDb, 'setLink');
+      spyOn(classDb, 'setTooltip');
+      const str =
+        'classDiagram\n' +
+        'class Class1\n' +
+        'Class1 : someMethod()\n' +
+        'link Class1 "google.com" "A tooltip" _self';
+      parser.parse(str);
+
+      expect(classDb.setLink).toHaveBeenCalledWith('Class1', 'google.com', '_self');
+      expect(classDb.setTooltip).toHaveBeenCalledWith('Class1', 'A tooltip');
+    });
+
+    it('should associate callback appropriately', function () {
+      spyOn(classDb, 'setClickEvent');
+      const str =
+        'classDiagram\n' +
+        'class Class1\n' +
+        'Class1 : someMethod()\n' +
+        'callback Class1 "functionCall"';
+      parser.parse(str);
+
+      expect(classDb.setClickEvent).toHaveBeenCalledWith('Class1', 'functionCall');
+    });
+
+    it('should associate click and call callback appropriately', function () {
+      spyOn(classDb, 'setClickEvent');
+      const str =
+        'classDiagram\n' +
+        'class Class1\n' +
+        'Class1 : someMethod()\n' +
+        'click Class1 call functionCall()';
+      parser.parse(str);
+
+      expect(classDb.setClickEvent).toHaveBeenCalledWith('Class1', 'functionCall');
+    });
+
+    it('should associate callback appropriately with an arbitrary number of args', function () {
+      spyOn(classDb, 'setClickEvent');
+      const str =
+        'classDiagram\n' +
+        'class Class1\n' +
+        'Class1 : someMethod()\n' +
+        'click Class1 call functionCall("test0", test1, test2)';
+      parser.parse(str);
+
+      expect(classDb.setClickEvent).toHaveBeenCalledWith(
+        'Class1',
+        'functionCall',
+        '"test0", test1, test2'
+      );
+    });
+
+    it('should associate callback with tooltip', function () {
+      spyOn(classDb, 'setClickEvent');
+      spyOn(classDb, 'setTooltip');
+      const str =
+        'classDiagram\n' +
+        'class Class1\n' +
+        'Class1 : someMethod()\n' +
+        'click Class1 call functionCall() "A tooltip"';
+      parser.parse(str);
+
+      expect(classDb.setClickEvent).toHaveBeenCalledWith('Class1', 'functionCall');
+      expect(classDb.setTooltip).toHaveBeenCalledWith('Class1', 'A tooltip');
+    });
+
+    it('should add classes namespaces', function () {
+      const str = `classDiagram
+namespace Namespace1 {
+class Class1 {
+int : test
+string : foo
+test()
+foo()
+}
+class Class2
+}`;
+      parser.parse(str);
+
+      const testNamespace = parser.yy.getNamespace('Namespace1');
+      expect(Object.keys(testNamespace.classes).length).toBe(2);
+      expect(Object.keys(testNamespace.children).length).toBe(0);
+      expect(testNamespace.classes['Class1'].id).toBe('Class1');
+    });
+  });
+
+  describe('when parsing classDiagram with text labels', () => {
+    beforeEach(function () {
+      parser.yy = classDb;
+      parser.yy.clear();
+    });
+
+    it('should parse a class with a text label', () => {
+      parser.parse(`classDiagram
+  class C1["Class 1 with text label"]
+  C1 -->  C2
+      `);
+      const c1 = classDb.getClass('C1');
+      expect(c1.label).toBe('Class 1 with text label');
+      const c2 = classDb.getClass('C2');
+      expect(c2.label).toBe('C2');
+    });
+
+    it('should parse two classes with text labels', () => {
+      parser.parse(`classDiagram
+  class C1["Class 1 with text label"]
+  class C2["Class 2 with chars @?"]
+  C1 -->  C2
+      `);
+      const c1 = classDb.getClass('C1');
+      expect(c1.label).toBe('Class 1 with text label');
+      const c2 = classDb.getClass('C2');
+      expect(c2.label).toBe('Class 2 with chars @?');
+    });
+
+    it('should parse a class with a text label and members', () => {
+      parser.parse(`classDiagram
+  class C1["Class 1 with text label"] {
+    +member1
+  }
+  C1 -->  C2
+      `);
+      const c1 = classDb.getClass('C1');
+      expect(c1.label).toBe('Class 1 with text label');
+      expect(c1.members.length).toBe(1);
+      expect(c1.members[0]).toBe('+member1');
+
+      const c2 = classDb.getClass('C2');
+      expect(c2.label).toBe('C2');
+    });
+
+    it('should parse a class with a text label, members and annotation', () => {
+      parser.parse(`classDiagram
+  class C1["Class 1 with text label"] {
+    <<interface>>
+    +member1
+  }
+  C1 -->  C2
+      `);
+      const c1 = classDb.getClass('C1');
+      expect(c1.label).toBe('Class 1 with text label');
+      expect(c1.members.length).toBe(1);
+      expect(c1.members[0]).toBe('+member1');
+      expect(c1.annotations.length).toBe(1);
+      expect(c1.annotations[0]).toBe('interface');
+
+      const c2 = classDb.getClass('C2');
+      expect(c2.label).toBe('C2');
+    });
+
+    it('should parse a class with text label and css class shorthand', () => {
+      parser.parse(`classDiagram
+class C1["Class 1 with text label"]:::styleClass {
+  +member1
+}
+C1 -->  C2
+  `);
+
+      const c1 = classDb.getClass('C1');
+      expect(c1.label).toBe('Class 1 with text label');
+      expect(c1.cssClasses.length).toBe(1);
+      expect(c1.members[0]).toBe('+member1');
+      expect(c1.cssClasses[0]).toBe('styleClass');
+    });
+
+    it('should parse a class with text label and css class', () => {
+      parser.parse(`classDiagram
+class C1["Class 1 with text label"] {
+  +member1
+}
+C1 --> C2
+cssClass "C1" styleClass
+  `);
+
+      const c1 = classDb.getClass('C1');
+      expect(c1.label).toBe('Class 1 with text label');
+      expect(c1.cssClasses.length).toBe(1);
+      expect(c1.members[0]).toBe('+member1');
+      expect(c1.cssClasses[0]).toBe('styleClass');
+    });
+
+    it('should parse two classes with text labels and css classes', () => {
+      parser.parse(`classDiagram
+class C1["Class 1 with text label"] {
+  +member1
+}
+class C2["Long long long long long long long long long long label"]
+C1 --> C2
+cssClass "C1,C2" styleClass
+  `);
+
+      const c1 = classDb.getClass('C1');
+      expect(c1.label).toBe('Class 1 with text label');
+      expect(c1.cssClasses.length).toBe(1);
+      expect(c1.cssClasses[0]).toBe('styleClass');
+
+      const c2 = classDb.getClass('C2');
+      expect(c2.label).toBe('Long long long long long long long long long long label');
+      expect(c2.cssClasses.length).toBe(1);
+      expect(c2.cssClasses[0]).toBe('styleClass');
+    });
+
+    it('should parse two classes with text labels and css class shorthands', () => {
+      parser.parse(`classDiagram
+class C1["Class 1 with text label"]:::styleClass1 {
+  +member1
+}
+class C2["Class 2 !@#$%^&*() label"]:::styleClass2
+C1 --> C2
+  `);
+
+      const c1 = classDb.getClass('C1');
+      expect(c1.label).toBe('Class 1 with text label');
+      expect(c1.cssClasses.length).toBe(1);
+      expect(c1.cssClasses[0]).toBe('styleClass1');
+
+      const c2 = classDb.getClass('C2');
+      expect(c2.label).toBe('Class 2 !@#$%^&*() label');
+      expect(c2.cssClasses.length).toBe(1);
+      expect(c2.cssClasses[0]).toBe('styleClass2');
+    });
+
+    it('should parse multiple classes with same text labels', () => {
+      parser.parse(`classDiagram
+class C1["Class with text label"]
+class C2["Class with text label"]
+class C3["Class with text label"]
+C1 --> C2
+C3 ..> C2
+  `);
+
+      const c1 = classDb.getClass('C1');
+      expect(c1.label).toBe('Class with text label');
+
+      const c2 = classDb.getClass('C2');
+      expect(c2.label).toBe('Class with text label');
+
+      const c3 = classDb.getClass('C3');
+      expect(c3.label).toBe('Class with text label');
+    });
+
+    it('should parse classes with different text labels', () => {
+      parser.parse(`classDiagram
+class C1["OneWord"]
+class C2["With, Comma"]
+class C3["With (Brackets)"]
+class C4["With [Brackets]"]
+class C5["With {Brackets}"]
+class C6[" "]
+class C7["With 1 number"]
+class C8["With . period..."]
+class C9["With - dash"]
+class C10["With _ underscore"]
+class C11["With ' single quote"]
+class C12["With ~!@#$%^&*()_+=-/?"]
+class C13["With Città foreign language"]
+`);
+      expect(classDb.getClass('C1').label).toBe('OneWord');
+      expect(classDb.getClass('C2').label).toBe('With, Comma');
+      expect(classDb.getClass('C3').label).toBe('With (Brackets)');
+      expect(classDb.getClass('C4').label).toBe('With [Brackets]');
+      expect(classDb.getClass('C5').label).toBe('With {Brackets}');
+      expect(classDb.getClass('C6').label).toBe(' ');
+      expect(classDb.getClass('C7').label).toBe('With 1 number');
+      expect(classDb.getClass('C8').label).toBe('With . period...');
+      expect(classDb.getClass('C9').label).toBe('With - dash');
+      expect(classDb.getClass('C10').label).toBe('With _ underscore');
+      expect(classDb.getClass('C11').label).toBe("With ' single quote");
+      expect(classDb.getClass('C12').label).toBe('With ~!@#$%^&*()_+=-/?');
+      expect(classDb.getClass('C13').label).toBe('With Città foreign language');
+    });
   });
 });
diff --git a/packages/mermaid/src/diagrams/class/classRenderer-v2.ts b/packages/mermaid/src/diagrams/class/classRenderer-v2.ts
index 82447c54f..352002242 100644
--- a/packages/mermaid/src/diagrams/class/classRenderer-v2.ts
+++ b/packages/mermaid/src/diagrams/class/classRenderer-v2.ts
@@ -8,7 +8,7 @@ import utils from '../../utils.js';
 import { interpolateToCurve, getStylesFromArray } from '../../utils.js';
 import { setupGraphViewbox } from '../../setupGraphViewbox.js';
 import common from '../common/common.js';
-import { ClassRelation, ClassNote, ClassMap, EdgeData } from './classTypes.js';
+import { ClassRelation, ClassNote, ClassMap, EdgeData, NamespaceMap } from './classTypes.js';
 
 const sanitizeText = (txt: string) => common.sanitizeText(txt, getConfig());
 
@@ -19,6 +19,59 @@ let conf = {
   curve: undefined,
 };
 
+interface RectParameters {
+  id: string;
+  shape: 'rect';
+  labelStyle: string;
+  domId: string;
+  labelText: string;
+  padding: number | undefined;
+  style?: string;
+}
+
+/**
+ * Function that adds the vertices found during parsing to the graph to be rendered.
+ *
+ * @param namespaces - Object containing the vertices.
+ * @param g - The graph that is to be drawn.
+ * @param _id - id of the graph
+ * @param diagObj - The diagram object
+ */
+export const addNamespaces = function (
+  namespaces: NamespaceMap,
+  g: graphlib.Graph,
+  _id: string,
+  diagObj: any
+) {
+  const keys = Object.keys(namespaces);
+  log.info('keys:', keys);
+  log.info(namespaces);
+
+  // Iterate through each item in the vertex object (containing all the vertices found) in the graph definition
+  keys.forEach(function (id) {
+    const vertex = namespaces[id];
+
+    // parent node must be one of [rect, roundedWithTitle, noteGroup, divider]
+    const shape = 'rect';
+
+    const node: RectParameters = {
+      shape: shape,
+      id: vertex.id,
+      domId: vertex.domId,
+      labelText: sanitizeText(vertex.id),
+      labelStyle: '',
+      style: 'fill: none; stroke: black',
+      // TODO V10: Flowchart ? Keeping flowchart for backwards compatibility. Remove in next major release
+      padding: getConfig().flowchart?.padding ?? getConfig().class?.padding,
+    };
+
+    g.setNode(vertex.id, node);
+    addClasses(vertex.classes, g, _id, diagObj, vertex.id);
+
+    log.info('setNode', node);
+  });
+};
+
 /**
  * Function that adds the vertices found during parsing to the graph to be rendered.
  *
@@ -26,12 +79,14 @@ let conf = {
  * @param g - The graph that is to be drawn.
  * @param _id - id of the graph
  * @param diagObj - The diagram object
+ * @param parent - id of the parent namespace, if it exists
  */
 export const addClasses = function (
   classes: ClassMap,
   g: graphlib.Graph,
   _id: string,
-  diagObj: any
+  diagObj: any,
+  parent?: string
 ) {
   const keys = Object.keys(classes);
   log.info('keys:', keys);
@@ -55,6 +110,7 @@ export const addClasses = function (
     const vertexText = vertex.label ?? vertex.id;
     const radius = 0;
     const shape = 'class_box';
+
     // Add the node
     const node = {
       labelStyle: styles.labelStyle,
@@ -67,7 +123,7 @@ export const addClasses = function (
       style: styles.style,
       id: vertex.id,
       domId: vertex.domId,
-      tooltip: diagObj.db.getTooltip(vertex.id) || '',
+      tooltip: diagObj.db.getTooltip(vertex.id, parent) || '',
       haveCallback: vertex.haveCallback,
       link: vertex.link,
       width: vertex.type === 'group' ? 500 : undefined,
@@ -76,6 +132,11 @@ export const addClasses = function (
       padding: getConfig().flowchart?.padding ?? getConfig().class?.padding,
     };
     g.setNode(vertex.id, node);
+
+    if (parent) {
+      g.setParent(vertex.id, parent);
+    }
+
     log.info('setNode', node);
   });
 };
@@ -275,10 +336,12 @@ export const draw = async function (text: string, id: string, _version: string,
     });
 
   // Fetch the vertices/nodes and edges/links from the parsed graph definition
+  const namespaces: NamespaceMap = diagObj.db.getNamespaces();
   const classes: ClassMap = diagObj.db.getClasses();
   const relations: ClassRelation[] = diagObj.db.getRelations();
   const notes: ClassNote[] = diagObj.db.getNotes();
   log.info(relations);
+  addNamespaces(namespaces, g, id, diagObj);
   addClasses(classes, g, id, diagObj);
   addRelations(relations, g);
   addNotes(notes, g, relations.length + 1, classes);
diff --git a/packages/mermaid/src/diagrams/class/classTypes.ts b/packages/mermaid/src/diagrams/class/classTypes.ts
index 4cacad3db..cf6f20f0b 100644
--- a/packages/mermaid/src/diagrams/class/classTypes.ts
+++ b/packages/mermaid/src/diagrams/class/classTypes.ts
@@ -52,4 +52,13 @@ export type ClassRelation = {
     lineType: number;
   };
 };
+
+export interface NamespaceNode {
+  id: string;
+  domId: string;
+  classes: ClassMap;
+  children: NamespaceMap;
+}
+
 export type ClassMap = Record<string, ClassNode>;
+export type NamespaceMap = Record<string, NamespaceNode>;
diff --git a/packages/mermaid/src/diagrams/class/parser/classDiagram.jison b/packages/mermaid/src/diagrams/class/parser/classDiagram.jison
index 7afba66bc..7788fcc0c 100644
--- a/packages/mermaid/src/diagrams/class/parser/classDiagram.jison
+++ b/packages/mermaid/src/diagrams/class/parser/classDiagram.jison
@@ -19,6 +19,10 @@
 %x acc_title
 %x acc_descr
 %x acc_descr_multiline
+%x class
+%x class-body
+%x namespace
+%x namespace-body
 %%
 \%\%\{                                                          { this.begin('open_directive'); return 'open_directive'; }
 .*direction\s+TB[^\n]*                                          return 'direction_tb';
@@ -41,35 +45,41 @@ accDescr\s*"{"\s*                                { this.begin("acc_descr_multili
 
 \s*(\r?\n)+                return 'NEWLINE';
 \s+                     /* skip whitespace */
+
 "classDiagram-v2"       return 'CLASS_DIAGRAM';
 "classDiagram"          return 'CLASS_DIAGRAM';
-[{]                     { this.begin("struct"); /*console.log('Starting struct');*/ return 'STRUCT_START';}
-<INITIAL,struct>"[*]"   { /*console.log('EDGE_STATE=',yytext);*/ return 'EDGE_STATE';}
-<struct><<EOF>>         return "EOF_IN_STRUCT";
-<struct>[{]             return "OPEN_IN_STRUCT";
-<struct>[}]             { /*console.log('Ending struct');*/this.popState(); return 'STRUCT_STOP';}}
-<struct>[\n]            /* nothing */
-<struct>[^{}\n]*        { /*console.log('lex-member: ' + yytext);*/  return "MEMBER";}
+"[*]"                   return 'EDGE_STATE';
 
-"class"               return 'CLASS';
-"cssClass"            return 'CSSCLASS';
-"callback"            return 'CALLBACK';
-"link"                return 'LINK';
-"click"               return 'CLICK';
-"note for"            return 'NOTE_FOR';
-"note"                return 'NOTE';
-"<<"                  return 'ANNOTATION_START';
-">>"                  return 'ANNOTATION_END';
-[~]                   this.begin("generic");
-<generic>[~]          this.popState();
-<generic>[^~]*        return "GENERICTYPE";
-["]                   this.begin("string");
-<string>["]           this.popState();
-<string>[^"]*         return "STR";
+<INITIAL,namespace>"namespace"  { this.begin('namespace'); return 'NAMESPACE'; }
+<namespace>\s*(\r?\n)+          { this.popState(); return 'NEWLINE'; }
+<namespace>\s+                  /* skip whitespace */
+<namespace>[{]                  { this.begin("namespace-body"); return 'STRUCT_START';}
+<namespace-body>[}]             { this.popState(); return 'STRUCT_STOP'; }
+<namespace-body><<EOF>>         return "EOF_IN_STRUCT";
+<namespace-body>\s*(\r?\n)+     return 'NEWLINE';
+<namespace-body>\s+             /* skip whitespace */
+<namespace-body>"[*]"           return 'EDGE_STATE';
 
-[`]                   this.begin("bqstring");
-<bqstring>[`]         this.popState();
-<bqstring>[^`]+       return "BQUOTE_STR";
+<INITIAL,namespace-body>"class"     { this.begin('class'); return 'CLASS';}
+<class>\s*(\r?\n)+          { this.popState(); return 'NEWLINE'; }
+<class>\s+                  /* skip whitespace */
+<class>[}]                  { this.popState(); this.popState(); return 'STRUCT_STOP';}
+<class>[{]                  { this.begin("class-body"); return 'STRUCT_START';}
+<class-body>[}]             { this.popState(); return 'STRUCT_STOP'; }
+<class-body><<EOF>>         return "EOF_IN_STRUCT";
+<class-body>"[*]"           { return 'EDGE_STATE';}
+<class-body>[{]             return "OPEN_IN_STRUCT";
+<class-body>[\n]            /* nothing */
+<class-body>[^{}\n]*        { return "MEMBER";}
+
+<*>"cssClass"           return 'CSSCLASS';
+<*>"callback"           return 'CALLBACK';
+<*>"link"               return 'LINK';
+<*>"click"              return 'CLICK';
+<*>"note for"           return 'NOTE_FOR';
+<*>"note"               return 'NOTE';
+<*>"<<"                 return 'ANNOTATION_START';
+<*>">>"                 return 'ANNOTATION_END';
 
 /*
 ---interactivity command---
@@ -77,7 +87,7 @@ accDescr\s*"{"\s*                                { this.begin("acc_descr_multili
 line was introduced with 'click'.
 'href "<link>"' attaches the specified link to the node that was specified by 'click'.
 */
-"href"[\s]+["]          this.begin("href");
+<*>"href"[\s]+["]       this.begin("href");
 <href>["]               this.popState();
 <href>[^"]*             return 'HREF';
 
@@ -89,41 +99,53 @@ the line was introduced with 'click'.
 arguments to the node that was specified by 'click'.
 Function arguments are optional: 'call <callback_name>()' simply executes 'callback_name' without any arguments.
 */
-"call"[\s]+              this.begin("callback_name");
+<*>"call"[\s]+              this.begin("callback_name");
 <callback_name>\([\s]*\) this.popState();
 <callback_name>\(        this.popState(); this.begin("callback_args");
 <callback_name>[^(]*     return 'CALLBACK_NAME';
 <callback_args>\)        this.popState();
 <callback_args>[^)]*     return 'CALLBACK_ARGS';
 
-"_self"               return 'LINK_TARGET';
-"_blank"              return 'LINK_TARGET';
-"_parent"             return 'LINK_TARGET';
-"_top"                return 'LINK_TARGET';
+<generic>[~]            this.popState();
+<generic>[^~]*          return "GENERICTYPE";
+<*>[~]                  this.begin("generic");
 
-\s*\<\|               return 'EXTENSION';
-\s*\|\>               return 'EXTENSION';
-\s*\>                 return 'DEPENDENCY';
-\s*\<                 return 'DEPENDENCY';
-\s*\*                 return 'COMPOSITION';
-\s*o                  return 'AGGREGATION';
-\s*\(\)               return 'LOLLIPOP';
-\-\-                  return 'LINE';
-\.\.                  return 'DOTTED_LINE';
-":"{1}[^:\n;]+        return 'LABEL';
-":"{3}                return 'STYLE_SEPARATOR';
-\-                    return 'MINUS';
-"."                   return 'DOT';
-\+                    return 'PLUS';
-\%                    return 'PCT';
-"="                   return 'EQUALS';
-\=                    return 'EQUALS';
-\w+                   return 'ALPHA';
-"["                   return 'SQS';
-"]"                   return 'SQE';
-[!"#$%&'*+,-.`?\\/]   return 'PUNCTUATION';
-[0-9]+                return 'NUM';
-[\u00AA\u00B5\u00BA\u00C0-\u00D6\u00D8-\u00F6]|
+<string>["]             this.popState();
+<string>[^"]*           return "STR";
+<*>["]                  this.begin("string");
+
+<bqstring>[`]           this.popState();
+<bqstring>[^`]+         return "BQUOTE_STR";
+<*>[`]                  this.begin("bqstring");
+
+<*>"_self"              return 'LINK_TARGET';
+<*>"_blank"             return 'LINK_TARGET';
+<*>"_parent"            return 'LINK_TARGET';
+<*>"_top"               return 'LINK_TARGET';
+
+<*>\s*\<\|              return 'EXTENSION';
+<*>\s*\|\>              return 'EXTENSION';
+<*>\s*\>                return 'DEPENDENCY';
+<*>\s*\<                return 'DEPENDENCY';
+<*>\s*\*                return 'COMPOSITION';
+<*>\s*o                 return 'AGGREGATION';
+<*>\s*\(\)              return 'LOLLIPOP';
+<*>\-\-                 return 'LINE';
+<*>\.\.                 return 'DOTTED_LINE';
+<*>":"{1}[^:\n;]+       return 'LABEL';
+<*>":"{3}               return 'STYLE_SEPARATOR';
+<*>\-                   return 'MINUS';
+<*>"."                  return 'DOT';
+<*>\+                   return 'PLUS';
+<*>\%                   return 'PCT';
+<*>"="                  return 'EQUALS';
+<*>\=                   return 'EQUALS';
+<*>\w+                  return 'ALPHA';
+<*>"["                  return 'SQS';
+<*>"]"                  return 'SQE';
+<*>[!"#$%&'*+,-.`?\\/]  return 'PUNCTUATION';
+<*>[0-9]+               return 'NUM';
+<*>[\u00AA\u00B5\u00BA\u00C0-\u00D6\u00D8-\u00F6]|
 [\u00F8-\u02C1\u02C6-\u02D1\u02E0-\u02E4\u02EC\u02EE\u0370-\u0374\u0376\u0377]|
 [\u037A-\u037D\u0386\u0388-\u038A\u038C\u038E-\u03A1\u03A3-\u03F5]|
 [\u03F7-\u0481\u048A-\u0527\u0531-\u0556\u0559\u0561-\u0587\u05D0-\u05EA]|
@@ -184,9 +206,9 @@ Function arguments are optional: 'call <callback_name>()' simply executes 'callb
 [\uFD50-\uFD8F\uFD92-\uFDC7\uFDF0-\uFDFB\uFE70-\uFE74\uFE76-\uFEFC]|
 [\uFF21-\uFF3A\uFF41-\uFF5A\uFF66-\uFFBE\uFFC2-\uFFC7\uFFCA-\uFFCF]|
 [\uFFD2-\uFFD7\uFFDA-\uFFDC]
-                      return 'UNICODE_TEXT';
-\s                    return 'SPACE';
-<<EOF>>               return 'EOF';
+                        return 'UNICODE_TEXT';
+<*>\s                   return 'SPACE';
+<*><<EOF>>              return 'EOF';
 
 /lex
 
@@ -254,6 +276,11 @@ classLabel
     : SQS STR SQE { $$=$2; }
     ;
 
+namespaceName
+    : alphaNumToken { $$=$1; }
+    | alphaNumToken namespaceName { $$=$1+$2; }
+    ;
+
 className
     : alphaNumToken { $$=$1; }
     | classLiteralName { $$=$1; }
@@ -265,6 +292,7 @@ className
 statement
     : relationStatement       { yy.addRelation($1); }
     | relationStatement LABEL { $1.title =  yy.cleanupLabel($2); yy.addRelation($1);        }
+    | namespaceStatement
     | classStatement
     | methodStatement
     | annotationStatement
@@ -277,6 +305,21 @@ statement
     | acc_descr_multiline_value  { $$=$1.trim();yy.setAccDescription($$); }
     ;
 
+namespaceStatement
+    : namespaceIdentifier STRUCT_START classStatements STRUCT_STOP          {yy.addClassesToNamespace($1, $3);}
+    | namespaceIdentifier STRUCT_START NEWLINE classStatements STRUCT_STOP  {yy.addClassesToNamespace($1, $4);}
+    ;
+
+namespaceIdentifier
+    : NAMESPACE namespaceName   {$$=$2; yy.addNamespace($2);}
+    ;
+
+classStatements
+    : classStatement                            {$$=[$1]}
+    | classStatement NEWLINE                    {$$=[$1]}
+    | classStatement NEWLINE classStatements    {$3.unshift($1); $$=$3}
+    ;
+
 classStatement
     : classIdentifier                                    
     | classIdentifier STYLE_SEPARATOR alphaNumToken      {yy.setCssClass($1, $3);}
diff --git a/packages/mermaid/src/docs/syntax/classDiagram.md b/packages/mermaid/src/docs/syntax/classDiagram.md
index 871ade057..c09c66abb 100644
--- a/packages/mermaid/src/docs/syntax/classDiagram.md
+++ b/packages/mermaid/src/docs/syntax/classDiagram.md
@@ -277,6 +277,23 @@ And `Link` can be one of:
 | --   | Solid       |
 | ..   | Dashed      |
 
+## Define Namespace
+
+A namespace groups classes.
+
+Code:
+
+```mermaid-example
+classDiagram
+namespace BaseShapes {
+    class Triangle
+    class Rectangle {
+      double width
+      double height
+    }
+}
+```
+
 ## Cardinality / Multiplicity on relations
 
 Multiplicity or cardinality in class diagrams indicates the number of instances of one class that can be linked to an instance of the other class. For example, each company will have one or more employees (not zero), and each employee currently works for zero or one companies.