Creating a Custom Dashboard
A guide to creating a custom dashboard in Umbraco
This page is a work in progress. It will be updated as the software evolves.
This guide takes you through the steps to set up a Custom Dashboard in Umbraco.
The guide is divided into four parts. The first part will go through the following:
A Dashboard is a tab on the right-hand side of a section eg. the Getting Started dashboard in the Content section:
%20(1)%20(1).jpg?alt=media)
Welcome dashboard
It is generally considered good practice to provide a custom dashboard to welcome your editors to the backoffice of your site. You can provide information about the site and/or provide a helpful gateway to common functionality the editors will use. This guide will show the basics of creating a custom 'Welcome Message' dashboard. The guide will also show how you can go a little further to provide interaction using Lit and Typescript.
The finished dashboard will give the editors an overview of which pages and media files they've worked on most recently.
Here's an overview of the steps that will be covered:
- Setting up the dashboard plugin
- Writing a basic Welcome Message view
- Configure the Custom Welcome Dashboard to be displayed
- Adding translations
- Adding styles
- Adding interactive functionality with Lit and Typescript
- Display the current user's name in our welcome message
- Display the most recent log viewer items
- You can do anything...
This tutorial uses Typescript and Lit with Umbraco, so it does not cover Typescript or Lit. It is expected that your package is already set up to use Typescript and Lit. To read about setting up an extension in Umbraco using Typescript and Lit, please read the article Creating your first extension.
For resources on Typescript or Lit, you can find some here:
There are a lot of parallels with Creating a Property Editor. The tutorial 'Creating a Property Editor Tutorial' is worth a read too.
At the end of this guide, we should have a friendly welcoming dashboard displaying a list of the most recent site logs.
Assuming you have read the tutorial Creating your first extension, you should have a folder named App_Plugins in your project. Let's call our project WelcomeDashboard. Start by creating a folder in App_Plugins called
WelcomeDashboard
.Create the manifest file
umbraco-package.json
at the root of the folder WelcomeDashboard
. Here we define and configure our dashboard.Add the following code:
umbraco-package.json
1
{
2
"$schema": "../../umbraco-package-schema.json",
3
"name": "My.WelcomePackage",
4
"version": "0.1.0",
5
"extensions": [
6
{
7
"type": "dashboard",
8
"alias": "my.welcome.dashboard",
9
"name": "My Welcome Dashboard",
10
"js": "/App_Plugins/WelcomeDashboard/dashboard.js",
11
"elementName": "my-welcome-dashboard",
12
"weight": -1,
13
"meta": {
14
"label": "Welcome Dashboard",
15
"pathname": "welcome-dashboard"
16
},
17
"conditions": [
18
{
19
"alias": "Umb.Condition.SectionAlias",
20
"match": "Umb.Section.Content"
21
}
22
]
23
}
24
]
25
}
Notice that the file for our dashboard extension is in the root of our WelcomeDashboard folder and is called
dashboard.js
with the element name my-welcome-dashboard
.For more information about the
umbraco-package.json
file, read the article Package Manifest. You should also read the Dashboards article for more information about dashboard configurations.Please be aware that the file
umbraco-package.json
is loaded into memory when Umbraco starts up. If you are changing or adding new configurations you will need to start and stop your application for it to be loaded.Next, let's create a new ts file called
welcome-dashboard.element.ts
. This file is our web component and will contain all our HTML, CSS, and logic.Let's start with setting the web component with some HTML and CSS:
welcome-dashboard.element.ts
1
import { LitElement, css, html } from "lit";
2
import { customElement } from "@umbraco-cms/backoffice/external/lit";
3
import { UmbElementMixin } from "@umbraco-cms/backoffice/element-api";
4
5
@customElement("my-welcome-dashboard")
6
export class MyWelcomeDashboardElement extends UmbElementMixin(LitElement) {
7
8
render() {
9
return html`
10
<h1>Welcome Dashboard</h1>
11
<div>
12
<p>
13
This is the Backoffice. From here, you can modify the content,
14
media, and settings of your website.
15
</p>
16
<p>© Sample Company 20XX</p>
17
</div>
18
`;
19
}
20
21
static styles = [
22
css`
23
:host {
24
display: block;
25
padding: 24px;
26
}
27
`,
28
];
29
}
30
31
declare global {
32
interface HTMLElementTagNameMap {
33
"my-welcome-dashboard": MyWelcomeDashboardElement;
34
}
35
}
Build the
ts
file and make sure to copy the output file to dashboard.js
under /App_Plugins/WelcomeDashboard/
.You can now start up the Backoffice and see our new dashboard in the content section:

First look of the dashboard
With all the steps completed, you should have a dashboard welcoming your users to the Backoffice.
In the next part, we will look into how to add localization to the dashboard using our own custom translations.