How to create components that accept one or more bindable properties. You might know these as "props" if you are coming from other frameworks and libraries.
When creating components, sometimes you will want the ability for data to be passed into them instead of their host elements. The @bindable
decorator allows you to specify one or more bindable properties for a component.
The @bindable
attribute also can be used with custom attributes as well as custom elements. The decorator denotes bindable properties on components on the view model of a component.
This will allow our component to be passed in values. Our specified bindable property here is called loading
and can be used like this:
In the example above, we are binding the boolean literal true
to the loading
property.
Instead of literal, you can also bind another property (loadingVal
in the following example) to the loading
property.
As seen in the following example, you can also bind values without the loading.bind
part.
Aurelia treats attribute values as strings. This means when working with primitives such as booleans or numbers, they won't come through in that way and need to be coerced into their primitive type using a bindable setter or specifying the bindable type explicitly using bindable coercion.
The @bindable
decorator signals to Aurelia that a property is bindable in our custom element. Let's create a custom element where we define two bindable properties.
You can then use the component in this way,`<name-component first-name="John" last-name="Smith"></name-component>
By default, Aurelia will call a change callback (if it exists) which takes the bindable property name followed by Changed
added to the end. For example, firstNameChanged(newVal, previousVal)
would fire every time the firstName
bindable property is changed.
Due to the way the Aurelia binding system works, change callbacks will not be fired upon initial component initialization. If you worked with Aurelia 1, this behavior differs from what you might expect.
If you would like to call your change handler functions when the component is initially bound (like v1), you can achieve this the following way:
Like almost everything in Aurelia, you can configure how bindable properties work.
You can specify the binding mode using the mode
property and passing in a valid BindingMode
to it; @bindable({ mode: BindingMode.twoWay})
- this determines which way changes flow in your binding. By default, this will be BindingMode.oneWay
Please consult the binding modes documentation below to learn how to change the binding modes. By default, the binding mode for bindable properties will be one-way
You can change the name of the callback that is fired when a change is made @bindable({ callback: 'propChanged' })
Bindable properties support many different binding modes determining the direction the data is bound in and how it is bound.
By default, bindable properties will be one-way binding. This means values flow into your component but not back out of it (hence the name, one way).
Bindable properties without an mode
explicitly set will be one-way
by default. You can also explicitly specify the binding mode.
Unlike the default, the two-way binding mode allows data to flow in both directions. If the value is changed with your component, it flows back out.
Much like most facets of binding in Aurelia, two-way binding is intuitive. Instead of .bind
you use .two-way
if you need to be explicit, but in most instances, you will specify the type of binding relationship a bindable property is using with @bindable
instead.
Explicit two-way binding looks like this:
The myVal
variable will get a new value whenever the text input is updated. Similarly, if myVal
were updated from within the view model, the input would get the updated value.
When using .bind
for input/form control values such as text inputs, select dropdowns and other form elements. Aurelia will automatically create a two-way binding relationship. So, the above example using a text input can be rewritten to be value.bind="myVal"
, and it would still be a two-way binding.
In some cases, you want to make an impact on the value that is binding. For such a scenario, you can use the possibility of new set
.
Suppose you have a carousel
component in which you want to enable navigator
feature for it.
In version two, you can easily implement such a capability with the set
feature.
Define your property like this:
For set
part, we need functionality to check the input. If the value is one of the following, we want to return true
, otherwise, we return the false
value.
''
: No input for a standalone navigator
property.
true
: When the navigator
property set to true
.
"true"
: When the navigator
property set to "true"
.
So our function will be like this
Now, we should set truthyDetector
function as follows:
Although, there is another way to write the functionality too:
You can simply use any of the above four methods to enable/disable your feature. As you can see, set
can be used to transform the values being bound into your bindable property and offer more predictable results when dealing with primitives like booleans and numbers.
By default, you'll find yourself work with binable and field most of the time, like the examples given above. But there' cases where it makes sense to have bindable as a getter, or a pair of getter/setter to do more logic when get/set.
For example, a component card nav that allow parent component to query its active status. With bindable on field, it would be written like this:
Note that because active
value needs to computed from other variables, we have to "actively" call setActive
. It's not a big deal, but sometimes not desirable.
For cases like this, we can turn active
into a getter, and decorate it with bindable, like the following:
Simpler, since the value of active
is computed, and observed based on the properties/values accessed inside the getter.
The bindable setter section shows how to adapt the value is bound to a @bindable
property. One common usage of the setter is to coerce the values that are bound from the view. Consider the following example.
Without any setter for the @bindable
num we will end up with the string '42'
as the value for num
in MyEl
. You can write a setter to coerce the value. However, it is a bit annoying to write setters for every @bindable
.
To address this issue, Aurelia 2 supports type coercion. To maintain backward compatibility, automatic type coercion is disabled by default and must be enabled explicitly.
There are two relevant configuration options.
enableCoercion
The default value is false
; that is Aurelia 2 does not coerce the types of the @bindable
by default. It can be set to true
to enable the automatic type-coercion.
coerceNullish
The default value is false
; that is Aurelia2 does not coerce the null
and undefined
values. It can be set to true
to coerce the null
and undefined
values as well. This property can be thought of as the global counterpart of the nullable
property in the bindable definition (see Coercing nullable values section).
Additionally, depending on whether you are using TypeScript or JavaScript for your app, there can be several ways to use automatic type coercion.
For TypeScript development, this gets easier when the emitDecoratorMetadata
configuration property in tsconfig.json
is set to true
. When this property is set, and the @bindable
properties are annotated with types, there is no need to do anything else; Aurelia 2 will do the rest.
If, for some reason, you cannot do that, then refer to the next section.
For JavaScript development, you need to specify the explicit type
in the @bindable
definition.
The rest of the document is based on TypeScript examples. However, we trust that you can transfer that knowledge to your JavaScript codebase if necessary.
Currently, coercing four primitive types are supported out of the box. These are number
, string
, boolean
, and bigint
. The coercion functions for these types are respectively Number(value)
, String(value)
, Boolean(value)
, and BigInt(value)
.
Be mindful when dealing with bigint
as the BigInt(value)
will throw if the value
cannot be converted to bigint; for example null
, undefined
, or non-numeric string literal.
It is also possible to coerce values into instances of classes. There are two ways how that can be done.
coerce
methodYou can define a static method named coerce
in the class used as a @bindable
type. This method will be called by Aurelia2 automatically to coerce the bound value.
This is shown in the following example with the Person
class.
According to the Person#coercer
implementation, for the example above MyEl#person
will be assigned an instance of Person
that is equivalent to new Person('john', null)
.
@coercer
decoratorAurelia2 also offers a @coercer
decorator to declare a static method in the class as the coercer. The previous example can be rewritten as follows using the @coercer
decorator.
With the @coercer
decorator, you are free to name the static method as you like.
To maintain backward compatibility, Aurelia2 does not attempt to coerce null
and undefined
values. We believe that this default choice should avoid unnecessary surprises and code breaks when migrating to newer versions of Aurelia.
However, you can explicitly mark a @bindable
to be not nullable.
When nullable
is set to false
, Aurelia2 will try to coerce the null
and undefined
values.
set
and auto-coercionIt is important to note that an explicit set
(see bindable setter) function is always prioritized over the type
. In fact, the auto-coercion is the fallback for the set
function. Hence whenever set
is defined, the auto-coercion becomes non-operational.
However, this gives you an opportunity to:
Override any of the default primitive type coercing behavior, or
Disable coercion selectively for a few selective @bindable
by using a noop
function for set
.
Aurelia2 already exposes a noop
function saving your effort to write such boring functions.
When using TypeScript, usages of union types are not rare. However, using union types for @bindable
will deactivate the auto-coercion.
For the example above, the type metadata supplied by TypeScript will be Object
disabling the auto-coercion.
To coerce union types, you can explicitly specify a type
.
However, using a setter would be more straightforward to this end.
Even though using a noop
function for set
function is a straightforward choice, Object
can also be used for type
in the bindable definition to disable the auto-coercion for selective @bindable
s (that is when the automatic type-coercion is enabled).
Attribute transferring is a way to relay the binding(s) on a custom element to its child element(s).
As an application grows, the components inside it also grow. Something that starts simple, like the following component
with the template
can quickly grow out of hand with a number of needs for configuration: aria, type, min, max, pattern, tooltip, validation etc...
After a while, the FormInput
component above will become more and more like a relayer to transfer the bindings from outside, to the elements inside it. This often results in an increase in the number of @bindable
. While this is fine, you end up with components that have a lot of boilerplate.
And the usage of our component would look like this:
to be repeated like this inside:
To juggle all the relevant pieces for such a task isn't difficult, but somewhat tedious. With attribute transferring, which is roughly close to object spreading in JavaScript, the above template should be as simple as:
, which reads like this: for some bindings on <form-input>
, change the targets of those bindings to the <input>
element inside it.
To transfer attributes & bindings from a custom element, there are two steps:
Set capture
to true
on a custom element via @customElement
decorator:
Or use the capture
decorator from aurelia
package if you don't want to declare the customElement
decorator and have to specify your name and template values.
As the name suggests, this is to signal the template compiler that all the bindings & attributes, with some exceptions, should be captured for future usage.
Spread the captured attributes onto an element
Using the ellipsis syntax which you might be accustomed to from Javascript, we can spread our attributes onto an element proceeding the magic variable $attrs
Spread attributes and overriding specific ones
In case you want to spread all attributes while explicitly overriding individual ones, make sure these come after the spread operator.
It's recommended that this feature should not be overused in multi-level capturing & transferring. This is often known as prop-drilling in React and could have a bad effect on the overall & long-term maintainability of an application. It's probably healthy to limit the max level of transferring to 2.
Aurelia conventions enable the setting of capture
metadata from the template via <capture>
tag, like the following example:
Sometimes it is desirable to capture only certain attributes on a custom element. Aurelia supports this via 2nd form of the custom element capture
value: a function that takes 1 parameter, which is the attribute name, and returns a boolean to indicate whether it should be captured.
What attributes are captured
Everything except the template controller and custom element bindables are captured.
A usage example is as follows:
What is captured:
value.bind="extraComment"
class="form-control"
style="background: var(--theme-purple)"
tooltip="Hello, ${tooltip}"
What is not captured:
if.bind="needsComment"
(if
is a template controller)
label.bind="label"
(label
is a bindable property)
How will attributes be applied in ...$attrs
Attributes that are spread onto an element will be compiled as if it was declared on that element.
This means .bind
command will work as expected when it's transferred from some element onto some element that uses .two-way
for .bind
.
It also means that spreading onto a custom element will also work: if a captured attribute targets a bindable property of the applied custom element. An example:
if value
is a bindable property of my-input
, the end result will be a binding that connects the message
property of the corresponding app.html
view model with <my-input>
view model value
property. The binding mode is also preserved like normal attributes.