CustomElement API

The CustomElement resource is a fundamental concept in Aurelia 2, providing the core functionality for creating encapsulated and reusable components. This comprehensive guide covers all aspects of the CustomElement API, including methods, decorators, and configuration options.

Core Methods

CustomElement.for

Retrieves the Aurelia controller associated with a DOM node. The controller provides access to the element's view model, lifecycle methods, and other properties.

Method Signatures

// Get controller for the current node
CustomElement.for<T>(node: Node): ICustomElementController<T>

// Get controller with optional flag (returns null if not found)
CustomElement.for<T>(node: Node, opts: { optional: true }): ICustomElementController<T> | null

// Search parent nodes for a controller
CustomElement.for<T>(node: Node, opts: { searchParents: true }): ICustomElementController<T>

// Get controller for a named custom element
CustomElement.for<T>(node: Node, opts: { name: string }): ICustomElementController<T> | undefined

// Get controller for a named custom element, searching parents
CustomElement.for<T>(node: Node, opts: { name: string; searchParents: true }): ICustomElementController<T> | undefined

Parameters

node: Node - The DOM node for which to retrieve the controller
opts?: object - Optional configuration object with the following properties:
- optional?: boolean - If true, returns null instead of throwing when no controller is found
- searchParents?: boolean - If true, searches parent nodes (including containerless elements) for a controller
- name?: string - If provided, only returns controllers for custom elements with this specific name

Examples

import { CustomElement, ILogger } from 'aurelia';

// Basic usage - get controller for current node
const myElement = document.querySelector('.my-custom-element');
try {
  const controller = CustomElement.for(myElement);
  // You can inject ILogger in your classes for proper logging
  this.logger?.info('View model:', controller.viewModel);
  this.logger?.info('Element state:', controller.state);
} catch (error) {
  this.logger?.error('The provided node does not host a custom element.', error);
}

// Safe retrieval without throwing errors
const optionalController = CustomElement.for(myElement, { optional: true });
if (optionalController) {
  // Controller found and available for use
  optionalController.viewModel.someMethod();
} else {
  // No controller found, handle gracefully
  this.logger?.info('Node is not a custom element');
}

// Search parent hierarchy for any custom element controller
const someInnerElement = document.querySelector('.some-inner-element');
const parentController = CustomElement.for(someInnerElement, { searchParents: true });
// parentController is the closest controller up the DOM tree

// Get controller for a specific named custom element
const namedController = CustomElement.for(myElement, { name: 'my-custom-element' });
if (namedController) {
  // Found a controller for the specific element type
} else {
  // The node is not hosting the named custom element type
}

// Search parents for a specific named custom element
const namedParentController = CustomElement.for(someInnerElement, {
  name: 'my-custom-element',
  searchParents: true
});

// Access view model properties and methods
const controller = CustomElement.for(myElement);
const viewModel = controller.viewModel;
viewModel.myProperty = 'new value';
viewModel.myMethod();

// Access lifecycle state
this.logger?.info('Current state:', controller.state);
this.logger?.info('Is activated:', controller.isActive);

CustomElement.define

Registers a class as a custom element in Aurelia. This method can be called directly or is used internally by the @customElement decorator.

Method Signatures

// Define with name and class
CustomElement.define<T>(name: string, Type: Constructable<T>): CustomElementType<T>

// Define with definition object and class
CustomElement.define<T>(def: PartialCustomElementDefinition, Type: Constructable<T>): CustomElementType<T>

// Define with definition object only (generates type)
CustomElement.define<T>(def: PartialCustomElementDefinition): CustomElementType<T>

Parameters

nameOrDef: string | PartialCustomElementDefinition - Either the element name or a complete definition object
Type?: Constructable - The class containing the element's logic (optional when using definition object)

Examples

import { CustomElement } from 'aurelia';

// Basic definition with name and class
class MyCustomElement {
  public message = 'Hello, World!';

  public greet() {
    alert(this.message);
  }
}

CustomElement.define('my-custom-element', MyCustomElement);

