Terminal
Terminal/Skill
Understand and create controllers in Umbraco backoffice (foundational concept)
By Umbraco
Works with
npx skills add umbraco/umbraco-cms-backoffice-skills --skill umbraco-controllersControllers are separate classes that contain or reuse logic across elements while maintaining connection to an element's lifecycle. A Controller is assigned to a Host Element and supports lifecycle methods (hostConnected, hostDisconnected, destroy) for managing side effects, timers, subscriptions, and cleanup. Controllers can host other controllers, enabling composition and reuse of functionality.
Always fetch the latest docs before implementing:
import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
export class MyController extends UmbControllerBase {
constructor(host: UmbControllerHost) {
super(host);
// Auto-registers with host
}
override hostConnected() {
super.hostConnected();
console.log('Controller connected!');
}
override hostDisconnected() {
super.hostDisconnected();
console.log('Controller disconnected!');
}
override destroy() {
super.destroy();
console.log('Controller destroyed!');
}
}
import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
export class TimerController extends UmbControllerBase {
#timer?: number;
#secondsAlive = 0;
constructor(host: UmbControllerHost) {
super(host);
}
override hostConnected() {
super.hostConnected();
// Start timer when element connects to DOM
this.#timer = window.setInterval(this.#onInterval, 1000);
}
override hostDisconnected() {
super.hostDisconnected();
// Clean up timer when element disconnects
if (this.#timer) {
clearInterval(this.#timer);
}
}
#onInterval = () => {
this.#secondsAlive++;
console.log(`Controller active for ${this.#secondsAlive} seconds`);
};
override destroy() {
super.destroy();
if (this.#timer) {
clearInterval(this.#timer);
}
}
getSecondsAlive(): number {
return this.#secondsAlive;
}
}
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { TimerController } from './timer-controller.js';
export class MyElement extends UmbLitElement {
#timerController = new TimerController(this);
render() {
return html`
<div>
Active for: ${this.#timerController.getSecondsAlive()}s
</div>
`;
}
}
export class MyManualController {
#host: UmbControllerHost;
constructor(host: UmbControllerHost) {
this.#host = host;
// Manual registration required
this.#host.addUmbController(this);
}
hostConnected() {
console.log('Connected');
}
destroy() {
// Manual deregistration required
this.#host.removeUmbController(this);
}
}
import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';
export class NotificationController extends UmbControllerBase {
async showSuccess(message: string) {
// Controllers can access contexts via getContext
const context = await this.getContext(UMB_NOTIFICATION_CONTEXT);
context?.peek('positive', { data: { message } });
}
}
Host Element: Web component that hosts the controller (all Umbraco Elements can be hosts)
Lifecycle Methods:
hostConnected() - Called when host element connects to DOMhostDisconnected() - Called when host element disconnects from DOMdestroy() - Called when controller is permanently destroyedAuto-Registration: Extending UmbControllerBase automatically registers/deregisters
Controller Composition: Controllers can host other controllers
Context Access: Controllers can consume contexts via getContext() and consumeContext()
Use Cases:
API Calls: When making API calls from controllers, NEVER use raw fetch(). Always use a generated OpenAPI client configured with Umbraco's auth context. See the umbraco-openapi-client skill for setup.
That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.