Umbraco Controllers What is it? Controllers 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. Documentation Always fetch the latest docs before implementing: Main docs : https://docs.umbraco.com/umbraco-cms/customizing/foundation/umbraco-controller Write Custom Controller : https://docs.umbraco.com/umbraco-cms/customizing/foundation/umbraco-controller/write-your-own-controller Foundation : https://docs.umbraco.com/umbraco-cms/customizing/foundation Workflow Fetch docs - Use WebFetch on the URLs above Ask questions - Need custom controller? What lifecycle events? What cleanup needed? Generate code - Implement controller extending UmbControllerBase based on latest docs Explain - Show what was created and how to host it Minimal Examples Basic Custom Controller 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!' ) ; } } Timer Controller Example 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

; } } Hosting a Controller in Element 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 `

` ; } } Manual Registration (Not Recommended) 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

)

;

}

}

Controller with Context Access

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

}

}

)

;

}

}

Key Concepts

Host Element

Web component that hosts the controller (all Umbraco Elements can be hosts)

Lifecycle Methods

:

hostConnected()

- Called when host element connects to DOM

hostDisconnected()

- Called when host element disconnects from DOM

destroy()

- Called when controller is permanently destroyed

Auto-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

:

Managing subscriptions and cleanup

Handling timers and intervals

Coordinating side effects

Reusing logic across multiple elements

Managing API calls and data fetching

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.