// Definition with complete configuration object
const definition = {
  name: 'advanced-element',
  template: '<h1>${title}</h1><div class="content"><au-slot></au-slot></div>',
  bindables: ['title', 'size'],
  shadowOptions: { mode: 'open' },
  containerless: false,
  capture: true,
  dependencies: []
};

class AdvancedElement {
  public title = '';
  public size = 'medium';
}

CustomElement.define(definition, AdvancedElement);

// Definition without explicit type (generates anonymous class)
const simpleDefinition = {
  name: 'simple-element',
  template: '<p>${text}</p>',
  bindables: ['text']
};

const SimpleElementType = CustomElement.define(simpleDefinition);

// Note: Using @customElement decorator is preferred over calling define directly
@customElement('my-element')
class MyElement {
  // This is equivalent to calling CustomElement.define('my-element', MyElement)
}

CustomElement.getDefinition

Retrieves the CustomElementDefinition for a custom element class, providing access to all metadata about the element.

Method Signature

CustomElement.getDefinition<T>(Type: Constructable<T>): CustomElementDefinition<T>

Parameters

Type: Constructable - The custom element class

Return Value

Returns a CustomElementDefinition object containing all metadata about the custom element.

Example

import { CustomElement, ILogger } from 'aurelia';

@customElement({
  name: 'my-element',
  template: '${message}',
  bindables: ['message']
})
class MyElement {
  public message = '';

  constructor(private logger: ILogger) {}

  public logDefinitionInfo() {
    const definition = CustomElement.getDefinition(MyElement);

    this.logger.info('Element name:', definition.name); // 'my-element'
    this.logger.info('Template:', definition.template);
    this.logger.info('Bindables:', definition.bindables);
    this.logger.info('Is containerless:', definition.containerless);
    this.logger.info('Shadow options:', definition.shadowOptions);
    this.logger.info('Dependencies:', definition.dependencies);
    this.logger.info('Aliases:', definition.aliases);
    this.logger.info('Capture mode:', definition.capture);
  }
}

CustomElement.find

Searches for a custom element definition by name within a specific container's registry.

Method Signature

CustomElement.find(container: IContainer, name: string): CustomElementDefinition | null

Parameters

container: IContainer - The dependency injection container to search in
name: string - The name of the custom element to find

Return Value

Returns the CustomElementDefinition if found, or null if no element with the specified name is registered.

Example

import { CustomElement, IContainer, ILogger } from 'aurelia';

// In a custom service or component
class MyService {
  constructor(private container: IContainer, private logger: ILogger) {}

  public checkElementExists(elementName: string): boolean {
    const definition = CustomElement.find(this.container, elementName);
    return definition !== null;
  }

  public getElementTemplate(elementName: string): string | null {
    const definition = CustomElement.find(this.container, elementName);
    return definition?.template as string || null;
  }
}

// Usage in template compiler or dynamic composition
class SomeComponent {
  constructor(private logger: ILogger) {}

  public checkDynamicElement(container: IContainer) {
    const definition = CustomElement.find(container, 'my-dynamic-element');
    if (definition) {
      // Element is registered and available for use
      this.logger.info('Found element:', definition.name);
    } else {
      // Element not found in current container
      this.logger.warn('Element not registered');
    }
  }
}

CustomElement.isType

Checks whether a given value is a custom element type (class decorated with @customElement or defined via CustomElement.define).

Method Signature

CustomElement.isType<T>(value: T): value is CustomElementType<T>

Parameters

value: any - The value to check

Return Value

Returns true if the value is a custom element type, false otherwise.

Example

import { CustomElement, customElement, ILogger } from 'aurelia';

@customElement('my-element')
class MyElement {}

class RegularClass {}

// Service class that performs type checking
class TypeCheckingService {
  constructor(private logger: ILogger) {}

  public demonstrateTypeChecking() {
    // Type checking
    this.logger.info('MyElement is custom element type:', CustomElement.isType(MyElement)); // true
    this.logger.info('RegularClass is custom element type:', CustomElement.isType(RegularClass)); // false
    this.logger.info('String is custom element type:', CustomElement.isType('string')); // false
    this.logger.info('Number is custom element type:', CustomElement.isType(42)); // false
  }

