Transforming Data Using Pipes

Use pipes to transform strings, currency amounts, dates, and other data for display. Pipes are simple functions to use in template expressions to accept an input value and return a transformed value. Pipes are useful because you can use them throughout your application, while only declaring each pipe once. For example, you would use a pipe to show a date as April 15, 1988 rather than the raw string format.

Angular provides built-in pipes for typical data transformations, including transformations for internationalization (i18n), which use locale information to format data. The following are commonly used built-in pipes for data formatting:

Create pipes to encapsulate custom transformations and use your custom pipes in template expressions.

Prerequisites

To use pipes you should have a basic understanding of the following:

• Typescript and HTML5 programming
• Templates in HTML with CSS styles
• Components

Using a pipe in a template

To apply a pipe, use the pipe operator (|) within a template expression as shown in the following code example.

      
        content_copy
      
      <p>The hero's birthday is {{ birthday | date }}</p>
    

The component's birthday value flows through the pipe operator (|) to the DatePipe whose pipe name is date. The pipe renders the date in the default format as Apr 15, 1988.

Look at the component class.

      
        content_copy
      
      import { Component } from '@angular/core';
import { DatePipe } from '@angular/common';

@Component({
  standalone: true,
  selector: 'app-birthday',
  templateUrl: './birthday.component.html',
  imports: [DatePipe],
})
export class BirthdayComponent {
  birthday = new Date(1988, 3, 15); // April 15, 1988 -- since month parameter is zero-based
}
    

Because this is a standalone component, it imports the DatePipe from @angular/common, the source of all built-in pipes.

Transforming data with parameters and chained pipes

Some pipes have optional parameters to fine-tune the pipe's output.

For example, the CurrencyPipe accepts a country code as a parameter. To specify the parameter, follow the pipe name (currency) with a colon (:) and the parameter value (a country code).

The template expression {{ amount | currency:'EUR' }} displays the amount, prefixed with the Euros symbol (€).

Some pipes accept multiple optional parameters. Pass each parameter to the pipe, separated by colons.

For example, {{ amount | currency:'EUR':'Euros '}} displays the amount with the label "Euros" (the second parameter) instead of the Euros symbol.

Some pipes, such as SlicePipe, require at least one parameter and may allow more optional parameters.

The expression {{ anArray | slice:1:5 }} displays a new string containing a subset of the elements starting with element 1 and ending with element 5.

Example: Formatting a date

The following example demonstrates two ways to format a hero's birthdate with the DatePipe.

      
        content_copy
      
      <p>The hero's birthday is {{ birthday | date:"shortDate" }} in the "shortDate" format.</p>

<p>The hero's birthday is {{ birthday | date:format }} in "{{format}}" format.
  Click the toggle button to change formats.</p>

<button type="button" (click)="toggleFormat()">Toggle Format</button>
    

In the template, the first expression passes the birthdate to the DatePipe with a literal date format parameter, "shortDate". The output is 04/15/88.

The second expression passes the birthdate to the DatePipe with a date format parameter bound to a component property (format).

Clicking the "Toggle" button switches that property value between two of the many possible pre-defined formats, 'mediumDate' and 'fullDate'. The output is either April 15, 1988 or Friday, April 15, 1988.

The page displays the birthdate in the specified format.

Example: Chaining two pipes together

Connect multiple pipes, using "pipe chaining syntax", so that the output of one pipe becomes the input to the next.

The following example passes the birthdate to the DatePipe and then forwards the result to the UpperCasePipe pipe, using "pipe chaining syntax".

Once again, it demonstrates the DatePipe both with and without a format parameter. Note that both results (APR 15, 1988 and FRIDAY, APRIL 15, 1988) are in uppercase.

      
        content_copy
      
      <p>
  The chained hero's uppercase birthday is
  {{ birthday | date | uppercase}}
</p>

<p>
  The chained hero's uppercase birthday in "fullDate" format is
  {{ birthday | date:'fullDate' | uppercase}}
</p>
    

Switch to the class file to see that this is a standalone component; it imports the two pipes from @angular/common, the source of all built-in pipes.

Creating pipes for custom data transformations

