|
| 1 | +# Creating pipes for custom data transformations |
| 2 | + |
| 3 | +Create custom pipes to encapsulate transformations that are not provided with the built-in pipes. |
| 4 | +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. |
| 5 | + |
| 6 | +## Marking a class as a pipe |
| 7 | + |
| 8 | +To mark a class as a pipe and supply configuration metadata, apply the [`@Pipe`](/api/core/Pipe "API reference for Pipe") [decorator](/guide/glossary#decorator--decoration "Definition for decorator") to the class. |
| 9 | + |
| 10 | +Use [UpperCamelCase](guide/glossary#case-types "Definition of case types") (the general convention for class names) for the pipe class name, and [camelCase](guide/glossary#case-types "Definition of case types") for the corresponding `name` string. |
| 11 | +Do not use hyphens in the `name`. |
| 12 | + |
| 13 | +For details and more examples, see [Pipe names](guide/styleguide#pipe-names "Pipe names in the Angular coding style guide"). |
| 14 | + |
| 15 | +Use `name` in template expressions as you would for a built-in pipe. |
| 16 | + |
| 17 | +<div class="alert is-important"> |
| 18 | + |
| 19 | +* Include your pipe in the `declarations` field of the `NgModule` metadata in order for it to be available to a template. See the `app.module.ts` file in the example application (<live-example></live-example>). For details, see [NgModules](guide/ngmodules "NgModules introduction"). |
| 20 | +* Register your custom pipes. The [Angular CLI](cli "CLI Overview and Command Reference") [`ng generate pipe`](cli/generate#pipe "ng generate pipe in the CLI Command Reference") command registers the pipe automatically. |
| 21 | + |
| 22 | +</div> |
| 23 | + |
| 24 | +## Using the PipeTransform interface |
| 25 | + |
| 26 | +Implement the [`PipeTransform`](/api/core/PipeTransform "API reference for PipeTransform") interface in your custom pipe class to perform the transformation. |
| 27 | + |
| 28 | +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. |
| 29 | + |
| 30 | +## Example: Transforming a value exponentially |
| 31 | + |
| 32 | +In a game, you might want to implement a transformation that raises a value exponentially to increase a hero's power. |
| 33 | +For example, if the hero's score is 2, boosting the hero's power exponentially by 10 produces a score of 1024. |
| 34 | +Use a custom pipe for this transformation. |
| 35 | + |
| 36 | +The following code example shows two component definitions: |
| 37 | + |
| 38 | +* The `exponential-strength.pipe.ts` component defines a custom pipe named `exponentialStrength` with the `transform` method that performs the transformation. |
| 39 | + It defines an argument to the `transform` method (`exponent`) for a parameter passed to the pipe. |
| 40 | +* The `power-booster.component.ts` component demonstrates how to use the pipe, specifying a value (`2`) and the exponent parameter (`10`). |
| 41 | + |
| 42 | +<code-tabs> |
| 43 | + <code-pane header="src/app/exponential-strength.pipe.ts" path="pipes/src/app/exponential-strength.pipe.ts"></code-pane> |
| 44 | + <code-pane header="src/app/power-booster.component.ts" path="pipes/src/app/power-booster.component.ts"></code-pane> |
| 45 | +</code-tabs> |
| 46 | + |
| 47 | +The browser displays the following: |
| 48 | + |
| 49 | +<code-example language="none"> |
| 50 | + |
| 51 | +Power Booster |
| 52 | + |
| 53 | +Superpower boost: 1024 |
| 54 | + |
| 55 | +</code-example> |
| 56 | + |
| 57 | +<div class="alert is-helpful"> |
| 58 | + |
| 59 | +To examine the behavior of the `exponentialStrength` pipe in the <live-example></live-example>, change the value and optional exponent in the template. |
| 60 | + |
| 61 | +</div> |
| 62 | + |
| 63 | +@reviewed 2022-02-10 |
0 commit comments