Filters in Depth

Synopsis

A Vue.js filter is essentially a function that takes a value, processes it, and then returns the processed value. In the markup it is denoted by a single pipe (|) and can be followed by one or more arguments:

1	<element directive="expression \| filterId [args...]"></element>

Examples

Filters must be placed at the end of a directive’s value:

1	<span v-text="message \| capitalize"></span>

You can also use them inside mustache-style bindings:

1	<span>{{message \| uppercase}}</span>

Multiple filters can be chained together:

1	<span>{{message \| lowercase \| reverse}}</span>

Arguments

Some filters can take optional arguments. Simply add arguments separated by spaces:

1	<span>{{order \| pluralize st nd rd th}}</span>

1	<input v-on="keyup: submitForm \| key enter">

For their specific use of the above examples see the full list of built-in filters.

Writing a Custom Filter

You can register a custom filter with the global Vue.filter() method, passing in a filterID and a filter function. The filter function takes a value as the argument and returns the transformed value:

1
2
3

Vue.filter('reverse', function (value) {
    return value.split('').reverse().join('')
})

<!--
    'abc' => 'cba'
-->
<span v-text="message | reverse"></span>

The filter function also receives any inline arguments:

1
2
3

Vue.filter('wrap', function (value, begin, end) {
    return begin + value + end
})

<!--
    'hello' => 'before hello after'
-->
<span v-text="message | wrap before after"></span>

Computed Filters

When a filter is invoked, its this context is set to the ViewModel instance that is invoking it. This allows it to output dynamic results based on the state of the owner ViewModel. In such case, we need to track these accessed properties so that when they change, directives that are using this filter will be re-evaluated.

For example:

Vue.filter('concat', function (value, key) {
    // `this` points to the VM invoking the filter
    return value + this[key]
})

1 2	<input v-model="userInput"> <span>{{msg \| concat userInput}}</span>

Filters that relies on the state of the ViewModel that is calling it are referred to as computed filters. For this simple example above, you can achieve the same result with just an expression, but for more complicated procedures that need more than one statements, you need to put them either in a computed property or a computed filter.

For example, the built-in filterBy and orderBy filters are both computed filters that perform non-trivial work on the Array being passed in. For custom filters, Vue.js checks for computed filters by looking for references to this in a filter’s function body. Any directive that uses a computed filter will be automatically compiled as an expression so its filters are included in the dependency collection process.

If you find the concept of computed filters confusing at the moment, don’t worry. It is handled automatically by Vue.js and you don’t really need to know how it works to leverage it. As you get familiar with more related concepts, it will all make sense.