Create custom pipes to encapsulate transformations that are not provided with the built-in pipes. Then, use your custom pipe in template expressions, the same way you use built-in pipes —to transform input values to output values for display.

Marking a class as a pipe

To mark a class as a pipe and supply configuration metadata, apply the @Pipe decorator to the class. Use UpperCamelCase (the general convention for class names) for the pipe class name, and camelCase for the corresponding name string. Do not use hyphens in the name. For details and more examples, see Pipe names.

Use name in template expressions as you would for a built-in pipe.

Using the PipeTransform interface

Implement the PipeTransform interface in your custom pipe class to perform the transformation.

Angular invokes the transform method with the value of a binding as the first argument, and any parameters as the second argument in list form, and returns the transformed value.

Example: Transforming a value exponentially

In a game, you might want to implement a transformation that raises a value exponentially to increase a hero's power. For example, if the hero's score is 2, boosting the hero's power exponentially by 10 produces a score of 1024. Use a custom pipe for this transformation.

The following code example shows two component definitions:

      
        content_copy
      
      import { Pipe, PipeTransform } from '@angular/core';
/*
 * Raise the value exponentially
 * Takes an exponent argument that defaults to 1.
 * Usage:
 *   value | exponentialStrength:exponent
 * Example:
 *   {{ 2 | exponentialStrength:10 }}
 *   formats to: 1024
*/
@Pipe({
  standalone: true,
  name: 'exponentialStrength'
})
export class ExponentialStrengthPipe implements PipeTransform {
  transform(value: number, exponent = 1): number {
    return Math.pow(value, exponent);
  }
}
    

The browser displays the following:

      
      Power Booster

Superpower boost: 1024
    

Detecting changes with data binding in pipes

You use data binding with a pipe to display values and respond to user actions. If the data is a primitive input value, such as String or Number, or an object reference as input, such as Date or Array, Angular executes the pipe whenever it detects a change for the input value or reference.

For example, you could change the previous custom pipe example to use two-way data binding with ngModel to input the amount and boost factor, as shown in the following code example.

      
        content_copy
      
      import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';

import { ExponentialStrengthPipe } from './exponential-strength.pipe';
@Component({
  standalone: true,
  selector: 'app-power-boost-calculator',
  template: `
    <h2>Power Boost Calculator</h2>
    <label for="power-input">Normal power: </label>
    <input id="power-input" type="text" [(ngModel)]="power">
    <label for="boost-input">Boost factor: </label>
    <input id="boost-input" type="text" [(ngModel)]="factor">
    <p>
      Super Hero Power: {{power | exponentialStrength: factor}}
    </p>
  `,
  imports: [ExponentialStrengthPipe, FormsModule],
  styles: ['input {margin: .5rem 0;}']
})
export class PowerBoostCalculatorComponent {
  power = 5;
  factor = 1;
}
    

The exponentialStrength pipe executes every time the user changes the "normal power" value or the "boost factor".

Angular detects each change and immediately runs the pipe. This is fine for primitive input values. However, if you change something inside a composite object (such as the month of a date, an element of an array, or an object property), you need to understand how change detection works, and how to use an impure pipe.

How change detection works

Angular looks for changes to data-bound values in a change detection process that runs after every DOM event: every keystroke, mouse move, timer tick, and server response. The following example, which doesn't use a pipe, demonstrates how Angular uses its default change detection strategy to monitor and update its display of every hero in the heroes array. The example tabs show the following:

      
        content_copy
      
      <label for="hero-name">New hero name: </label>
<input type="text" #box id="hero-name" (keyup.enter)="addHero(box.value); box.value=''" placeholder="hero name">
  <button type="button" (click)="reset()">Reset list of heroes</button>
  <!<!-- Only used in deprecated `pipes.md` -->
  <div *ngFor="let hero of heroes">
    {{hero.name}}
  </div>
    

Angular updates the display every time the user adds a hero. If the user clicks the Reset button, Angular replaces heroes with a new array of the original heroes and updates the display. If you add the ability to remove or change a hero, Angular would detect those changes and update the display as well.

However, executing a pipe to update the display with every change would slow down your application's performance. So Angular uses a faster change-detection algorithm for executing a pipe, as described in the next section.