  // Usage in dynamic scenarios
  public processComponent(component: unknown) {
    if (CustomElement.isType(component)) {
      // Safe to use as custom element
      const definition = CustomElement.getDefinition(component);
      this.logger.info('Processing element:', definition.name);
    } else {
      this.logger.info('Not a custom element type');
    }
  }
}

Metadata Methods

CustomElement.annotate

Attaches metadata to a custom element class. This is typically used internally by decorators and the framework.

Method Signature

CustomElement.annotate<K extends keyof PartialCustomElementDefinition>(
  Type: Constructable,
  prop: K,
  value: PartialCustomElementDefinition[K]
): void

Parameters

Type: Constructable - The custom element class to annotate
prop: string - The property key for the annotation
value: any - The value to associate with the property

Example

import { CustomElement } from 'aurelia';

class MyElement {}

// Manually annotate the class (decorators do this automatically)
CustomElement.annotate(MyElement, 'template', '${message}');
CustomElement.annotate(MyElement, 'bindables', ['message']);
CustomElement.annotate(MyElement, 'containerless', true);

CustomElement.getAnnotation

Retrieves metadata that was previously attached to a custom element class.

Method Signature

CustomElement.getAnnotation<K extends keyof PartialCustomElementDefinition>(
  Type: Constructable,
  prop: K
): PartialCustomElementDefinition[K] | undefined

Parameters

Type: Constructable - The custom element class
prop: string - The property key to retrieve

Return Value

Returns the annotation value, or undefined if not found.

Example

import { CustomElement, customElement, ILogger } from 'aurelia';

@customElement({
  name: 'annotated-element',
  template: '${content}'
})
class AnnotatedElement {
  constructor(private logger: ILogger) {}

  public logAnnotations() {
    // Retrieve annotations
    const template = CustomElement.getAnnotation(AnnotatedElement, 'template');
    const bindables = CustomElement.getAnnotation(AnnotatedElement, 'bindables');

    this.logger.info('Template:', template);
    this.logger.info('Bindables:', bindables);
  }
}

Utility Methods

CustomElement.generateName

Generates a unique name for a custom element, useful for anonymous or dynamically created elements.

Method Signature

CustomElement.generateName(): string

Return Value

A string representing a unique name (typically in the format unnamed-{number}).

Example

import { CustomElement } from 'aurelia';

// Generate unique names for dynamic elements
const uniqueName1 = CustomElement.generateName(); // 'unnamed-1'
const uniqueName2 = CustomElement.generateName(); // 'unnamed-2'

// Use with dynamic element creation
class DynamicElement {
  public data = '';
}

const DynamicElementType = CustomElement.define(uniqueName1, DynamicElement);

CustomElement.generateType

Dynamically generates a CustomElementType with a given name and prototype properties.

Method Signature

CustomElement.generateType<P extends object = object>(
  name: string,
  proto?: P
): CustomElementType<Constructable<P>>

Parameters

name: string - The name for the generated type
proto?: object - An optional object containing properties and methods to add to the prototype

Return Value

A CustomElementType that can be used with CustomElement.define.

Example

import { CustomElement } from 'aurelia';

// Generate a type with custom properties and methods
const DynamicElement = CustomElement.generateType('dynamic-element', {
  message: 'Hello from Dynamic Element!',
  count: 0,

  increment() {
    this.count++;
  },

  showMessage() {
    alert(`${this.message} Count: ${this.count}`);
  }
});

// Define the generated type
CustomElement.define('dynamic-element', DynamicElement);

// Usage in templates: <dynamic-element></dynamic-element>

CustomElement.createInjectable

Creates an InjectableToken for dependency injection scenarios.

Method Signature

CustomElement.createInjectable<T = any>(): InterfaceSymbol<T>

Return Value

An InterfaceSymbol that can be used as a dependency injection token.

Example

import { CustomElement, resolve } from 'aurelia';

// Create injectable tokens for custom scenarios
const MyServiceToken = CustomElement.createInjectable<MyService>();

// Use in dependency injection
class MyElement {
  private service = resolve(MyServiceToken);
}

CustomElement.keyFrom

Generates the registry key used internally to store and retrieve custom element definitions.

Method Signature

CustomElement.keyFrom(name: string): string

