Modifier characters

Bind key modifier characters are special characters that you can add to an element's bind key to add special behaviour.

An example of what this may look like is <button name="do" value="delete" data-bind:disabled="?!isActive">Delete</button>, and <img src="/photo.jpg" data-bind:class=":size" />.

Token modifier :

Adding a colon as the first character of the bind key will have the effect of toggling a token's presence, such as in the element's classList.

The "token" in this case is represented by a DOMTokenList object in the underlying DOM implementation, and represents a set of space-separated tokens. Such a set is returned by Element.classList or HTMLLinkElement.relList, and many others. See DOMTokenList on MDN for more information.

It's very common in web user interfaces to want to add or remove a string token to the class attribute. Using the DOM, this can be achieved by doing $element->classList->add("selected");, for example.

HTML:

<img src="/cat.jpg" alt="My cat" data-bind:class=":imageCategory" />

This image element will add a token to the class attribute according to the value of imageCategory.

PHP:

function example(DocumentBinder $binder):void {
	$binder->bindKeyValue("imageCategory", "cat-photo");
}

Output HTML:

<img src="/cat.jpg" alt="My cat" class="cat-photo" />

Space-separated token modifier

The name of the class you wish to toggle can be added to the HTML, using a space to separate it from the bind key.

HTML:

<img class="sidebar" src="/cat.jpg" alt="My cat" data-bind:class=":deletedAt deleted" />

This image element will add the deleted token to the class attribute if the deletedAt bind key is not falsey.

PHP:

function example(DocumentBinder $binder, DateTime|null $dateOfDeletion):void {
	$binder->bindKeyValue("deletedAt", $dateOfDeletion);
}

Output HTML:

<img class="sidebar deleted" src="/cat.jpg" alt="My cat" />

or if the $dateOfDeletion variable is null:

<img class="sidebar" src="/cat.jpg" alt="My cat" />

Attribute modifier @

The at character can be added as the first character of the bind key to indicate that the bind key should reference another attribute's value. This feature exists to remove repetition in the HTML - if an element has a name attribute with the value of country, and the bind key should also be country, the name attribute can be referenced using the attribute modifier. This means that if the name attribute's value ever changes, so will the bind key.

HTML:

<input name="country" data-bind:value="@name" />

<!-- which is synonymous to: <input name="country" data-bind:value="country" /> -->

PHP:

function example(DocumentBinder $binder):void {
	$binder->bindKeyValue("country", "TW");
}

Output HTML:

<input name="country" value="TW" />

As it is so common to use the name attribute's value as the bind attribute value, a shorthand was introduced in v3.4.1 allowing the single @ character to be used in place of @name.

Example HTML:

<input name="country" data-bind:value="@" />

Boolean modifier ?

Adding a question mark as the first character of the bind key can be used to toggle the presence of any attribute, depending on whether the bound value is truthy.

For example, data-bind:disabled="?deletedAt can be used to toggle the disabled attribute on the element when the deletedAt value is anything that loosely equals true.

HTML:

<button name="do" value="delete" data-bind:disabled="?deletedAt">Delete me</button>

PHP:

function example(DocumentBinder $binder, DateTime|null $deletedAt):void {
	$binder->bindKeyValue("deletedAt", $deletedAt);
}

Output HTML:

<button name="do" value="delete" disabled>Delete me</button>

or if the $deletedAt variable is null:

<button name="do" value="delete">Delete me</button>

Inverse boolean modifier ?!

The boolean modifier checks for a truthy value, but this can be inverted to check for a falsey value by adding an exclamation mark after the question mark. This is useful for when you only want to add an attribute when a value is falsey, for example data-bind:disabled="?!active" will add the disabled attribute when the active bind key is falsey.

Boolean value modifier =

This modifier character is currently in development, and will be released with the next version. It's intended to make it easier to add the checked attribute to a set of radio buttons.

Removing elements with a boolean modifier

It's possible to remove an element from the document when a certain condition is true/truthy by marking the element with the data-bind:remove attribute. If the boolean modifier is triggered, the element will be removed from the document.

The inverse logic can be applied by adding an exclamation mark (!) to the start of the bind value.

In this example, a bound object has an isDay boolean property, and the appropriate span is removed from the document, leaving the correct sentence behind:

<p id="day-or-night">Is it day or night? <span data-bind:remove="?isDay">It's nighttime!</span><span data-bind:remove="?!isDay">It's daytime!</span></p>

If the bound object has a truthy isDay property, the span containing "It's nighttime" will be removed, and the span containing "It's daytime" will persist.

---

Next, learn how to inject data into HTML with {{curly braces}}.