From fd5077d82300fa3f60147a7b7bfdfa75650d1fc5 Mon Sep 17 00:00:00 2001
From: Mads Rasmussen <madsr@hey.com>
Date: Mon, 24 Nov 2025 17:32:53 +0100
Subject: [PATCH] Example Docs: Add menu item examples (#20910)

Add menu item registration examples

Introduces example implementations for registering action, link, and entity menu items in the backoffice. Includes manifests and API to demonstrate how to extend the menu system.
---
 .../examples/menu-item/README.md                |  9 +++++++++
 .../menu-item/action/action-menu-item.api.ts    | 17 +++++++++++++++++
 .../examples/menu-item/action/manifests.ts      | 16 ++++++++++++++++
 .../examples/menu-item/entity/manifests.ts      | 15 +++++++++++++++
 .../examples/menu-item/index.ts                 |  5 +++++
 .../examples/menu-item/link/manifests.ts        | 16 ++++++++++++++++
 .../examples/menu-item/tree/README.md           |  3 +++
 7 files changed, 81 insertions(+)
 create mode 100644 src/Umbraco.Web.UI.Client/examples/menu-item/README.md
 create mode 100644 src/Umbraco.Web.UI.Client/examples/menu-item/action/action-menu-item.api.ts
 create mode 100644 src/Umbraco.Web.UI.Client/examples/menu-item/action/manifests.ts
 create mode 100644 src/Umbraco.Web.UI.Client/examples/menu-item/entity/manifests.ts
 create mode 100644 src/Umbraco.Web.UI.Client/examples/menu-item/index.ts
 create mode 100644 src/Umbraco.Web.UI.Client/examples/menu-item/link/manifests.ts
 create mode 100644 src/Umbraco.Web.UI.Client/examples/menu-item/tree/README.md

diff --git a/src/Umbraco.Web.UI.Client/examples/menu-item/README.md b/src/Umbraco.Web.UI.Client/examples/menu-item/README.md
new file mode 100644
index 0000000000..238df9b497
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/examples/menu-item/README.md
@@ -0,0 +1,9 @@
+# Menu Item Example
+
+This example demonstrates how to register a Menu Item.
+
+The example includes:
+
+- Action Menu Item Registration
+- Link Menu Item Registration
+- Entity Menu Item Registration
diff --git a/src/Umbraco.Web.UI.Client/examples/menu-item/action/action-menu-item.api.ts b/src/Umbraco.Web.UI.Client/examples/menu-item/action/action-menu-item.api.ts
new file mode 100644
index 0000000000..53b68bacf2
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/examples/menu-item/action/action-menu-item.api.ts
@@ -0,0 +1,17 @@
+import { UmbMenuItemActionApiBase } from '@umbraco-cms/backoffice/menu';
+
+/**
+ * Example menu item action API
+ * This action will log "Hello world" to the console when executed.
+ */
+export class ExampleActionMenuItemApi extends UmbMenuItemActionApiBase<never> {
+	/**
+	 * This method is executed when the menu item is clicked
+	 */
+	override async execute() {
+		console.log('Hello world');
+	}
+}
+
+// Declare an `api` export so the Extension Registry can initialize this class
+export { ExampleActionMenuItemApi as api };
diff --git a/src/Umbraco.Web.UI.Client/examples/menu-item/action/manifests.ts b/src/Umbraco.Web.UI.Client/examples/menu-item/action/manifests.ts
new file mode 100644
index 0000000000..a3ccfc45c6
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/examples/menu-item/action/manifests.ts
@@ -0,0 +1,16 @@
+import { UMB_CONTENT_MENU_ALIAS } from '@umbraco-cms/backoffice/document';
+
+export const manifests: Array<UmbExtensionManifest> = [
+	{
+		type: 'menuItem',
+		kind: 'action',
+		alias: 'Example.MenuItem.Action',
+		name: 'Example Action Menu Item',
+		api: () => import('./action-menu-item.api.js'),
+		meta: {
+			label: 'Example Action Menu Item',
+			icon: 'icon-hammer',
+			menus: [UMB_CONTENT_MENU_ALIAS],
+		},
+	},
+];
diff --git a/src/Umbraco.Web.UI.Client/examples/menu-item/entity/manifests.ts b/src/Umbraco.Web.UI.Client/examples/menu-item/entity/manifests.ts
new file mode 100644
index 0000000000..a5b3ef0ea8
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/examples/menu-item/entity/manifests.ts
@@ -0,0 +1,15 @@
+import { UMB_CONTENT_MENU_ALIAS } from '@umbraco-cms/backoffice/document';
+
+export const manifests: Array<UmbExtensionManifest> = [
+	{
+		type: 'menuItem',
+		alias: 'Example.MenuItem.Entity',
+		name: 'Example Entity Menu Item',
+		meta: {
+			label: 'Example Entity Menu Item',
+			icon: 'icon-wand',
+			entityType: 'example-entity-type',
+			menus: [UMB_CONTENT_MENU_ALIAS],
+		},
+	},
+];
diff --git a/src/Umbraco.Web.UI.Client/examples/menu-item/index.ts b/src/Umbraco.Web.UI.Client/examples/menu-item/index.ts
new file mode 100644
index 0000000000..10a5c8d895
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/examples/menu-item/index.ts
@@ -0,0 +1,5 @@
+import { manifests as actionManifests } from './action/manifests.js';
+import { manifests as entityManifests } from './entity/manifests.js';
+import { manifests as linkManifests } from './link/manifests.js';
+
+export const manifests = [...actionManifests, ...entityManifests, ...linkManifests];
diff --git a/src/Umbraco.Web.UI.Client/examples/menu-item/link/manifests.ts b/src/Umbraco.Web.UI.Client/examples/menu-item/link/manifests.ts
new file mode 100644
index 0000000000..6680fba219
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/examples/menu-item/link/manifests.ts
@@ -0,0 +1,16 @@
+import { UMB_CONTENT_MENU_ALIAS } from '@umbraco-cms/backoffice/document';
+
+export const manifests: Array<UmbExtensionManifest> = [
+	{
+		type: 'menuItem',
+		kind: 'link',
+		alias: 'Example.MenuItem.ExternalLink',
+		name: 'Example External Link Menu Item',
+		meta: {
+			label: 'Example Link Menu Item',
+			icon: 'icon-link',
+			href: 'https://',
+			menus: [UMB_CONTENT_MENU_ALIAS],
+		},
+	},
+];
diff --git a/src/Umbraco.Web.UI.Client/examples/menu-item/tree/README.md b/src/Umbraco.Web.UI.Client/examples/menu-item/tree/README.md
new file mode 100644
index 0000000000..dd2c82da77
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/examples/menu-item/tree/README.md
@@ -0,0 +1,3 @@
+#Tree Menu Item
+
+See the Tree Example of how to register a tree and use it as a menu item in the sidebar.