Parameters

name: string - The custom element name

Return Value

A string representing the internal registry key.

Example

import { CustomElement, ILogger } from 'aurelia';

class KeyGeneratorService {
  constructor(private logger: ILogger) {}

  public demonstrateKeyGeneration() {
    const key = CustomElement.keyFrom('my-element');
    this.logger.info(key); // 'au:ce:my-element' (internal format)

    // Used internally for container registration/lookup
    const hasElement = container.has(CustomElement.keyFrom('my-element'));
  }
}

Decorators

@customElement Decorator

The primary decorator for marking a class as a custom element.

Syntax

@customElement(name: string)
@customElement(definition: PartialCustomElementDefinition)

Examples

import { customElement } from 'aurelia';

// Simple name-based definition
@customElement('hello-world')
class HelloWorld {
  public message = 'Hello, World!';
}

// Full definition object
@customElement({
  name: 'advanced-component',
  template: `
    <h1>\${title}</h1>
    <div class="content">
      <au-slot></au-slot>
    </div>
  `,
  bindables: ['title', 'theme'],
  shadowOptions: { mode: 'open' },
  dependencies: []
})
class AdvancedComponent {
  public title = '';
  public theme = 'light';
}

@useShadowDOM Decorator

Enables Shadow DOM for the custom element.

Syntax

@useShadowDOM(options?: { mode: 'open' | 'closed' })

Example

import { customElement, useShadowDOM } from 'aurelia';

@customElement('shadow-element')
@useShadowDOM({ mode: 'open' })
class ShadowElement {
  // This element will render in Shadow DOM
}

// Or with default mode (open)
@customElement('shadow-element-simple')
@useShadowDOM()
class ShadowElementSimple {}

@containerless Decorator

Renders the custom element without its element container.

Syntax

@containerless()
@containerless(target: Constructable, context: ClassDecoratorContext)

Example

import { customElement, containerless } from 'aurelia';

@customElement('invisible-wrapper')
@containerless()
class InvisibleWrapper {
  // This element won't create its own DOM node
  // Only its content will be rendered
}

// Usage: <invisible-wrapper>content</invisible-wrapper>
// Renders: content (without the wrapper element)

@capture Decorator

Enables capturing of all attributes and bindings that are not explicitly defined as bindables or template controllers.

Syntax

@capture()
@capture(filter: (attr: string) => boolean)

Example

import { customElement, capture } from 'aurelia';

@customElement('flexible-element')
@capture() // Capture all unrecognized attributes
class FlexibleElement {
  // Any attribute not defined as bindable will be captured
}

@customElement('filtered-element')
@capture((attrName) => attrName.startsWith('data-'))
class FilteredElement {
  // Only capture attributes that start with 'data-'
}

@processContent Decorator

Defines a hook that processes the element's content before compilation.

Syntax

@processContent(hook: ProcessContentHook)
@processContent(methodName: string | symbol)
@processContent() // Decorator for static method

Example

import { customElement, processContent, IPlatform } from 'aurelia';

@customElement('content-processor')
class ContentProcessor {
  @processContent()
  static processContent(node: HTMLElement, platform: IPlatform, data: Record<PropertyKey, unknown>): boolean | void {
    // Modify the element's content before compilation
    const children = Array.from(node.children);
    children.forEach(child => {
      if (child.tagName === 'SPECIAL') {
        child.setAttribute('processed', 'true');
      }
    });
    return true; // Continue with normal compilation
  }
}

// Or reference a method by name
@customElement('named-processor')
@processContent('customProcessor')
class NamedProcessor {
  static customProcessor(node: HTMLElement, platform: IPlatform, data: Record<PropertyKey, unknown>): boolean | void {
    // Process content
    return true;
  }
}

Definition Objects

PartialCustomElementDefinition

An object that describes a custom element's configuration. All properties are optional.

Properties