Detecting pure changes to primitives and object references

By default, pipes are defined as pure so that Angular executes the pipe only when it detects a pure change to the input value. A pure change is either a change to a primitive input value (such as String, Number, Boolean, or Symbol), or a changed object reference (such as Date, Array, Function, or Object).

A pure pipe must use a pure function, which is one that processes inputs and returns values without side effects. In other words, given the same input, a pure function should always return the same output.

With a pure pipe, Angular ignores changes within composite objects, such as a newly added element of an existing array, because checking a primitive value or object reference is much faster than performing a deep check for differences within objects. Angular can quickly determine if it can skip executing the pipe and updating the view.

However, a pure pipe with an array as input might not work the way you want. To demonstrate this issue, change the previous example to filter the list of heroes to just those heroes who can fly. Use the FlyingHeroesPipe in the *ngFor repeater as shown in the following code. The tabs for the example show the following:

• The template (flying-heroes.component.html (flyers)) with the new pipe
• The FlyingHeroesPipe custom pipe implementation (flying-heroes.pipe.ts)

      
        content_copy
      
      <div *ngFor="let hero of (heroes | flyingHeroes)">
  {{hero.name}}
</div>
    

The application now shows unexpected behavior: When the user adds flying heroes, none of them appear under "Heroes who fly." This happens because the code that adds a hero does so by pushing it onto the heroes array:

      
        content_copy
      
      this.heroes.push(hero);
    

The change detector ignores changes to elements of an array, so the pipe doesn't run.

The reason Angular ignores the changed array element is that the reference to the array hasn't changed. Because the array is the same, Angular does not update the display.

One way to get the behavior you want is to change the object reference itself. Replace the array with a new array containing the newly changed elements, and then input the new array to the pipe. In the preceding example, create an array with the new hero appended, and assign that to heroes. Angular detects the change in the array reference and executes the pipe.

To summarize, if you mutate the input array, the pure pipe doesn't execute. If you replace the input array, the pipe executes and the display is updated.

The preceding example demonstrates changing a component's code to accommodate a pipe.

To keep your component independent of HTML templates that use pipes, you can, as an alternative, use an impure pipe to detect changes within composite objects such as arrays, as described in the next section.

Detecting impure changes within composite objects

To execute a custom pipe after a change within a composite object, such as a change to an element of an array, you need to define your pipe as impure to detect impure changes. Angular executes an impure pipe every time it detects a change with every keystroke or mouse movement.

Make a pipe impure by setting its pure flag to false:

      
        content_copy
      
      @Pipe({
  standalone: true,
  name: 'flyingHeroesImpure',
  pure: false
})
    

The following code shows the complete implementation of FlyingHeroesImpurePipe, which extends FlyingHeroesPipe to inherit its characteristics. The example shows that you don't have to change anything else—the only difference is setting the pure flag as false in the pipe metadata.

      
        content_copy
      
      @Pipe({
  standalone: true,
  name: 'flyingHeroesImpure',
  pure: false
})
export class FlyingHeroesImpurePipe extends FlyingHeroesPipe { }
    

FlyingHeroesImpurePipe is a good candidate for an impure pipe because the transform function is trivial and fast:

      
        content_copy
      
      return allHeroes.filter(hero => hero.canFly);
    

You can derive a FlyingHeroesImpureComponent from FlyingHeroesComponent. As shown in the following code, only the pipe in the template changes.

      
        content_copy
      
      <div *ngFor="let hero of (heroes | flyingHeroesImpure)">
  {{hero.name}}
</div>
    

Unwrapping data from an observable

Observables let you pass messages between parts of your application. Observables are recommended for event handling, asynchronous programming, and handling multiple values. Observables can deliver single or multiple values of any type, either synchronously (as a function delivers a value to its caller) or asynchronously on a schedule.

Use the built-in AsyncPipe to accept an observable as input and subscribe to the input automatically. Without this pipe, your component code would have to subscribe to the observable to consume its values, extract the resolved values, expose them for binding, and unsubscribe when the observable is destroyed in order to prevent memory leaks. AsyncPipe is an impure pipe that saves boilerplate code in your component to maintain the subscription and keep delivering values from that observable as they arrive.

