The Angular output() function is a powerful tool that developers can use to emit values to parent components, making it an essential part of modern Angular applications. This guide will walk you through its functionalities, benefits, and best practices.

What is the output() Function in Angular?

The Angular output() function declares an output in a directive or component, allowing you to emit values to parent components. This function is currently in developer preview but provides a robust way to manage outputs in Angular applications.

Basic Usage Example

The following example demonstrates the basic use of the output() function in a component.

import { Component, output } from '@angular/core';


@Component({
  selector: 'my-comp',
  template: `<button (click)="setNewName('John')">Change Name</button>`
})
export class MyComp {
  onNameChange = output<string>(); // OutputEmitterRef<string>
  
  setNewName(newName: string) {
    this.onNameChange.emit(newName);
  }
}

In the parent component, you can listen to this output using event binding syntax.

<my-comp (onNameChange)="showNewName($event)"></my-comp>

Here, showNewName is a method in the parent component that handles the emitted value.

Detailed Example

For a more detailed example, consider a component that emits a custom event when a user's profile is updated:

import { Component, output } from '@angular/core';


@Component({
  selector: 'user-profile',
  template: `
    <div>
      <input [(ngModel)]="userName" placeholder="Enter your name">
      <button (click)="updateProfile()">Update Profile</button>
    </div>
  `
})
export class UserProfileComponent {
  userName: string = '';
  profileUpdated = output<{ name: string }>(); // OutputEmitterRef<{ name: string }>


  updateProfile() {
    this.profileUpdated.emit({ name: this.userName });
  }
}

The parent component can bind to profileUpdated to handle profile updates:

<user-profile (profileUpdated)="handleProfileUpdate($event)"></user-profile>

import { Component } from '@angular/core';


@Component({
  selector: 'app-root',
  template: `<user-profile (profileUpdated)="handleProfileUpdate($event)"></user-profile>`
})
export class AppComponent {
  handleProfileUpdate(event: { name: string }) {
    console.log('Profile updated with name:', event.name);
  }
}

Why Use the Angular output() Function Over @Output() Decorator?

Using the output() function provides several advantages over the traditional decorator-based @Output() and EventEmitter:

Simplified API

The output() function offers a simpler mental model without the complexities of error and completion channels associated with RxJS.

Accurate Typing

OutputEmitterRef.emit(value) is correctly typed, reducing the risk of runtime errors, unlike EventEmitter. This ensures that the emitted values match the expected types, improving type safety and reducing bugs.

Enhanced Type Safety Example

Consider the following example using @Output():

import { Component, EventEmitter, Output } from '@angular/core';


@Component({
  selector: 'old-comp',
  template: `<button (click)="notify()">Notify</button>`
})
export class OldComp {
  @Output() notify = new EventEmitter<string>();
  
  notify() {
    this.notify.emit(123); // This will cause a runtime error because the type is incorrect
  }
}

Using output() ensures the type is correct at compile-time:

import { Component, output } from '@angular/core';


@Component({
  selector: 'new-comp',
  template: `<button (click)="notify()">Notify</button>`
})
export class NewComp {
  notify = output<string>();


  notify() {
    this.notify.emit('Hello World'); // Type safety enforced
  }
}

Aliasing an Output

Angular uses the class member name as the output's name. You can alias outputs to change their public name, making the API more intuitive for consumers of your component.

Example of Aliasing an Output

class MyComp {
  onNameChange = output({alias: 'ngxNameChange'});
}

With this alias, users can bind to the output using (ngxNameChange) while still accessing the emitter internally using this.onNameChange.

Subscribing Programmatically

Components created dynamically can have their outputs subscribed to directly, providing flexibility in dynamic component creation scenarios.

Example of Programmatic Subscription

import { ViewContainerRef, ComponentFactoryResolver } from '@angular/core';


const factory = this.componentFactoryResolver.resolveComponentFactory(MyComp);
const myComp = this.viewContainerRef.createComponent(factory);
myComp.instance.onNameChange.subscribe(newName => {
  console.log('Name changed to:', newName);
});

Angular handles the subscription cleanup automatically when the component is destroyed, though manual unsubscription is also possible.

Using RxJS Observables as Source

In scenarios where you need to emit output values based on RxJS observables, Angular provides the outputFromObservable function.

Example Using RxJS Observable

import { Directive } from '@angular/core';
import { outputFromObservable } from '@angular/core/rxjs-interop';


@Directive({
  selector: '[myDir]'
})
class MyDir {
  nameChange$ = this.dataService.get(); // Observable<Data>
  nameChange = outputFromObservable(this.nameChange$);
}

When the directive owning the observable is destroyed, Angular stops forwarding values from the observable.

Converting an Output to an Observable

You can convert an OutputRef to an observable using Angular's helper function, allowing seamless integration with RxJS operators.

Example of Converting Output to Observable

import { outputToObservable } from '@angular/core/rxjs-interop';
import { map } from 'rxjs/operators';


@Component({
  selector: 'my-comp',
  template: `<button (click)="notify()">Notify</button>`
})
class MyComp {
  onNameChange = output<string>();


  notify() {
    this.onNameChange.emit('Hello World');
  }
}


const myComp: MyComp;
outputToObservable(this.myComp.instance.onNameChange)
  .pipe(map(name => `New name: ${name}`))
  .subscribe(name => console.log(name));

Pros and Cons of Using the output() Function

Pros:

  • Simplified API: Less complex than handling RxJS directly.
  • Type Safety: More accurate types prevent runtime errors.
  • Flexibility: Allows for both imperative and observable-based outputs.

Cons:

  • Developer Preview: Being in developer preview means it may still have some limitations and potential changes.

FAQs

1. What is the primary purpose of the output() function in Angular?

The output() function is used to emit values to parent components, simplifying communication between components.

2. How does the output() function differ from @Output()?

The output() function offers a simpler API and more accurate typing compared to @Output().

3. Can I use RxJS observables with the output() function?

Yes, you can use RxJS observables as sources for outputs with the outputFromObservable function.

4. Is the output() function stable for production use?

As it is currently in developer preview, it is advisable to use it cautiously in production environments.

5. How do I subscribe to an output programmatically?

You can subscribe programmatically by accessing the output property directly and using the .subscribe method.

6. Can I alias an output using the output() function?

Yes, you can alias outputs to change their public names.

7. How is cleanup handled for output subscriptions?

Angular automatically cleans up subscriptions when the component is destroyed.

8. What are the benefits of using the output() function?

It provides a simpler API, accurate typing, and flexibility for both imperative and observable-based outputs.

9. How can I convert an OutputRef to an observable?

You can use the outputToObservable helper function to convert an OutputRef to an observable.

10. Is there a performance difference between output() and @Output()?

The performance is generally similar, but output() offers a more streamlined and type-safe approach.

Conclusion

The Angular output() function is a valuable addition to any developer's toolkit, offering simplified APIs and improved type safety. By understanding its usage, benefits, and best practices, you can enhance your Angular applications' inter-component communication. Whether you're using imperative methods or RxJS observables, the output() function provides a robust and flexible solution for managing outputs in Angular.

Recent Articles