diff --git a/src/Umbraco.Web.UI.Client/libs/modal/stories/modal.mdx b/src/Umbraco.Web.UI.Client/libs/modal/stories/modal.mdx
index fa40855dc5..ed0aae3113 100644
--- a/src/Umbraco.Web.UI.Client/libs/modal/stories/modal.mdx
+++ b/src/Umbraco.Web.UI.Client/libs/modal/stories/modal.mdx
@@ -23,10 +23,11 @@ A modal is a popup that darkens the background and has focus lock. There are two
 The UmbModal context can be used to open modals.
 
 ```ts
-import { html, LitElement } from 'lit';
-import { UmbLitElement } from '@umbraco-cms/element';
+import { LitElement } from 'lit';
+import { UmbElementMixin } from '@umbraco-cms/element';
 import { UmbModalContext, UMB_MODAL_CONTEXT_ALIAS } from '@umbraco-cms/modal';
-class MyElement extends UmbLitElement {
+
+class MyElement extends UmbElementMixin(LitElement) {
 	#modalContext?: UmbModalContext;
 
 	constructor() {
@@ -41,13 +42,13 @@ class MyElement extends UmbLitElement {
 
 ### Open a modal
 
-A modal is opened by calling one of the helper methods on the UmbModalContext. The methods will accept an element template and modal options and return an instance of UmbModalHandler.
+A modal is opened by calling the open method on the UmbModalContext. The methods will accept a modal token (or extension alias), an optional dataset, and optional modal options .It returns an instance of UmbModalHandler.
 
 ```ts
 import { html, LitElement } from 'lit';
-import { UmbLitElement } from '@umbraco-cms/element';
-import { UmbModalContext, UMB_MODAL_CONTEXT_ALIAS } from './core/services/modal';
-class MyElement extends UmbLitElement {
+import { UmbElementMixin } from '@umbraco-cms/element';
+import { UmbModalContext, UMB_MODAL_CONTEXT_ALIAS } from '@umbraco-cms/modal';
+class MyElement extends UmbElementMixin(LitElement) {
 	#modalContext?: UmbModalContext;
 
 	constructor() {
@@ -59,9 +60,11 @@ class MyElement extends UmbLitElement {
 	}
 
 	#onClick() {
-		const options = {'options goes here'}
-		const modalHandler = this.#modalContext?.openDialog('my-dialog'), options);
-		modalHandler.onClose().then((data) => {
+		const data = {'data goes here'};
+		const options {'options go here'};
+		const modalHandler = this.#modalContext?.open(SOME_MODAL_TOKEN), data, options);
+
+		modalHandler?.onClose().then((data) => {
 			// if any data is supplied on close, it will be available here.
 		});
 	}
@@ -72,13 +75,45 @@ class MyElement extends UmbLitElement {
 }
 ```
 
-The dialog template to open:
+## Create a custom modal
+
+### Register in the extension registry
+
+The manifest
+
+```json
+{
+	"type": "modal",
+	"alias": "My.Modal",
+	"name": "My Modal",
+	"js": "../path/to/my-modal.element.js"
+}
+```
+
+### Create a modal token
+
+A modal token is a string that identifies a modal. It should be the modal extension alias. It is used to open a modal and is also to set default options for the modal.
+
+```ts
+interface MyModalData = {
+	headline: string;
+	content: string;
+}
+
+const MY_MODAL_TOKEN = new ModalToken<MyModalData>('My.Modal', {
+	type: 'sidebar',
+	size: 'small'
+});
+```
+
+The Modal element
 
 ```ts
 import { html, LitElement } from 'lit';
-import type { UmbModalHandler } from './core/services/modal';
+import { UmbElementMixin } from '@umbraco-cms/element';
+import type { UmbModalHandler } from '@umbraco-cms/modal';
 
-class MyDialog extends LitElement {
+class MyDialog extends UmbElementMixin(LitElement) {
 	// the modal handler will be injected into the element when the modal is opened.
 	@property({ attribute: false })
 	modalHandler?: UmbModalHandler;
@@ -92,7 +127,7 @@ class MyDialog extends LitElement {
 	render() {
 		return html`
 			<div>
-				<h1>My Dialog</h1>
+				<h1>My Modal</h1>
 				<button @click=${this._handleClose}>Close</button>
 			</div>
 		`;