Skip to content
Sortable UI primitives for Ember.js
JavaScript HTML CSS Makefile
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Add bug issue template (#205) Nov 16, 2018
addon Completed hooking up sortable-handle to the everything and updated al… Oct 17, 2019
app Completed hooking up sortable-handle to the everything and updated al… Oct 17, 2019
config Add Ember 2.8, 2.12 to testing. Test Node 8 Apr 24, 2019
test-support/ember-sortable 1. Adding data-test-selector. (#271) Oct 10, 2019
tests Completed hooking up sortable-handle to the everything and updated al… Oct 17, 2019
vendor/polyfills Removing matches polyfill from closest polyfill (#286) Oct 6, 2019
.editorconfig Upgrade to ember-cli 2.7.0 Aug 5, 2016
.ember-cli Initial Commit from Ember CLI v0.2.3 Apr 23, 2015
.eslintignore Upgrade to 3.7.x family (#228) Feb 5, 2019
.eslintrc.js eslint: enforce space before and after arrow of arrow function Jun 15, 2019
.gitignore 1. Removing sortable-item-mixin. (#270) Oct 2, 2019
.huskyrc 1. Adding data-test-selector. (#271) Oct 10, 2019
.npmignore Upgrade to 3.7.x family (#228) Feb 5, 2019
.template-lintrc.js Upgrade to 3.7.x family (#228) Feb 5, 2019
.travis.yml Add Ember 2.8, 2.12 to testing. Test Node 8 Apr 24, 2019
.watchmanconfig Upgrade to ember-cli 2.2.0-beta.1 Dec 17, 2015
CHANGELOG.md heroku ➝ adopted-ember-addons Sep 25, 2019
CODE_OF_CONDUCT.md add a code of conduct (#204) Nov 19, 2018
CONTRIBUTING.md Upgrade to 3.7.x family (#228) Feb 5, 2019
LICENSE.md ember-cli-update to 2.18 Jan 16, 2018
Makefile 1.x -> master in Makefile May 22, 2019
README.md Replacing contextual components and replacing registerWaiter with bui… Oct 17, 2019
V2_MIGRATION_RFC.md Migration RFC (#274) Oct 10, 2019
demo.gif Update demo.gif Apr 29, 2015
ember-cli-build.js Replace jQuery with vanilla JS (#212) Dec 3, 2018
index.js 1. Adding closest polyfill (#280) Oct 5, 2019
package.json Replacing sendAction. (#282) Oct 16, 2019
testem.js fixes for Firefox (#223) Dec 19, 2018
yarn.lock Replacing sendAction. (#282) Oct 16, 2019

README.md

Ember-sortable

npm version Download Total Ember Observer Score Build Status Code Climate

Sortable UI primitives for Ember.

ember-sortable in action

Check out the demo

Releases

We're actively working on the next exciting 2.0.0 release. The master branch will contain all the up-to-date development Please refer to the Migration RFC for more information.

Requirements

Version 1.0 depends upon the availability of 2D CSS transforms. Check the matrix on caniuse.com to see if your target browsers are compatible.

As of version 1.12.2 ember-sortable depends on Element.closest, which is unsupported in all versions of Internet Explorer. A polyfill is available - both on MDN, and as a package.

Installation

$ ember install ember-sortable

Usage

{{! app/templates/my-route.hbs }}

{{#sortable-group tagName="ul" onChange=(action "reorderItems") as |group|}}
  {{#each model.items as |item|}}
    {{#group.item tagName="li" model=item group=group handle=".handle"}}
      {{item.name}}
      <span class="handle">&varr;</span>
    {{/group.item}}
  {{/each}}
{{/sortable-group}}

The onChange action is called with two arguments:

  • Your item models in their new order
  • The model you just dragged
// app/routes/my-route.js

export default Ember.Route.extend({
  actions: {
    reorderItems(itemModels, draggedModel) {
      this.set('currentModel.items', itemModels);
      this.set('currentModel.justDragged', draggedModel);
    }
  }
});

Declaring a “group model”

When model is set on the sortable-group, the onChange action is called with that group model as the first argument:

{{! app/templates/my-route.hbs }}

{{#sortable-group tagName="ul" model=model onChange=(action "reorderItems") as |group|}}
  {{#each model.items as |item|}}
    {{#group.item tagName="li" model=item group=group handle=".handle"}}
      {{item.name}}
      <span class="handle">&varr;</span>
    {{/group.item}}
  {{/each}}
{{/sortable-group}}
// app/routes/my-route.js

export default Ember.Route.extend({
  actions: {
    reorderItems(groupModel, itemModels, draggedModel) {
      groupModel.set('items', itemModels);
    }
  }
});

Changing sort direction

To change sort direction, define direction on sortable-group (default is y):

{{#sortable-group direction="x" onChange=(action "reorderItems") as |group|}}

Changing spacing between currently dragged element and the rest of the group

When user starts to drag element, other elements jump back. Works both for the x and y direction option.

In y case: elements above current one jump up, and elements below current one - jump down. In x case: elements before current one jump to the left, and elements after current one - jump to the right.

To change this property, define spacing on sortable-item (default is 0):

{{#sortable-item tagName="li" group=group spacing=15}}

Changing the drag tolerance

distance attribute changes the tolerance, in pixels, for when sorting should start. If specified, sorting will not start until after mouse is dragged beyond distance. Can be used to allow for clicks on elements within a handle.

{{#sortable-item group=group distance=30}}

CSS, Animation

Sortable items can be in one of three states: default, dragging, dropping. The classes look like this:

<!-- Default -->
<li class="sortable-item">...</li>
<!-- Dragging -->
<li class="sortable-item is-dragging">...</li>
<!-- Dropping -->
<li class="sortable-item is-dropping">...</li>

In our example app.css we apply a transition of .125s in the default case:

.sortable-item {
  transition: all .125s;
}

While an item is dragging we want it to move pixel-for-pixel with the user’s mouse so we bring the transition duration to 0. We also give it a highlight color and bring it to the top of the stack:

.sortable-item.is-dragging {
  transition-duration: 0s;
  background: red;
  z-index: 10;
}

While dropping, the is-dragging class is removed and the item returns to its default transition duration. If we wanted to apply a different duration we could do so with the is-dropping class. In our example we opt to simply maintain the z-index and apply a slightly different colour:

.sortable-item.is-dropping {
  background: #f66;
  z-index: 10;
}

Drag Actions

The onDragStart and onDragStop actions are available for the sortable-items. You can provide an action name to listen to these actions to be notified when an item is being dragged or not.

When the action is called, the item's model will be provided as the only argument.

// app/routes/my-route.js

export default Ember.Route.extend({
  actions: {
    dragStarted(item) {
      console.log(`Item started dragging: ${item.get('name')}`);
    },
    dragStopped(item) {
      console.log(`Item stopped dragging: ${item.get('name')}`);
    }
  }
});
  {{#sortable-item
    onDragStart=(action "dragStarted")
    onDragStop=(action "dragStopped")
    tagName="li"
    model=item
    group=group
    handle=".handle"
  }}
    {{item.name}}
    <span class="handle">&varr;</span>
  {{/sortable-item}}

Data down, actions up

No data is mutated by sortable-group or sortable-item. In the spirit of “data down, actions up”, a fresh array containing the models from each item in their new order is sent via the group’s onChange action.

sortable-group yields itself to the block so that it may be assigned explicitly to each item’s group property.

Each item takes a model property. This should be fairly self-explanatory but it’s important to note that it doesn’t do anything with this object besides keeping a reference for later use in onChange.

Accessibility

sortable-items can receive a tabindex which allows them to be focused. Use this to enable keyboard sorting for accessibility.

{{#each myItems as |item idx| }}
  {{#sortable-item tabindex=0 keyUp=(action 'keyUp' idx) tagName="li" model=item group=group handle=".handle"}}
    {{item.name}}
    <span class="handle">&varr;</span>
  {{/sortable-item}}
{{/each}}
actions: {
  keyUp(index, evt) {
    switch(evt.key) {
      case "ArrowDown":
        // move item at `index` back one
        break;
      case "ArrowUp":
        // move item at `index` forward one
        break;
      default:
        return;
    }
  }
}

Testing

ember-sortable exposes some acceptance test helpers:

  • drag: Drags elements by an offset specified in pixels.
  • reorder: Reorders elements to the specified state.

To include them in your application, import then in your start-app.js:

// tests/helpers/start-app.js

import './ember-sortable/test-helpers';

Developing

Setup

$ git clone git@github.com:adopted-ember-addons/ember-sortable
$ cd ember-sortable
$ ember install

Dev Server

$ ember serve

Running Tests

$ npm test

Publishing Demo

$ make demo
You can’t perform that action at this time.