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 "checked" binding

Purpose

The checked binding links a checkable form control — i.e., a checkbox (<input type='checkbox'>) or a radio button (<input type='radio'>) — with a property on your view model.

When the user checks the associated form control, this updates the value on your view model. Likewise, when you update the value in your view model, this checks or unchecks the form control on screen.

Note: For text boxes, drop-down lists, and all non-checkable form controls, use the value binding to read and write the element’s value, not the checked binding.

Example with checkbox

<p>Send me spam: <input type="checkbox" data-bind="checked: wantsSpam" /></p>

<script type="text/javascript">
    var viewModel = {
		wantsSpam: ko.observable(true) // Initially checked
    };

    // ... then later ...
    viewModel.wantsSpam(false); // The checkbox becomes unchecked
</script>

Example adding checkboxes bound to an array

<p>Send me spam: <input type="checkbox" data-bind="checked: wantsSpam" /></p>
<div data-bind="visible: wantsSpam">
	Preferred flavors of spam:
	<div><input type="checkbox" value="cherry" data-bind="checked: spamFlavors" /> Cherry</div>
	<div><input type="checkbox" value="almond" data-bind="checked: spamFlavors" /> Almond</div>
	<div><input type="checkbox" value="msg" data-bind="checked: spamFlavors" /> Monosodium Glutamate</div>
</div>

<script type="text/javascript">
    var viewModel = {
		wantsSpam: ko.observable(true),
		spamFlavors: ko.observableArray(["cherry","almond"]) // Initially checks the Cherry and Almond checkboxes
    };

    // ... then later ...
    viewModel.spamFlavors.push("msg"); // Now additionally checks the Monosodium Glutamate checkbox
</script>

Example adding radio buttons

<p>Send me spam: <input type="checkbox" data-bind="checked: wantsSpam" /></p>
<div data-bind="visible: wantsSpam">
	Preferred flavor of spam:
	<div><input type="radio" name="flavorGroup" value="cherry" data-bind="checked: spamFlavor" /> Cherry</div>
	<div><input type="radio" name="flavorGroup" value="almond" data-bind="checked: spamFlavor" /> Almond</div>
	<div><input type="radio" name="flavorGroup" value="msg" data-bind="checked: spamFlavor" /> Monosodium Glutamate</div>
</div>

<script type="text/javascript">
    var viewModel = {
		wantsSpam: ko.observable(true),
		spamFlavor: ko.observable("almond") // Initially selects only the Almond radio button
    };

    // ... then later ...
    viewModel.spamFlavor("msg"); // Now only Monosodium Glutamate is checked
</script>

Parameters

  • Main parameter

    Knockout sets the element’s checked state to match your parameter value. Any previous checked state will be overwritten. The way your parameter is interpreted depends on what type of element you’re binding to:

    • For checkboxes, Knockout will set the element to be checked when the parameter value is true, and unchecked when it is false. If you give a value that isn’t actually boolean, it will be interpreted loosely. This means that nonzero numbers and non-null objects and non-empty strings will all be interpreted as true, whereas zero, null, undefined, and empty strings will be interpreted as false. When the user checks or unchecks the checkbox, Knockout will set your model property to true or false accordingly.

      If the checkedValue parameter is set, that value is used instead of true to represent a checked status, and an unchecked status is represented with a value of undefined.

      Special consideration is given if your parameter resolves to an array. In this case, Knockout will set the element to be checked if its value matches an item in the array, and unchecked if it is not contained in the array. The value of a checkbox is either the element’s value attribute or the value specified by the checkedValue parameter. When the user checks or unchecks the checkbox, Knockout will add or remove its value from the array accordingly.

    • For radio buttons, Knockout will set the element to be checked when the parameter value equals the radio button element’s value attribute or the value specified by the checkedValue parameter. In the previous example, the radio button with value="almond" was checked only when the view model’s spamFlavor property was equal to "almond".

      When the user changes which radio button is selected, Knockout will set your model property to equal the value of the selected radio button. In the preceding example, clicking on the radio button with value="cherry" would set viewModel.spamFlavor to be "cherry".

      Of course, this is most useful when you have multiple radio button elements bound to a single model property. To ensure that only one of those radio buttons can be checked at any one time, you should set all of their name attributes to an arbitrary common value (e.g., the value flavorGroup in the preceding example) – doing this puts them into a group where only one can be selected.

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

  • Additional parameters

    • checkedValue

      If your binding also includes checkedValue, this defines the value used by the checked binding instead of the element’s value attribute. This is useful if you want the value to be something other than a string (such as an integer or object), or you want the value set dynamically. For normally boolean checkboxes, this value is used instead of true to represent the checked state, with undefined used for the unchecked state.

      In the following example, the item objects themselves (not their itemName strings) will be included in the chosenItems array when their corresponding checkboxes are checked:

      <!-- ko foreach: items -->
          <input type="checkbox" data-bind="checkedValue: $data, checked: $root.chosenItems" />
          <span data-bind="text: itemName"></span>
      <!-- /ko -->
      
      <script type="text/javascript">
          var viewModel = {
              items: ko.observableArray([
                  { itemName: 'Choice 1' },
                  { itemName: 'Choice 2' }
              ]),
              chosenItems: ko.observableArray()
          };
      </script>
      

      If your checkedValue parameter is an observable value, whenever the value changes and the element is currently checked, the binding will update the checked model property. For checkboxes bound to an array, it will remove the previous value from the array and add the new value. Otherwise, it will just update the model value.

Dependencies

None, other than the core Knockout library.