knockout.selection

This binding implements a selection model that can be used with Knockout.js's `foreach` and `template` bindings, or other bindings through the `data` option. It handles multiple selections using `<ctrl>`- and `<shift>`-click as well as keyboard navigation.

npm install knockout.selection
28 downloads in the last week
29 downloads in the last month

Knockout.js selection binding Build Status

This binding implements a selection model that can be used with Knockout.js's foreach and template bindings, or other bindings through the data option. It handles multiple selections using <ctrl>- and <shift>-click as well as keyboard navigation.

Usage

data-bind="foreach: <observableArray>, selection: <observableArray>"

data-bind="foreach: <observableArray>, selection: { selection: <observableArray>, focused: <observable> }"

data-bind="selection: { data: <observableArray>, selection: <observableArray>, focused: <observable> }"

If you want to use the built-in keyboard navigation be sure to set tabindex so that your element can have focus and therefor receive keyboard events. See examples/index.html for an example on how to set tabindex.

Options

data \

An observable array that contains all items available to the selection model, as an alternative to the foreach and template: { foreach: ... } bindings.

selection \

An observable array that will reflect the currently selected items from the foreach or template: { foreach: ... } bindings, or from the data option.

focused \

An observable that contains the currently focused item. This might return null if there is no current focus.

mode \

Set to single if the selection model should only allow a single selected item.

If set to multi users can use <ctrl> and <shift> to select multiple items using either a mouse or keyboard.

When set to toggle the selection model supports multiple selections, but selections are "sticky". Once selected they can only be deselect by selecting them again. This is useful on, for example, touch devices.

Set to off to disable the selection.

Defaults to multi.

The mode will be altered on the fly when the value of the observable changes.

direction \

Set to horizontal to allow navigating with left/right arrow keys, when mode is either single or multi.

When set to vertical, the up/down arrow keys are available for navigating.

Defaults to vertical.

properties \

The selection binding will by default look for selected and focused observable properties on your foreach items and set them to true when the item is selected or focused. Using the properties option you can override these default property names to something else. For example:

data-bind="foreach: mylist, selection: { selection: mylistSelection, properties: { selected: 'active', focused: 'highlight' }"

This will set the active and highlight observable properties on items in mylist when they are selected or focused.

Running the tests

This test suite uses Mocha and Expect.js.

You can run the tests in the browser by opening tests.html. It is also posible to run the tests from the console using PhantomJS, just run npm test.

Browser Support

This project supports the latest Internet Explorer, Firefox, Opera, Chrome, Safari, and Android browsers. Tests are run automatically on all supported browsers using BrowserStack and browserstack-test.

Contributors

  • Sune Sloth Simonsen (@sunesimonsen)
  • Andreas Lind Petersen (@papandreou)
  • Maarten Winter (@mwoc)
  • Gustav Nikolaj Olsen (@gustavnikolaj)

License

knockout.selection is licensed under the three clause BSD license.

npm loves you