Bind properties and modifiers

Most data-bind:* attributes set an element attribute or property, but some bind properties and modifier characters add extra behaviour.

Common bind properties

Here are the bind properties we will use most often:

• text sets textContent
• html sets innerHTML
• value sets form values
• class adds or toggles class names
• list binds a nested iterable into a contained list template
• table binds table data into a <table>
• remove removes an element conditionally
• any other property name is treated as a normal attribute name

text and html

HTML:

<p data-bind:text="name">Guest</p>
<div data-bind:html="bioHtml">Plain text bio</div>

If we bind name, the element's text content changes. If we bind bioHtml, the element's inner HTML changes.

Important

html inserts HTML, so it should only be used with trusted content to avoid cross-site scripting (XSS). If we're only using plain text, stick to text.

class

Without a modifier, data-bind:class adds a class name.

HTML:

<div class="panel" data-bind:class="extraClass"></div>

If we bind extraClass to featured, the element ends up with class="panel featured".

The : token modifier

The colon modifier toggles a token within a token list, most commonly a class name.

HTML:

<li data-bind:class=":isSelected selected"></li>

If isSelected is truthy, selected is added. If it is falsey, selected is removed.

If we omit the explicit token name:

<li data-bind:class=":status"></li>

the bound value itself becomes the token.

The ? boolean modifier

The question mark toggles an attribute based on truthiness.

HTML:

<button data-bind:disabled="?isArchived">Archive</button>

If isArchived is truthy, the button gets disabled. Otherwise, that attribute is removed.

The ?! inverse boolean modifier

HTML:

<button data-bind:disabled="?!isEditable">Save</button>

Here we can read it as: "disable the button when isEditable is not truthy".

Boolean equality checks with =

We can also make the boolean modifier compare against a specific string value.

HTML:

<label>
	<input type="radio" name="size" value="s" data-bind:checked="?size=s" />
	<span>Small</span>
</label>
<label>
	<input type="radio" name="size" value="m" data-bind:checked="?size=m" />
	<span>Medium</span>
</label>
<label>
	<input type="radio" name="size" value="l" data-bind:checked="?size=l" />
	<span>Large</span>
</label>

If size is "m", the middle radio becomes checked.

This is especially handy for radios, tab state, and selected options.

The @ attribute reference modifier

The @ modifier lets us reuse an existing attribute value instead of repeating ourselves.

HTML:

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

This behaves as though we had written:

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

There is also a shorthand:

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

which means the same thing as @name.

Combining modifiers

Modifiers can be combined in one expression.

HTML:

<input
	name="size"
	value="m"
	data-bind:checked="?@name=@value"
	data-rebind />

Here we are saying:

• look up the bind key from name
• compare it with the current element's value
• add checked when they match

data-rebind

By default, once a bind attribute has been used, DomTemplate removes it to prevent any further bind functions from affecting the element again.

If we want the property to remain bindable, add data-rebind.

HTML:

<button data-bind:disabled="?isBusy" data-rebind>Save</button>

This is useful when we bind the same area more than once during one request.

data-bind:remove

remove is a special bind property that removes the element itself rather than mutating one of its attributes.

HTML:

<p>
	<span data-bind:remove="?isDay">It's night-time.</span>
	<span data-bind:remove="?!isDay">It's daytime.</span>
</p>

If isDay is true, the first span disappears. If isDay is false, the second span disappears.

data-bind:list

This property binds a nested iterable into a child list template.

HTML:

<section data-bind:list="orderList">
	<ul>
		<li data-list data-bind:text="id">Order</li>
	</ul>
</section>

When the key orderList is bound, the contained list template is used.

We will cover that properly in the binding lists section.

data-bind:table

This property tells DomTemplate where table-shaped data should go.

HTML:

<table data-bind:table="sales"></table>

We will go through the supported table data shapes in the binding tables section.

---

Now that the element-level behaviour is clear, move on to binding lists for the part of the library that does the heavy lifting with repeated markup.