From 0fe909d42e187057f4cbe12bb5f5b1a4644c50ae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Niels=20Lyngs=C3=B8?= <nsl@umbraco.dk>
Date: Mon, 20 Mar 2023 13:43:05 +0100
Subject: [PATCH] docs

---
 .../src/stories/extending/registration.mdx    | 61 +++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/src/Umbraco.Web.UI.Client/src/stories/extending/registration.mdx b/src/Umbraco.Web.UI.Client/src/stories/extending/registration.mdx
index 2366eecb43..1b1bc32b16 100644
--- a/src/Umbraco.Web.UI.Client/src/stories/extending/registration.mdx
+++ b/src/Umbraco.Web.UI.Client/src/stories/extending/registration.mdx
@@ -62,6 +62,67 @@ const manifest = {
 extensionRegistry.register(extension);
 ```
 
+## Using Kinds for registration
+
+Generally UI extensions, requires you to bring everything for the extension.
+But there are several situations where you dont want to bring the full solution, just some configuration.
+
+In this case we can use Extension 'Kinds'. Kinds enables you to extend a base configuration and make it your own.
+
+To understand the concept of Kinds, lets look at the Header App extension type:
+
+```ts
+import { extensionRegistry } from '@umbraco-cms/extension-registry';
+
+const manifest = {
+	type: 'headerApp',
+	kind: 'button',
+	name: 'My Header App Example',
+	alias: 'My.HeaderApp.Example',
+	meta: {
+		label: 'My Example',
+		icon: 'umb:home',
+		href: '/some/path/to/open/when/clicked',
+	},
+};
+
+extensionRegistry.register(extension);
+```
+
+The above example does not provide a element, but is still visually present through a button element.
+The this element comes from the kind 'button'.
+
+Backoffice comes with a set of predefined Kinds, and you can even create your own.
+
+Many of the build-in Kinds comes with a default element, but it could be anything. To understand the abilities we can look closer at the registration of your own Kinds.
+
+## Registering a kind
+
+The registration of Kinds, is done in the same maner as the registration of other extensions.
+But the format of it is quite different, lets look at the Kind registration of the Header App Button Kind (The kind used in the above example):
+
+```ts
+import { extensionRegistry } from '@umbraco-cms/extension-registry';
+
+const manifest: ManifestKind = {
+	type: 'kind',
+	alias: 'Umb.Kind.Button',
+	matchKind: 'button',
+	matchType: 'headerApp',
+	manifest: {
+		elementName: 'umb-header-app-button',
+	},
+};
+
+umbExtensionsRegistry.register(manifest);
+```
+
+The root properties of this object, defines the Kind registration.
+And then the manifest property holds the base extension manifest that users of this Kind will be extending.
+This object can hold the property values that makes sense for the Kind.
+
+In the above example the only property value defined a elementName, which is enough to create the button element for all extensions using this Kind.
+
 ### JSON Manifest files
 
 TODO: describe how and where to position the JSON manifest files