Understanding Pipes

Use pipes to transform strings, currency amounts, dates, and other data for display.

What is a pipe

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.

Built-in pipes

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:

• DatePipe: Formats a date value according to locale rules.

• UpperCasePipe: Transforms text to all upper case.

• LowerCasePipe: Transforms text to all lower case.

• CurrencyPipe: Transforms a number to a currency string, formatted according to locale rules.

• DecimalPipe: Transforms a number into a string with a decimal point, formatted according to locale rules.

• PercentPipe: Transforms a number to a percentage string, formatted according to locale rules.

• AsyncPipe: Subscribe and unsubscribe to an asynchronous source such as an observable.

• JsonPipe: Display a component object property to the screen as JSON for debugging.

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.

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.

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.

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.

Pipe precedence in template expressions

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,

is parsed as

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,

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