jQuery-xselectable

jQuery-xselectable is a jQuery plugin to enable DOM elements to be selectable. Draw a box with your cursor to select items. You can try this live on the demo here on the right.

It behaves similarly to jQuery UI 'selectable', but it offers a few extra features, such as support for scrollable containers and selection over Flash embeds. See Features.

I haven't spent a huge amount of time trying to customize jQuery UI 'selectable' behavior, so you may still be able to have it handle some of the features described here, with enough effort.

Download Demos Fork me on GitHub

  • Apple
  • Banana
  • Kiwi
  • Orange
  • Peach

Usage

<html>
<head>
  <style>
    UL {
      position: relative;
    }

    LI.xselectable-selected {
      color: red;
    }

    .xselectable-glass {
      background-color: transparent;
      z-index: 1000;
      cursor: hand;
      cursor: pointer;
    }

    .xselectable-box {
      border: 1px dotted black;
      background-color: rgba(255, 255, 255, 0.5);
      cursor: hand;
      cursor: pointer;
    }
  </style>
  <script src="jquery.min.js"></script>
  <script src="xselectable.min.js"></script>
  <script>
    $().ready(function() {
      $('UL').xselectable();
    });
  </script>
</head>
<body>
  <ul>
    <li>Apple</li>
    <li>Banana</li>
    <li>Kiwi</li>
    <li>Orange</li>
    <li>Peach</li>
  </ul>
<body>
</html>

Include the plugin sources in your html page (after the jQuery plugin) and use the .xselectable() method to activate the plugin on elements of your choice.

Then define a minimum set of styles to configure the plugin behavior and look'n'feel:

  • Ensure that the element that you intend to make selectable has either position: relative or position: absolute,
  • Define how selected items should appear via the .xseletable-selected class,
  • Define how the selection box should appear via the .xselectable-box class,
  • Define how the glass pane (superimposed to the selectable elements during the selection gesture) should appeara via the .xselectable-glass class.

Which plugin source file to include?

  • xselectable.min.js: self-contained, minified version of the plugin. This is the recommended file for production use.
  • xselectable.js: plain, not-minified and commented version of the plugin. Useful for debugging.

Usage with require.js

jQuery-xselectable is automatically exported as a require.js module, if your project uses require.js, just add the xselectable dependency to your requirements: 

require(['jquery', 'xselectable'], function($) {
   // Use the xselectable plugin here.       
});

See the basic.html demo for sample code.

Features

jQuery-xselectable offers a behavior similar to jQuery UI 'selectable'. In addition to that, it offers the following extra features out of the box:

  • Selection over Flash embeds. Flash embeds would normally swallow click events, causing the selection gesture not to terminate if the mouse were to be released within the Flash embed. This plugin separates the selection box from the selectable elements via glass panels to fix that.
  • Scrolling support. When the selectable container overflows the browser window viewport (or the selectable elements overflow the container viewport) and the selection box is dragged toward the viewport borders, the viewport is scrolled accordingly to let the selection gesture continue until the viewport scrolling limits are hit. In practice, this means you don't have to worry about scrolling, either of the browser window or the selectable element itself (if you configured it to have scrollbars).
    Scrolling management is pluggable, which allows for different scrolling implementations (in addition to the default one which relies on native browser scrolling functionality). For example, a Google Maps-like endless scrolling can be easily implemented.
    The plugin tries to keep scrolling at 60fps.
  • Selection does not inadvertently trigger when the mouse down event occurs over scrollbars. See http://bugs.jqueryui.com/ticket/4441.
  • The plugin doesn't require any of jQuery UI machinery. It can be used directly on top of jQuery, possibly reducing the javascript payload used in the hosting page.

Notice The plugin semantics are similar to jQuery UI 'selectable' ones but not the same. While it's fairly straightforward to replace jQuery UI plugin for this, this pluging is not a 100% compatible drop-in replacement. See the comments on top of the plugin sources for details.

Browser support

jQuery-xselectable is tested and supported in major modern browsers like Chrome, Safari, Internet Explorer, and Firefox.

Tested and supported in Chrome, Safari, Internet Explorer, and Firefox
  • Latest Safari
  • Latest Google Chrome
  • Firefox 3.6+
  • Internet Explorer 8+
  • Opera

Options

The plugin supports the following options:

Option key Default value Description
distance 0 Tolerance, in pixels, for when selecting should start. If specified, selecting will not start until after mouse is dragged beyond distance.
disabled false Whether the selectable behavior is enabled or not.
cancel :input,option Prevents selecting if you start on elements matching the selector.
filter * The matching child elements will be made able to be selected
scrollingThreshold 100 The minimum pixel distance, from the selectable container border, that should trigger scrolling.
scrollSpeedMultiplier 1 A multiplier to increase/decrease scrolling speed.
scroller null

Advanced Custom scroller implementation. The scroller is responsible for scrolling the viewport (the browser window and/or the selectable container itself, depending on its CSS styling) when the selection box is close to the viewport borders.

