Pipes
What pipes are
Section titled “What pipes are”A pipe is a declarative transformation applied in a template with the | operator:
<p>Total: {{ amount | currency }}</p><h1>Purchases from {{ company | titlecase }} on {{ purchasedOn | date }}</h1>Pipes are standalone by default and must appear in the component’s imports:
@Component({ imports: [CurrencyPipe, DatePipe, TitleCasePipe], /* ... */})Forgetting the import is the single most common pipe error, and the message — “The pipe ‘currency’ could not be found” — is at least clear about it.
Note that Angular’s | is not JavaScript’s bitwise OR. Angular template expressions have no bitwise operators at all, so the character is unambiguous.
Built-in pipes
Section titled “Built-in pipes”From @angular/common:
| Pipe | Purpose |
|---|---|
AsyncPipe |
Unwraps a Promise or Observable |
CurrencyPipe |
Number to a locale-formatted currency string |
DatePipe |
Formats a Date by locale rules |
DecimalPipe |
Number with a locale decimal point |
PercentPipe |
Number to a locale percentage |
LowerCasePipe / UpperCasePipe / TitleCasePipe |
Case transformations |
SlicePipe |
A subset of an array or string |
KeyValuePipe |
Object or Map to key/value pairs |
JsonPipe |
JSON.stringify — for debugging |
I18nPluralPipe / I18nSelectPipe |
Locale-aware plurals and selection |
The formatting pipes are locale-aware, which is the main reason to use them over hand-rolled formatting. {{ amount | currency }} renders $123.45 for a US user and the appropriate format elsewhere, and it stays correct when a locale is added.
JsonPipe is a debugging tool. It runs JSON.stringify on every check and will happily serialise a large object into the DOM.
Parameters
Section titled “Parameters”Append with ::
<p>{{ scheduledOn | date: 'hh:mm' : 'UTC' }}</p><p>{{ amount | currency: 'EUR' : 'symbol' : '1.2-2' }}</p>Chaining
Section titled “Chaining”Left to right:
<p>{{ scheduledOn | date | uppercase }}</p>Operator precedence — a real trap
Section titled “Operator precedence — a real trap”The pipe operator binds lower than +, -, *, /, %, &&, || and ??, and higher than the ternary.
<!-- Concatenated first, then uppercased. Probably what you meant. -->{{ firstName + lastName | uppercase }}
<!-- NOT what most people expect: parsed as --><!-- isAdmin ? 'Access granted' : ('Access denied' | uppercase) -->{{ isAdmin ? 'Access granted' : 'Access denied' | uppercase }}
<!-- Correct -->{{ (isAdmin ? 'Access granted' : 'Access denied') | uppercase }}Parenthesise whenever precedence could be ambiguous. The ternary case fails silently — one branch is transformed and the other is not, which reads as a styling bug rather than a parsing one.
Pure and impure
Section titled “Pure and impure”Every pipe is pure by default. A pure pipe re-runs only when a primitive input changes, or when an object reference changes. Angular reuses the previous result otherwise, which is what makes pure pipes cheap enough to use in a list of a thousand rows.
The consequence: mutating an object property or an array element does not re-run a pure pipe, because the reference did not change.
@Pipe({ name: 'joinNamesImpure', pure: false })export class JoinNamesImpurePipe implements PipeTransform { transform(names: string[]): string { return names.join(', '); }}An impure pipe runs on every change detection cycle — for every element it appears on. In a 1,000-row list that is 1,000 invocations per pass, and there can be many passes per second.
Angular’s guidance is unambiguous: avoid impure pipes unless absolutely necessary; they can incur a significant performance penalty if used without care. The convention is to put Impure in the pipe’s name and class name so callers see the cost at the call site.
Almost always, the right fix is to stop mutating. Replace the array reference — this.names = [...this.names, name] — and a pure pipe works, cheaply.
AsyncPipe is impure, and legitimately so: it must react to emissions that have nothing to do with input identity. It also calls markForCheck() and unsubscribes on destroy, which is why it is preferable to a manual subscription.
Custom pipes
Section titled “Custom pipes”import { Pipe, PipeTransform } from '@angular/core';
@Pipe({ name: 'kebabCase' })export class KebabCasePipe implements PipeTransform { transform(value: string): string { return value.toLowerCase().replace(/ /g, '-'); }}Requirements: a name, and a transform method. Implement PipeTransform so TypeScript checks the shape.
Naming convention: camelCase name, no hyphens; PascalCase class name with Pipe appended.
Extra transform parameters become pipe arguments:
transform(value: string, format: 'short' | 'long'): string { /* ... */ }{{ title | myTransform: 'short' }}Extract the logic
Section titled “Extract the logic”Angular is explicit about this: do not inject a pipe class into a service. Pipes are template operators, not injectable services.
Put the transformation in a plain function and have both the pipe and any other caller use it:
export function toKebabCase(value: string): string { return value.toLowerCase().replace(/ /g, '-');}
// kebab-case.pipe.ts@Pipe({ name: 'kebabCase' })export class KebabCasePipe implements PipeTransform { transform(value: string): string { return toKebabCase(value); }}
// formatter.ts@Service()export class Formatter { formatSlug(title: string): string { return toKebabCase(title); }}The function is testable on its own, tree-shakable, and usable anywhere — and the pipe becomes a two-line adapter.
Pipe or computed?
Section titled “Pipe or computed?”Signals overlap with the classic use of pipes, and the choice is genuinely worth making rather than defaulting.
Use a computed when the transformation is specific to one component and depends on that component’s state. It is memoised, lazy, dependency-tracked, testable without a template, and it recomputes only when a dependency actually changed:
readonly visibleOrders = computed(() => this.orders().filter((o) => o.status === this.filter()),);Use a pure pipe when the transformation is reused across templates and is genuinely a view concern — formatting a value for display. Locale-aware formatting, a domain-specific number format, a relative-time renderer. Pipes are the better fit here precisely because they are declarative in the template and reusable without any component wiring.
Never use an impure pipe where a computed would do. It is the same work with none of the memoisation.
The rule that holds up: pipes format, computed derives.
Testing
Section titled “Testing”Test the extracted function directly. If you must test the pipe itself, instantiate it — no TestBed required:
it('kebab-cases a title', () => { expect(new KebabCasePipe().transform('Hello World')).toBe('hello-world');});For a pipe that injects a dependency (LOCALE_ID, a service), use TestBed.runInInjectionContext(() => new MyPipe()) or provide it and TestBed.inject it.
Common mistakes
Section titled “Common mistakes”| Mistake | Consequence | Fix |
|---|---|---|
Pipe not in imports |
“The pipe could not be found” | Add it |
| Missing parentheses with a ternary | One branch silently untransformed | Parenthesise |
| Mutating an array and expecting a pure pipe to re-run | Stale output | Replace the reference |
| Impure pipe to work around mutation | Runs on every check, per element | Fix the mutation instead |
| Impure pipe in a large list | Thousands of calls per pass | computed, or make it pure |
| Injecting a pipe into a service | Pipes are not services | Extract a plain function |
Expensive work in transform |
Multiplied across rows and passes | Memoise, or precompute |
JsonPipe left in production |
Serialises objects on every check | Debugging only |
| A pipe that fetches data | Called unpredictably; no error handling | Use resource / httpResource |
| Component-specific logic in a pipe | Ceremony for a single call site | computed |
Related pages
Section titled “Related pages”- Templates in Angular
- Signals and Angular Reactivity
- Change Detection and Zoneless Angular
- Angular Performance
- Pipes basics