Getting started

  1. How KO works and what benefits it brings
  2. Downloading and installing

Observables

  1. Creating view models with observables
  2. Working with observable arrays

Computed observables

  1. Using computed observables
  2. Writable computed observables
  3. How dependency tracking works
  4. Pure computed observables
  5. Reference

Bindings

Controlling text and appearance

  1. The visible and hidden bindings
  2. The text binding
  3. The html binding
  4. The class and css bindings
  5. The style binding
  6. The attr binding

Control flow

  1. The foreach binding
  2. The if and ifnot bindings
  3. The with and using bindings
  4. The let binding
  5. The component binding
  6. Binding lifecycle events

Working with form fields

  1. The click binding
  2. The event binding
  3. The submit binding
  4. The enable and disable bindings
  5. The value binding
  6. The textInput binding
  7. The hasFocus binding
  8. The checked binding
  9. The options binding
  10. The selectedOptions binding
  11. The uniqueName binding

Rendering templates

  1. The template binding

Binding syntax

  1. The data-bind syntax
  2. The binding context

Creating custom bindings

  1. Creating custom bindings
  2. Controlling descendant bindings
  3. Supporting virtual elements
  4. Custom disposal logic
  5. Preprocessing: Extending the binding syntax

Components

  1. Overview: What components and custom elements offer
  2. Defining and registering components
  3. The component binding
  4. Using custom elements
  5. Advanced: Custom component loaders

Further techniques

  1. Loading and saving JSON data
  2. Extending observables
  3. Deferred updates
  4. Rate-limiting observables
  5. Unobtrusive event handling
  6. Using fn to add custom functions
  7. Microtasks
  8. Asynchronous error handling

Plugins

  1. The mapping plugin

More information

  1. Browser support
  2. Getting help
  3. Links to tutorials & examples
  4. Usage with AMD using RequireJs (Asynchronous Module Definition)

The "text" binding

Purpose

The text binding causes the associated DOM element to display the text value of your parameter.

Typically this is useful with elements like <span> or <em> that traditionally display text, but technically you can use it with any element.

Example

Today's message is: <span data-bind="text: myMessage"></span>

<script type="text/javascript">
    var viewModel = {
        myMessage: ko.observable() // Initially blank
    };
    viewModel.myMessage("Hello, world!"); // Text appears
</script>

Parameters

  • Main parameter

    Knockout sets the element’s content to a text node with your parameter value. Any previous content will be overwritten.

    If this parameter is an observable value, the binding will update the element’s text whenever the value changes. If the parameter isn’t observable, it will only set the element’s text once and will not update it again later.

    If you supply something other than a number or a string (e.g., you pass an object or an array), the displayed text will be equivalent to yourParameter.toString()

  • Additional parameters

    • None

Note 1: Using functions and expressions to detemine text values

If you want to detemine text programmatically, one option is to create a computed observable, and use its evaluator function as a place for your code that works out what text to display.

For example,

The item is <span data-bind="text: priceRating"></span> today.

<script type="text/javascript">
    var viewModel = {
        price: ko.observable(24.95)
    };
    viewModel.priceRating = ko.pureComputed(function() {
        return this.price() > 50 ? "expensive" : "affordable";
    }, viewModel);
</script>

Now, the text will switch between “expensive” and “affordable” as needed whenever price changes.

Alternatively, you don’t need to create a computed observable if you’re doing something simple like this. You can pass an arbitrary JavaScript expression to the text binding. For example,

The item is <span data-bind="text: price() > 50 ? 'expensive' : 'affordable'"></span> today.

This has exactly the same result, without requiring the priceRating computed observable.

Note 2: About HTML encoding

Since this binding sets your text value using a text node, it’s safe to set any string value without risking HTML or script injection. For example, if you wrote:

viewModel.myMessage("<i>Hello, world!</i>");

… this would not render as italic text, but would render as literal text with visible angle brackets.

If you need to set HTML content in this manner, see the html binding.

Note 3: Using “text” without a container element

Sometimes you may want to set text using Knockout without including an extra element for the text binding. For example, you’re not allowed to include other elements within an option element, so the following will not work.

<select data-bind="foreach: items">
    <option>Item <span data-bind="text: name"></span></option>
</select>

To handle this, you can use the containerless syntax, which is based on comment tags.

<select data-bind="foreach: items">
    <option>Item <!--ko text: name--><!--/ko--></option>
</select>

The <!--ko--> and <!--/ko--> comments act as start/end markers, defining a “virtual element” that contains the markup inside. Knockout understands this virtual element syntax and binds as if you had a real container element.

Note 4: About an IE 6 whitespace quirk

IE 6 has a strange quirk whereby it sometimes ignores whitespace that immediately follows an empty span. This has nothing directly to do with Knockout, but in case you do want to write:

Welcome, <span data-bind="text: userName"></span> to our web site.

… and IE 6 renders no whitespace before the words to our web site, you can avoid the problem by putting any text into the <span>, e.g.:

Welcome, <span data-bind="text: userName">&nbsp;</span> to our web site.

Other browsers, and newer versions of IE, don’t have this quirk.

Dependencies

None, other than the core Knockout library.