The default implementation relies on native browser scrolling, but alternate implementations can provide Google Maps-like scrolling behavior. For examples on how to implement this, see demos and the plugin sources.
positioner null

Advanced Custom positioner implementation. The positioner is responsible for computing selectable elements' positions when the selection gesture starts, in order to correctly determine when the selection box touches a selectable element.

The default implementation computes selectables' positions via offset measurement. This works accurately if the element the plugin applies to (the selection container) is their offset parent.

The default implementation recomputes selectables' positions every time the selection gesture starts. This may be inefficient when many selectable elements are present.

Custom implementations may be provided to overcome the above limitations. For examples on how to implement this, see demos and the plugin sources.

Configure the plugin options at initialization time:

$('#container').xselectable({
  'cancel': '.item',
  'filter': '.item',
  'distance': 10,
  'scrollSpeedMultiplier': 1.2
});

Methods

After initialization, you can invoke different methods on the plugin:

Method name Description Example
enable Enables selection gestures. 
$('#container').xselectable('enable');

Tip You can achieve the same via .xselectable('option', 'disabled', false);

disable Disables selection gestures. 
$('#container').xselectable('disable');

Tip You can achieve the same via .xselectable('option', 'disabled', true);

option Gets or sets any selectable option. If no value is specified, will act as a getter. 
$('#container').xselectable('option', 'distance', 10);
var distance = $('#container').xselectable('option', 'distance');
destroy Deactives the plugin on the given set of elements, clearing any additional data structures and event listeners created in the process, reverting the affected elements to their original state. 
$('#container').xselectable('destroy');

Events

You can bind to different events fired by the plugin to react to selections performed by the user. Use jQuery bind() function to attach listeners for each event you are interested in.

Event name Description Example
xselectablestart Fired when the selection gesture starts. 
$('#container').xselectable().bind(
  'xselectablestart',
  function(ev) {
    console.log('selection is starting');
  });
xselectableselecting Fired while the selection gesture is in progress, for every element that becomes selected. It receives an ui parameter, which contains a reference to the element that became selected in its selecting property. 
$('#container').xselectable().bind(
  'xselectableselecting',
  function(ev, ui) {
    console.log(
      'You selected: ', ui.selecting);
  });
xselectableunselecting Fired while the selection gesture is in progress, for every element that becomes unselected. It receives an ui parameter, which contains a reference to the element that became unselected in its unselecting property. 
$('#container').xselectable().bind(
  'xselectableunselecting',
  function(ev, ui) {
    console.log(
      'You selected: ', ui.unselecting);
  });
xselectableselected Fired at the end of the selection gesture, before the stop event. It receives an ui parameter, which contains a reference to the list of elements that are currently selected in its selected property. 
$('#container').xselectable().bind(
  'xselectableselected',
  function(ev, ui) {
    for (var i = ui.selected.length - 1; i >= 0; i--) {
      console.log(ui.selected[i], ' is selected');
    }
  });
xselectableunselected Fired at the end of the selection gesture, before the stop event. It receives an ui parameter, which contains a reference to the list of elements that are currently unselected in its unselected property. 
$('#container').xselectable().bind(
  'xselectableunselected',
  function(ev, ui) {
    for (var i = ui.unselected.length - 1;
         i >= 0; i--) {
      console.log(ui.unselected[i], ' is NOT selected');
    }
  });
xselectablestop Fired when the selection gesture ends. 
$('#container').xselectable().bind(
  'xselectablestop',
  function(ev) {
    console.log('selection has completed.');
  });

Demos

Basic

Use the mouse to drag a selection box and select one or more of the items in the list.

Open in a separate window: basic.html

Demo variants exist to demonstrate how to load the plugin with and without depending on require.js.

Flash embeds

All the clocks are flash SWF files. Notices how you can drag selection boxes over them, and terminate selection by releasing the mouse button while hovering over a flash element.

Open in a separate window: flash.html

Scrolling

This demo shows how scrolling is triggered when the selection box gets closer to the selectable container border. Notice how scrolling speed increases the closer the mouse is to the border.

Open in a separate window: scrollbar.html

Demo variants exist for scrolling of the browser window and combined scrolling of both the browser window and the selectable container.

Panning

Like the one above, this demo demonstrates scrolling but, instead of rely on native browser scrolling, emulates scrolling by using positioning offsets and a custom plugin scroller.

Try dragging a selection box and see how the background is scrolled when the selection box gets closer to the selectable container border.

Open in a separate window: panning.html

Google Maps Scrolling

This complex demo shows how to implement custom scrolling behavior that works in sync with other libraries (in this case, the Google Maps API).

Try moving the selection box toward the map borders and see how the map correctly scrolls in the desired direction, while continuing the select operation.

Try zooming and panning to different locations, and see how the selection process remains accurate.

Open in a separate window: maps_scrolling.html

Sources

You can download, contribute, fork or study the plugin sources at https://github.com/battlehorse/jquery-xselectable.