Header Apps

Example how to work with extension registry

This page is a work in progress. It will be updated as the software evolves.

A header app appears next to the user profile and global search icon on the top-right corner of Umbraco's backoffice.

In this article, you can find an example of an extension registry. This example goes through the creation of a Header App in two ways just as the extension registry can be done as well:

1. Using a manifest file.

2. Using the javascript/typescript file.

Header Apps

Button Header App with Manifest

Below you can find an example of how to setup a Header App using the manifest file.

1. Follow the Vite Package Setup by creating a new project folder called "header-app" in App_Plugins.

2. Create a manifest file named umbraco-package.json at the root of the welcome-dashboard folder. Here we define and configure our dashboard.

3. Add the following code to umbraco-package.json:

umbraco-package.json

{
  "$schema": "../../umbraco-package-schema.json",
  "name": "My Header App",
  "version": "0.1.0",
  "extensions": [
    {
      "type": "headerApp",
      "alias": "My.HeaderApp",
      "name": "My Header App",
      "kind": "button",

      "meta": {
        "label": "Hello Umbraco",
        "icon": "icon-hearts",
        "href": "https://umbraco.com/"
      }
    }
  ]
}

• First we define the type which is a headerApp. Then we add a unique alias and a name to define the extension UI.

• Then we can define what kind of extension it is, where in this case we can use a pre-defined element called button.

• The button requires some metdata: an icon, label of the button (name of the button) and a link which opens once clicked.

4. In the header-app folder run npm run build and then run the project. Then in the backoffice you will see our new Header App extension with heart icon:

Header App in the Backoffice registered via Manifest File

Button Header App with JS/TS

Below you can find an example of how to setup a Header App using the ts file.

This is a continuation of the above steps from Button Header App with Manifest example as we will register a new Header App directly from the .ts file.

1. Add a reference to the .js file. Update the umbraco-package.json with the following:

umbraco-package.json

{
  "$schema": "../../umbraco-package-schema.json",
  "name": "My Header App",
  "version": "0.1.0",
  "extensions": [
    {
      "type": "headerApp",
      "alias": "My.HeaderApp",
      "name": "My Header App",
      "kind": "button",
      "js": "/App_Plugins/header-app/dist/header-app.js",
      "meta": {
        "label": "Hello Umbraco",
        "icon": "icon-hearts",
        "href": "https://umbraco.com/"
      }
    }
  ]
}

2. Replace the content of the src/my-element.ts file with the following:

my-element.ts

import { ManifestHeaderAppButtonKind, umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';

const manifest: ManifestHeaderAppButtonKind = {
  type: "headerApp",
  alias: "My.HeaderApp.Documentation",
  name: "My Header App Documentation",
  kind: "button",
  meta: {
    label: "Hello Documentation",
    icon: "icon-addressbook",
    href: "https://docs.umbraco.com/"
  }
};

umbExtensionsRegistry.register(manifest);

3. In the header-app folder run npm run build and then run the project. Then in the backoffice you will see our new Header App extension with address book icon:

Header App in Backoffice registered via ts File