Skip to content

docs: Add DestroyRef and takeUntilDestroyed sections to lifecycle doc #50042

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
dylhunn wants to merge 1 commit into from
Closed

docs: Add DestroyRef and takeUntilDestroyed sections to lifecycle doc #50042

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 45 additions & 2 deletions aio/content/guide/lifecycle-hooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Lifecycle hooks
# Component Lifecycle

A component instance has a lifecycle that starts when Angular instantiates the component class and renders the component view along with its child views.
The lifecycle continues with change detection, as Angular checks to see when data-bound properties change, and updates both the view and the component instance as needed.
Expand Down Expand Up @@ -84,7 +84,11 @@ Use the `ngOnInit()` method to perform the following initialization tasks.

## Cleaning up on instance destruction

Put cleanup logic in `ngOnDestroy()`, the logic that must run before Angular destroys the directive.
Angular provides several ways to clean up when an instance is destroyed.

### `ngOnDestroy`

You can put cleanup logic in `ngOnDestroy()`, the logic that must run before Angular destroys the directive.

This is the place to free resources that won't be garbage-collected automatically.
You risk memory leaks if you neglect to do so.
Expand All @@ -95,6 +99,45 @@ You risk memory leaks if you neglect to do so.

The `ngOnDestroy()` method is also the time to notify another part of the application that the component is going away.

### DestroyRef

In addition to to `ngOnDestroy()`, you can inject Angular's `DestroyRef` and register callback functions to be called when the enclosing context is destroyed. This can be useful for building reusable utilities that require cleanup.

Register a callback with the `DestroyRef`:

```ts
@Component(...)
class Counter {
count = 0;
constructor() {
// Start a timer to increment the counter every second.
const id = setInterval(() => this.count++, 1000);

// Stop the timer when the component is destroyed.
const destroyRef = inject(DestroyRef);
destroyRef.onDestroy(() => clearInterval(id));
}
}
```

Like `ngOnDestroy`, `DestroyRef` works in any Angular service, directive, component, or pipe.

### `takeUntilDestroyed`

<div class="alert is-important">

`takeUntilDestroyed` is available for [developer preview](/guide/releases#developer-preview). It's ready for you to try, but it might change before it is stable.

</div>

When using RxJS Observables in components or directives, you may want to complete any observables when the component or directive is destroyed. Angular's `@angular/core/rxjs-interop` package provides an operator, `takeUntilDestroyed`, to simply this common task:

```ts
data$ = http.get('...').pipe(takeUntilDestroyed());
```

By default, `takeUntilDestroyed` must be called in an injection context so that it can access `DestroyRef`. If an injection context isn't available, you can explicitly provide a `DestroyRef`.

## General examples

The following examples demonstrate the call sequence and relative frequency of the various lifecycle events, and how the hooks can be used separately or together for components and directives.
Expand Down