---
url: /reference/items/DataBind/js-api.md
---
# JS API
The `DataBind` component can be used to keep a value in sync between multiple DOM elements.
## Options
### `prop`
* Type: `string`
* Default: `'textContent'`
The default value for the `prop` option depends on the type of the targeted element. If the element is an input, a textarea, or a select, the default prop will be one of the following:
* `valueAsDate` for ` `
* `valueAsNumber` for ` `
* `value` for all other inputs
* for `` elements, the prop option is not used and the value will always be the selected option(s)
If the option is explicitly set with the `data-option-prop` attribute, it will override the default behavior.
### `immediate`
* Type: `boolean`
* Default: `false`
Propagates the component's value on mount to other components in the same group. Inside a [`DataScope`](../DataScope/index.md), only [`DataModel`](../DataModel/index.md) sources hydrate the keyed value; immediate keyed `DataBind`, `DataComputed` and `DataEffect` components are subscribers and receive the hydrated values once all sources are collected. An immediate keyed subscriber mounted after hydration — for example inside content inserted by [`data-bind:if`](#conditional-rendering-with-data-bind-if) — syncs with the current scoped value on mount instead of waiting for the next update.
### `group`
* Type: `string`
* Default: `''`
The `group` option is used to group instances together. All related instances will be updated when the value changes. Inside a [`DataScope`](../DataScope/index.md), an omitted group inherits the scope's group and remains isolated from other scopes.
### `key`
* Type: `string`
* Default: the native form control `name`, when scoped
A keyed value updates only bindings with the same key while notifying unkeyed subscribers. Keys are local to a `DataScope`; unscoped bindings preserve scalar group behavior.
When using it with multiple checkboxes or a multiple select, use the `[]` suffix to push each selected value into an array. See the [checkboxes example](../DataModel/examples.md#checkboxes) for more details.
## Virtual bindings
Virtual `data-bind:*` attributes update several parts of an element from the same value. When an element has one or more virtual bindings, they replace the default single `textContent` or property update.
| Syntax | Behavior |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-bind:prop.` | Assigns the DOM property. |
| `data-bind:attr.` | Removes the attribute for `false`, `null`, or `undefined`; writes an empty attribute for `true`; otherwise writes the stringified value. |
| `data-bind:class.` | Toggles the class according to the result's boolean value. |
| `data-bind:style.` | Clears the style for `false`, `null`, or `undefined`; otherwise writes the stringified value. |
| `data-bind:text` | Assigns `textContent`. |
| `data-bind:if` | On a `` element only: inserts a clone of the template content after the template for a truthy result, removes it for a falsy result. |
A non-empty attribute value is a JavaScript expression with access to `value`, `target`, and `$data`. An empty attribute passes through the current value. Bindings are read when first used; changing their attributes afterward is not supported. See the [virtual bindings examples](./examples.md#virtual-bindings) for a live example of each binding.
Use kebab-case for camel-cased DOM properties because HTML attribute names are case-insensitive, for example `data-bind:prop.tab-index` targets `tabIndex`.
For ARIA attributes, explicitly stringify booleans when `"false"` must remain present, for example `data-bind:attr.aria-selected="String(value === 'overview')"`.
Expression errors are reported without interrupting updates to the other bindings, matching `DataComputed` and `DataEffect` behavior.
### Conditional rendering with `data-bind:if`
The `data-bind:if` binding adds or removes DOM nodes based on the bound value, like `v-if` in Vue or `x-if` in Alpine.js. It must be set on a `` element: the template stays in the DOM and keeps the binding alive, while its content is cloned and inserted after the template when the expression is truthy, and removed when it is falsy.
```html
Results for
```
Each insertion is a fresh clone of the template content, so components inside are mounted again and any state they held is reset on every toggle. Give nested keyed bindings the [`immediate` option](#immediate) so they sync with the current scoped value when they mount, as in the `` element above. Template content is inert until the first truthy value, so conditional content never flashes before the data is ready.
Use `data-bind:if` when the element must not exist in the DOM — a form control that must not submit, an expensive subtree, or content that must be absent from the accessibility tree. To show or hide an element in place, prefer the cheaper `data-bind:attr.hidden`, `data-bind:class.` or `data-bind:style.display` bindings, which keep the element and its state.
### Wrapping the DOM change with the `dom-update` event
Before `data-bind:if` inserts or removes the template content, the component emits the bubbling `dom-update` protocol event — the shared announcement components use before an imminent DOM change. Its `detail` carries the new logical state as `isPresent` and a `wrap(runner)` function: a listener can call `wrap()` to substitute what runs the DOM change. The runner is either a function receiving an `apply()` callback that performs the actual insertion or removal, or a duck-typed transitioner exposing an `update(mutate)` method — like [`MotionView`](/reference/items/MotionView/) from `@studiometa/ui-motion` — whose `update()` receives the callback.
```ts
interface DomUpdateTransitioner {
update(mutate: () => void | Promise): void | Promise;
}
type DomUpdateRunner = ((apply: () => void) => void | Promise) | DomUpdateTransitioner;
```
* `wrap()` is only valid synchronously, while the event dispatches — later calls warn and are ignored.
* A single runner runs the change: the last `wrap()` call wins.
* The DOM change is never lost: without a runner it runs synchronously as before, and a rejected runner is reported with a warning before the change is applied anyway if the runner did not call `apply()`.
Because the removal also goes through the runner, the removed nodes stay in the DOM until the runner calls `apply()` — this is what enables exit animations for removed template content. And because the event bubbles, an enclosing `MotionView` wraps any `dom-update` announced in its subtree with no wiring at all:
```html
…
```
For cross-subtree topologies — when the transitioner does not enclose the template — an ancestor [`Action`](../Action/index.md) can catch the event and route it across the page, the same pattern as the [`Timer`](../Timer/index.md) events:
```html {4}
…
```
## Properties
### `value`
Get and set the value on the current instance. This is a getter and setter alias for the `set(value)` and [`get()`](#get) methods.
### `target`
* Type: `HTMLElement`
* Readonly
The targeted DOM element.
### `multiple`
* Type: `boolean`
* Readonly
Whether new values should be pushed to an array instead of a single value. This is enabled by adding the `[]` suffix to the [`group` option](#group).
## Methods
### `set(value: DataValue, dispatch = true)`
Set the value for the current instance and dispatch it to others if the second parameter `dispatch` is set to `true` (default).
`DataValue` accepts `boolean`, `string`, `string[]`, `number`, `Date`, `null`, or `undefined`.
**Params**
* `value` (`DataValue`): the value to set
* `dispatch` (`boolean`, defaults to `true`): whether to dispatch the value to other related instances
The mutation helpers below are available on `DataBind` and `DataModel`. They are not supported on computed values or effects.
### `toggle(onValue = true, offValue = false)`
Toggle between two values and dispatch the result to the group. Single checkboxes support the default boolean values; custom values require a target that can represent them without coercing them to `checked`. Radio inputs are not supported.
Custom values can describe disclosure state without repeating comparison logic in an Action:
```html
Toggle
```
### `increment(step = 1)`
Convert the current value to a number, increment it by `step`, and dispatch the result. A non-numeric current value starts at `0`. Pass a negative step to decrement. Date inputs are not supported.
```html
Count: 0
```
### `cycle(values)`
Select and dispatch the value following the current value in the given array. The method wraps to the first value; an unknown current value also selects the first value. An empty array does nothing.
```html
Status: draft
```
### `get()`
Get the value for the current instance.