Terminal
Terminal/Skill
Understand and use Context API in Umbraco backoffice (foundational concept)
By Umbraco
Works with
npx skills add umbraco/umbraco-cms-backoffice-skills --skill umbraco-context-apiThe Context API is Umbraco's communication system that enables extensions to share data and functionality through the component hierarchy without tight coupling. It uses a provider-consumer pattern where parent elements provide contexts that descendant components can access. Contexts cascade down through the DOM tree and use tokens for type-safe access to services like notifications, workspaces, and user information.
Always fetch the latest docs before implementing:
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';
export class MyElement extends UmbLitElement {
#notificationContext?: typeof UMB_NOTIFICATION_CONTEXT.TYPE;
constructor() {
super();
// Subscribe to context - callback runs when context is available
this.consumeContext(UMB_NOTIFICATION_CONTEXT, (context) => {
this.#notificationContext = context;
});
}
showMessage() {
this.#notificationContext?.peek('positive', {
data: { message: 'Hello from Context API!' }
});
}
}
import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';
export class MyService extends UmbControllerBase {
async showNotification(text: string) {
// Get context once, use it, then release
const context = await this.getContext(UMB_NOTIFICATION_CONTEXT);
context?.peek('positive', { data: { message: text } });
}
}
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { UmbContextToken } from '@umbraco-cms/backoffice/context-api';
// Define a context token
export const MY_CUSTOM_CONTEXT = new UmbContextToken<MyCustomContext>(
'MyCustomContext'
);
export class MyCustomContext {
getData() {
return { message: 'Hello from custom context!' };
}
}
export class MyProviderElement extends UmbLitElement {
constructor() {
super();
// Provide context to all descendants
this.provideContext(MY_CUSTOM_CONTEXT, new MyCustomContext());
}
}
// Notifications
import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';
// Current User
import { UMB_CURRENT_USER_CONTEXT } from '@umbraco-cms/backoffice/current-user';
// Modal Manager
import { UMB_MODAL_MANAGER_CONTEXT } from '@umbraco-cms/backoffice/modal';
// Workspace (varies by type)
import { UMB_DOCUMENT_WORKSPACE_CONTEXT } from '@umbraco-cms/backoffice/document';
// Block Entry (for block editors)
import { UMB_BLOCK_ENTRY_CONTEXT } from '@umbraco-cms/backoffice/block';
// Property Dataset (for property editors)
import { UMB_PROPERTY_DATASET_CONTEXT } from '@umbraco-cms/backoffice/property';
Context Token: Type-safe identifier for a context
const MY_TOKEN = new UmbContextToken<MyType>('UniqueName');
Provider: Element that provides context to descendants via provideContext()
Consumer: Element that accesses context via consumeContext() or getContext()
Subscription vs One-time:
consumeContext() when you need the context during initializationgetContext() for actions triggered by user interactionHierarchy: Contexts flow DOWN the DOM tree from provider to consumers
That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.