interface PartialCustomElementDefinition {
  name?: string;                    // Element name (kebab-case)
  template?: string | Node | null;  // HTML template
  bindables?: string[] | object;    // Bindable properties
  dependencies?: any[];             // Required dependencies
  aliases?: string[];               // Alternative names
  containerless?: boolean;          // Render without container
  shadowOptions?: { mode: 'open' | 'closed' } | null; // Shadow DOM options
  hasSlots?: boolean;              // Has <au-slot> elements
  capture?: boolean | ((attr: string) => boolean); // Capture unbound attributes
  enhance?: boolean;               // Enhance existing DOM
  instructions?: any[][];          // Template instructions
  surrogates?: any[];             // Surrogate instructions
  needsCompile?: boolean;         // Requires compilation
  injectable?: any;               // DI token
  watches?: any[];               // Property watchers
  strict?: boolean;              // Strict binding mode
  processContent?: Function;     // Content processing hook
}

Example

const elementDefinition: PartialCustomElementDefinition = {
  name: 'my-component',
  template: `
    <h1>\${title}</h1>
    <p class="description">\${description}</p>
    <div class="actions">
      <au-slot name="actions"></au-slot>
    </div>
  `,
  bindables: ['title', 'description'],
  shadowOptions: { mode: 'open' },
  containerless: false,
  hasSlots: true,
  capture: false,
  dependencies: [],
  aliases: ['my-comp']
};

CustomElementDefinition

The complete, resolved definition of a custom element (read-only).

Key Properties

interface CustomElementDefinition {
  readonly Type: CustomElementType;      // The element class
  readonly name: string;                 // Element name
  readonly template: string | Node | null; // Compiled template
  readonly bindables: Record<string, BindableDefinition>; // Resolved bindables
  readonly aliases: string[];            // Alternative names
  readonly key: string;                  // Registry key
  readonly containerless: boolean;       // Container rendering mode
  readonly shadowOptions: { mode: 'open' | 'closed' } | null; // Shadow DOM
  readonly hasSlots: boolean;           // Contains slots
  readonly capture: boolean | Function; // Attribute capturing
  readonly enhance: boolean;            // DOM enhancement mode
  readonly dependencies: any[];         // Required dependencies
  readonly instructions: any[][];       // Template instructions
  readonly surrogates: any[];          // Surrogate instructions
  readonly needsCompile: boolean;      // Compilation requirement
  readonly watches: any[];             // Property watchers
  readonly strict: boolean | undefined; // Strict binding mode
  readonly processContent: Function | null; // Content processor
}

Programmatic Resource Aliases

PartialCustomElementDefinition.aliases is only one way to expose alternative names. For reusable libraries or bridge packages you often need to add aliases outside of the definition itself. The runtime provides two helpers to make that ergonomic.

`alias(...aliases)` decorator

Apply the decorator directly to any custom element, custom attribute, value converter, or binding behavior to append aliases to the resource metadata.

import { alias, customElement } from '@aurelia/runtime-html';

@alias('counter-panel', 'stats-card')
@customElement({
  name: 'au-counter',
  template: `
    <section class="counter">
      <h2>\${title}</h2>
      <slot></slot>
    </section>
  `
})
export class CounterPanel {
  title = 'Visitors';
}

The decorator merges with aliases declared via the definition object, so you can sprinkle default aliases in a base class and extend them in derived implementations without clobbering earlier metadata.

`registerAliases(...)`

When you need to attach aliases to an existing resource (for example, to keep backwards compatibility after a rename), call registerAliases during app startup.

import { AppTask, CustomElement, registerAliases } from '@aurelia/runtime-html';
import { IContainer } from '@aurelia/kernel';

export const LegacyCounterAliases = AppTask.creating(IContainer, container => {
  const definition = CustomElement.getDefinition(CounterPanel);
  registerAliases(['legacy-counter', 'legacy-panel'], CustomElement, definition.key, container);
});

The resource argument identifies which registry to update. Pass CustomElement, CustomAttribute, ValueConverter, or BindingBehavior depending on the resource you are aliasing. Because aliases are registered against the supplied container you can scope them to individual feature modules or make them global by running the task in your root configuration.

Best Practices

1. Use Decorators Over Direct API Calls

// Preferred
@customElement('my-element')
class MyElement {}

// Avoid unless in dynamic scenarios
CustomElement.define('my-element', MyElement);

2. Type Your Controllers

