diff --git a/src/Umbraco.Web.UI.Client/src/stories/modal-service.mdx b/src/Umbraco.Web.UI.Client/src/stories/modal-service.mdx
index e031df1869..c31456d767 100644
--- a/src/Umbraco.Web.UI.Client/src/stories/modal-service.mdx
+++ b/src/Umbraco.Web.UI.Client/src/stories/modal-service.mdx
@@ -1,12 +1,22 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="API/Modals/Intro" />
+
 # Modals
 
-A modal is a popup that darkens the background and has focus lock.
+A modal is a popup that darkens the background and has focus lock. There are two types of modals: "dialog" and "sidebar".
 
-**Dialog modals**
-Appears in the middle of the screen.
+**Dialog modals** appears in the middle of the screen.
+| option | values |
+|:------:|:--------------------------:|
+| No options yet | |
 
-**Sidebar modals**
-Slides in from the right.
+<br>
+
+**Sidebar modals** slides in from the right.
+| option | values |
+|:------:|:--------------------------:|
+| size | small, medium, large, full |
 
 ## Basic Usage
 
@@ -17,7 +27,7 @@ The UmbModal service can be used to open modals.
 ```ts
 import { html, LitElement } from 'lit';
 import { UmbContextConsumerMixin } from './core/context';
-import { UmbModalService } from './core/services/modal.service';
+import type { UmbModalService } from './core/services/modal.service';
 class MyElement extends UmbContextConsumerMixin(LitElement) {
 	private _modalService_?: UmbModalService;
 	constructor() {
@@ -29,3 +39,60 @@ class MyElement extends UmbContextConsumerMixin(LitElement) {
 	}
 }
 ```
+
+### Open a modal
+
+A modal is opened by calling one of the helper methods on the UmbModalService. The methods will accept an element template and modal options and return an instance of UmbModalHandler.
+
+```ts
+import { html, LitElement } from 'lit';
+import { UmbContextConsumerMixin } from './core/context';
+import type { UmbModalService } from './core/services/modal';
+class MyElement extends UmbContextConsumerMixin(LitElement) {
+	private _modalService?: UmbModalService;
+	constructor() {
+		super();
+		this.consumeContext('umbModalService', (modalService) => {
+			this._modalService = modalService.;
+			// modalService is now ready to be used
+		});
+	}
+	private _handleClick() {
+		const options = {'options goes here'}
+		const modalHandler = this._modalService?.openDialog('my-dialog'), options);
+		modalHandler.onClose.then((data) => {
+			// if any data is supplied on close, it will be available here.
+		});
+	}
+	render() {
+		return html`<button @click=${this._handleClick}>Open modal</button>`;
+	}
+}
+```
+
+The dialog template to open:
+
+```ts
+import { html, LitElement } from 'lit';
+import type { UmbModalHandler } from './core/services/modal';
+class MyDialog extends LitElement {
+	// the modal handler will be injected into the element when the modal is opened.
+	@property({ attribute: false })
+	modalHandler?: UmbModalHandler;
+
+	private _handleClose() {
+		/* Optional data of any type can be applied to the close method to pass it
+		   to the modal parent through the onClose promise. */
+		this._modalHandler?.close('optional data');
+	}
+
+	render() {
+		return html`
+			<div>
+				<h1>My Dialog</h1>
+				<button @click=${this._handleClose}>Close</button>
+			</div>
+		`;
+	}
+}
+```
diff --git a/src/Umbraco.Web.UI.Client/src/stories/modal-service.stories.ts b/src/Umbraco.Web.UI.Client/src/stories/modal-service.stories.ts
index 4919fb86af..fae53c88f4 100644
--- a/src/Umbraco.Web.UI.Client/src/stories/modal-service.stories.ts
+++ b/src/Umbraco.Web.UI.Client/src/stories/modal-service.stories.ts
@@ -11,8 +11,7 @@ import { html } from 'lit-html';
 import { customElement, property, state } from 'lit/decorators.js';
 import { UmbContextConsumerMixin } from '../core/context';
 import { LitElement } from 'lit';
-import { UmbModalService } from '../core/services/modal/modal.service';
-import UmbModalHandler from '../core/services/modalHandler';
+import { UmbModalHandler, UmbModalService } from '../core/services/modal';
 
 export default {
 	title: 'API/Modals',