Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Commit f48a349

Browse files
committed
docs(guide/filters): clarify when filters are executed
Closes #14590
1 parent 976d15f commit f48a349

File tree

1 file changed

+11
-1
lines changed

1 file changed

+11
-1
lines changed

docs/content/guide/filter.ngdoc

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,16 @@ Filters may have arguments. The syntax for this is
3131
E.g. the markup `{{ 1234 | number:2 }}` formats the number 1234 with 2 decimal points using the
3232
{@link ng.filter:number `number`} filter. The resulting value is `1,234.00`.
3333

34+
### When filters are executed
35+
36+
In templates, filters are only executed when their inputs have changed. This is more performant than executing
37+
a filter on each {@link ng.$rootScope.Scope#$digest `$digest`} as is the case with {@link guide/expression expressions}.
38+
However, this is only true for filters that take [primitive values](https://developer.mozilla.org/docs/Glossary/Primitive)
39+
as inputs. Filters that receive [Objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Objects)
40+
as input are executed on each `$digest`, as it would be too costly to track if they have changed.
41+
42+
This means custom filters should only rely on their inputs and not on external state (e.g. other Angular services).
43+
See {@link guide/filter#creating-custom-filters Creating custom filters} below for more information.
3444

3545
## Using filters in controllers, services, and directives
3646

@@ -141,7 +151,7 @@ text upper-case.
141151
</example>
142152

143153

144-
## Stateful filters
154+
### Stateful filters
145155

146156
It is strongly discouraged to write filters that are stateful, because the execution of those can't
147157
be optimized by Angular, which often leads to performance issues. Many stateful filters can be

0 commit comments

Comments
 (0)