interface MyElementViewModel {
  title: string;
  count: number;
  increment(): void;
}

const controller = CustomElement.for<MyElementViewModel>(element);
controller.viewModel.increment(); // Fully typed

3. Handle Errors Gracefully

// Use optional flag when controller might not exist
const controller = CustomElement.for(element, { optional: true });
if (controller) {
  // Safe to use
} else {
  // Handle missing controller
}

4. Leverage Definition Objects for Complex Elements

@customElement({
  name: 'complex-element',
  template: complexTemplate,
  shadowOptions: { mode: 'open' },
  bindables: ['data', 'config'],
  dependencies: [SomeService, AnotherDependency]
})
class ComplexElement {}

PreviousScope and context NextComponent Recipes

Last updated 4 months ago

Was this helpful?

hashtagTable of Contents

hashtagCore Methods

hashtagCustomElement.for

hashtagMethod Signatures

hashtagParameters

hashtagExamples

hashtagCustomElement.define

hashtagMethod Signatures

hashtagParameters

hashtagExamples

hashtagCustomElement.getDefinition

hashtagMethod Signature

hashtagParameters

hashtagReturn Value

hashtagExample

hashtagCustomElement.find

hashtagMethod Signature

hashtagParameters

hashtagReturn Value

hashtagExample

hashtagCustomElement.isType

hashtagMethod Signature

hashtagParameters

hashtagReturn Value

hashtagExample

hashtagMetadata Methods

hashtagCustomElement.annotate

hashtagMethod Signature

hashtagParameters

hashtagExample

hashtagCustomElement.getAnnotation

hashtagMethod Signature

hashtagParameters

hashtagReturn Value

hashtagExample

hashtagUtility Methods

hashtagCustomElement.generateName

hashtagMethod Signature

hashtagReturn Value

hashtagExample

hashtagCustomElement.generateType

hashtagMethod Signature

hashtagParameters

hashtagReturn Value

hashtagExample

hashtagCustomElement.createInjectable

hashtagMethod Signature

hashtagReturn Value

hashtagExample

hashtagCustomElement.keyFrom

hashtagMethod Signature

hashtagParameters

hashtagReturn Value

hashtagExample

hashtagDecorators

hashtag@customElement Decorator

hashtagSyntax

hashtagExamples

hashtag@useShadowDOM Decorator

hashtagSyntax

hashtagExample

hashtag@containerless Decorator

hashtagSyntax

hashtagExample

hashtag@capture Decorator

hashtagSyntax

hashtagExample

hashtag@processContent Decorator

hashtagSyntax

hashtagExample

hashtagDefinition Objects

hashtagPartialCustomElementDefinition

hashtagProperties

hashtagExample

hashtagCustomElementDefinition

hashtagKey Properties

hashtagProgrammatic Resource Aliases

hashtagalias(...aliases) decorator

hashtagregisterAliases(...)

hashtagBest Practices

Table of Contents

Core Methods

CustomElement.for

Method Signatures

Parameters

Examples

CustomElement.define

Method Signatures

Parameters

Examples

CustomElement.getDefinition

Method Signature

Parameters

Return Value

Example

CustomElement.find

Method Signature

Parameters

Return Value

Example

CustomElement.isType

Method Signature

Parameters

Return Value

Example

Metadata Methods

CustomElement.annotate

Method Signature

Parameters

Example

CustomElement.getAnnotation

Method Signature

Parameters

Return Value

Example

Utility Methods

CustomElement.generateName

Method Signature

Return Value

Example

CustomElement.generateType

Method Signature

Parameters

Return Value

Example

CustomElement.createInjectable

Method Signature

Return Value

Example

CustomElement.keyFrom

Method Signature

Parameters

Return Value

Example

Decorators

@customElement Decorator

Syntax

Examples

@useShadowDOM Decorator

Syntax

Example

@containerless Decorator

Syntax

Example

@capture Decorator

Syntax

Example

@processContent Decorator

Syntax

Example

Definition Objects

PartialCustomElementDefinition

Properties

Example

CustomElementDefinition

Key Properties

Programmatic Resource Aliases

`alias(...aliases)` decorator

`registerAliases(...)`

Best Practices