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)

v3.0.0 Upgrade Notes

Knockout.js takes backward compatibility seriously. If you’re using a recent v2.x build, you will typically be able to drop in Knockout v3.0.0 without having to make any changes to your application code. Version 3.0.0 is intended to be fully backward-compatible except for a few carefully chosen design changes that enable major new features or fix longstanding issues.

1. Computed properties now notify only when their value changes

In Knockout v2.x, ko.computed properties would issue a “change” notification to their subscribers whenever they re-evaluated, even if the evaluation result was clearly identical to the previous one.

Many Knockout developers found this inconvenient because it caused unnecessary re-processing or duplicate actions. By popular demand we’ve changed the default behavior so that ko.computed does not issue “change” notifications after re-evaluation if the new value is definitely identical to the previous one (i.e., it’s a primitive - string/boolean/number/null/undefined - and equals the previous value).

This makes ko.computed consistent with ko.observable, which has always suppressed notifications if you reassign the same primitive value to it.

Restoring the earlier behavior

If you have a computed property that requires the v2.x behavior, i.e., you want repeated notifications even if the computed value is primitive and unchanged, you can enable this as follows:

myComputed.extend({ notify: 'always' });

2. Bindings are now refreshed independently

In Knockout v2.x, all bindings on the same element would refresh at the same time. Consider the following example:

<input type="checkbox" data-bind="visible: showTerms, checked: acceptsTerms" />

If your viewmodel changes acceptsTerms, then of course Knockout will re-run the checked binding to update the checkbox in the UI. But what you might not have realised is that, in v2.x, Knockout would also re-run the visible binding even though showTerms hasn’t changed. Although this usually caused no problems, it could lead to surprising bugs in advanced scenarios with custom binding handlers.

Knockout v3 has a greatly improved binding mechanism that refreshes all bindings independently and only when necessary. This improves performance and eliminates a whole category of potential problems with cross-binding dependencies. This change will only affect you if your code relies on v2.x’s undocumented implementation detail of cross-binding dependencies. In this case, you will need to update your code to stop relying on the obsolete behavior.

3. optionsCaption now HTML-encodes its output

In v2.x, optionsCaption did not HTML-encode its value. This was very inconvenient for developers who needed to display untrusted user-provided values, and was a security issue for developers who didn’t notice it. Knockout v3 now does HTML-encode optionsCaption values for display, making it consistent with the text binding which has always done so.

If you previously solved this by manually HTML-encoding strings before supplying them to optionsCaption, you’ll need to remove that logic otherwise the string will be double-encoded.

4. checked binding uses strict equality

Knockout v3 now checks for strict equality when comparing model values and element values for the checked binding. For instance, if you were to declare:

var foo = ko.observable(2);

and bind it to these elements:

<input type="radio" name="example" value="1" data-bind="checked: foo" />
<input type="radio" name="example" value="2" data-bind="checked: foo" />

the “2” radio button would not be checked because of the strict equality comparison between the observable and the element value. You could, of course, set the observable to a string value:

var foo = ko.observable('2');

and this would bind as expected. The preferred method, though, is to have the checked binding use numeric values by employing the checkedValue binding:

<input type="radio" name="example" data-bind="checked: foo, checkedValue: 2" />
(c) knockoutjs.com