Component lifecycles
Aurelia components offer a rich lifecycle that lets you hook into specific moments of a component's existence—from construction, through activation, to eventual disposal. Understanding the order and intent of each hook will help you write components that are predictable, testable, and memory-leak-free.
Quick reference
Construction
constructor
once
–
–
define
once
top ➞ down
no
hydrating
once
top ➞ down
no
hydrated
once
top ➞ down
no
created
once
bottom ➞ up
no
Activation
binding
every activation
top ➞ down
yes (blocks children)
bound
every activation
bottom ➞ up
yes (awaits)
attaching
every activation
top ➞ down
yes (awaits before attached
)
attached
every activation
bottom ➞ up
yes (awaits)
Deactivation
detaching
every deactivation
bottom ➞ up
yes (awaits before DOM removal)
unbinding
every deactivation
bottom ➞ up
yes (awaits)
Cleanup
dispose
when permanently discarded
–
–
Legend
top ➞ down – parent executes before its children
bottom ➞ up – children execute before their parent
Detailed walkthrough
1. Constructor
Executed when the instance is created. Inject services here and perform work that does not depend on bindable values.
import { resolve } from 'aurelia';
import { IRouter } from '@aurelia/router';
export class MyComponent {
readonly router = resolve(IRouter);
}
2. Define
define(
controller: IDryCustomElementController<this>,
hydrationContext: IHydrationContext | null,
definition: CustomElementDefinition
): PartialCustomElementDefinition | void {}
Opportunity to modify the component definition before hydration begins.
Can return a partial definition to override aspects of the component's behavior.
Runs synchronously, parent before children.
3. Hydrating
hydrating(controller: IContextualCustomElementController<this>): void {}
Opportunity to register dependencies in
controller.container
that are needed while compiling the view template.Runs synchronously, parent before children.
4. Hydrated
hydrated(controller: ICompiledCustomElementController<this>): void {}
View template has been compiled, child components are not yet created.
Last chance to influence how the soon-to-be-created child components resolve their dependencies.
5. Created
created(controller: ICustomElementController<this> | ICustomAttributeController<this>): void {}
All child components are now constructed and hydrated.
Executes once per instance, children before parent.
Great for logic that must run after the whole subtree is constructed but before binding.
6. Binding
// Custom Elements
binding(initiator: IHydratedController, parent: IHydratedController | null): void | Promise<void> {}
// Custom Attributes
binding(initiator: IHydratedController, parent: IHydratedController): void | Promise<void> {}
Bindable properties have been set but bindings in the view are not yet connected.
Runs parent ➞ child.
Return a
Promise
(or mark the methodasync
) to block binding/attaching of children until resolved.
7. Bound
// Custom Elements
bound(initiator: IHydratedController, parent: IHydratedController | null): void | Promise<void> {}
// Custom Attributes
bound(initiator: IHydratedController, parent: IHydratedController): void | Promise<void> {}
View-to-view-model bindings are active;
ref
,let
, andfrom-view
values are available.Executes child ➞ parent.
8. Attaching
// Custom Elements
attaching(initiator: IHydratedController, parent: IHydratedController | null): void | Promise<void> {}
// Custom Attributes
attaching(initiator: IHydratedController, parent: IHydratedController): void | Promise<void> {}
The component's host element is now in the DOM but child components may still be attaching.
Queue animations or setup 3rd-party libraries here.
A returned
Promise
is awaited beforeattached
is invoked on this component but does not block children.
9. Attached
attached(initiator: IHydratedController): void | Promise<void> {}
The entire component subtree is mounted; safe to measure elements or call libraries that need actual layout information.
Executes child ➞ parent.
Note: Only receives the
initiator
parameter, not the parent.
10. Detaching
// Custom Elements
detaching(initiator: IHydratedController, parent: IHydratedController | null): void | Promise<void> {}
// Custom Attributes
detaching(initiator: IHydratedController, parent: IHydratedController): void | Promise<void> {}
Called when the framework removes the component's element from the DOM.
Executes child ➞ parent. Any returned
Promise
(e.g., an outgoing animation) is awaited in parallel with sibling promises.
11. Unbinding
// Custom Elements
unbinding(initiator: IHydratedController, parent: IHydratedController | null): void | Promise<void> {}
// Custom Attributes
unbinding(initiator: IHydratedController, parent: IHydratedController): void | Promise<void> {}
Runs after
detaching
finishes and bindings have been disconnected.Executes child ➞ parent.
12. Dispose
dispose(): void {}
Invoked when the instance is permanently discarded—typically when removed from a repeater and the view cache is full, or when the application shuts down.
Use to tear down long-lived resources, subscriptions, or manual observers to prevent memory leaks.
Lifecycle hooks decorator (@lifecycleHooks
)
@lifecycleHooks
)For cross-cutting concerns like logging, analytics, or debugging, implement lifecycle hooks in a separate class using the @lifecycleHooks
decorator. This keeps your component code focused while adding shared behavior.
import { lifecycleHooks, ILifecycleHooks, ICustomElementController, IHydratedController } from 'aurelia';
@lifecycleHooks()
export class ComponentLogger implements ILifecycleHooks<MyComponent> {
bound(vm: MyComponent, initiator: IHydratedController, parent: IHydratedController | null) {
console.log(`${vm.constructor.name} bound with data:`, vm.someProperty);
}
detaching(vm: MyComponent, initiator: IHydratedController, parent: IHydratedController | null) {
console.log(`${vm.constructor.name} detaching`);
}
}
Multiple lifecycle hook classes can be registered; the framework executes them in registration order alongside the component's own lifecycle methods.
Special cases
<au-compose>
components additionally supportactivate
/deactivate
hooks—see the dynamic composition guide.Router hooks such as
canLoad
,loading
,canUnload
,unloading
, etc., are documented in the routing lifecycle section and are available even if you do not use the router.
Best practices
Prefer early exits—perform checks at the start of hooks and
return
early to minimise nesting.Clean up observers, timeouts, event listeners, or 3rd-party widgets in the opposite hook (
unbinding
/detaching
ordispose
).Avoid heavy work in the constructor. Move anything needing bindables or DOM to later hooks.
Mark hooks
async
andawait
your operations instead of manually creating Promises for clarity.Keep hooks fast—expensive work can block the component hierarchy.
Last updated
Was this helpful?