The following code example binds an observable of message strings (message$) to a view with the async pipe.

      
        content_copy
      
      import { Component } from '@angular/core';
import { AsyncPipe } from '@angular/common';

import { Observable, interval } from 'rxjs';
import { map, startWith, take } from 'rxjs/operators';

@Component({
  standalone: true,
  selector: 'app-hero-async-message',
  template: `
    <h2>Async Messages and AsyncPipe</h2>
    <p>{{ message$ | async }}</p>
    <button type="button" (click)="resend()">Resend Messages</button>`,
  imports: [AsyncPipe],
})
export class HeroAsyncMessageComponent {
  message$: Observable<string>;

  private messages = [
    'You are my hero!',
    'You are the best hero!',
    'Will you be my hero?'
  ];

  constructor() {
    this.message$ = this.getResendObservable();
  }

  resend() {
    this.message$ = this.getResendObservable();
  }

  private getResendObservable() {
    return interval(1000).pipe(
      map(i => `Message #${i + 1}: ${this.messages[i]}`),
      take(this.messages.length),
      startWith('Waiting for messages...')
    );
  }
}
    

Caching HTTP requests

To communicate with backend services using HTTP, the HttpClient service uses observables and offers the HttpClient.get() method to fetch data from a server. The asynchronous method sends an HTTP request, and returns an observable that emits the requested data for the response.

As shown in the previous section, use the impure AsyncPipe to accept an observable as input and subscribe to the input automatically. You can also create an impure pipe to make and cache an HTTP request.

Impure pipes are called whenever change detection runs for a component, which could be as often as every few milliseconds. To avoid performance problems, call the server only when the requested URL changes, as shown in the following example, and use the pipe to cache the server response. The tabs show the following:

• The fetch pipe (fetch-json.pipe.ts).
• A harness component (hero-list.component.ts) for demonstrating the request, using a template that defines two bindings to the pipe requesting the heroes from the heroes.json file. The second binding chains the fetch pipe with the built-in JsonPipe to display the same hero data in JSON format.

      
        content_copy
      
      import { HttpClient } from '@angular/common/http';
import { Pipe, PipeTransform } from '@angular/core';

@Pipe({
  standalone: true,
  name: 'fetch',
  pure: false,
})
export class FetchJsonPipe implements PipeTransform {
  private cachedData: any = null;
  private cachedUrl = '';

  constructor(private http: HttpClient) { }

  transform(url: string): any {
    if (url !== this.cachedUrl) {
      this.cachedData = null;
      this.cachedUrl = url;
      this.http.get(url).subscribe(result => this.cachedData = result);
    }

    return this.cachedData;
  }
}
    

In the preceding example, a breakpoint on the pipe's request for data shows the following:

• Each binding gets its own pipe instance.
• Each pipe instance caches its own URL and data and calls the server only once.

The fetch and fetch-json pipes display the heroes in the browser as follows:

      
      Heroes from JSON File

Windstorm
Bombasto
Magneto
Tornado

Heroes as JSON: [ { "name": "Windstorm", "canFly": true }, { "name": "Bombasto", "canFly": false }, { "name": "Magneto", "canFly": false }, { "name": "Tornado", "canFly": true } ]
    

Pipes and precedence

Sometimes you want to choose between two values, based on some condition, before passing the choice to the pipe. You could use the JavaScript ternary operator (?:) in the template to make that choice.

Beware! The pipe operator has a higher precedence than the JavaScript ternary operator (?:).

If you simply write the expression as if it were evaluated left-to-right, you might be surprised by the result. For example,

      
        content_copy
      
      condition ? a : b | pipe
    

is parsed as

      
        content_copy
      
      condition ? a : (b | pipe)
    

The value of b passes through pipe; the value of a will not.

If you want the pipe to apply to the result of the ternary expression, wrap the entire expression in parentheses. For example,

      
        content_copy
      
      (condition ? a : b) | pipe
    

In general, you should always use parentheses to be sure Angular evaluates the expression as you intend.

The "Pipes and Precedence" section of the pipes examplepipes example explores this issue in more detail.