Sortable UI primitives for Ember.
Note 2.2.0
and above contains both component and modifiers invocation capabilities. This means that you will see a signficant size increase for ember-sortable
, but it should help you with migrations to modifier
, which is the path forward when we introduce v3.x.x
If you are migrating from 1.x.x
to 2.x.x
,
For components, please read this migration guide.
For modifiers, please read this migration guide.
In version 2.0.0+, our closest
polyfill seems to break some app's production
build. To mitigate this, the closest
polyfill will only enabled if it doesn't break the production
build (if the polyfill
file is recognized by the build). Affected apps will need to supply their own closest polyfill to ensure compatibility with IE. This issue is tracked here.
We require the ember-decorators-polyfill
to be installed if you are using this addon with versions of Ember < 3.10.0.
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.
$ ember install ember-sortable
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);
}
}
});
When groupModel
is set on the sortable-group
, the onChange
action is called
with that group model as the first argument:
// app/routes/my-route.js
export default Ember.Route.extend({
actions: {
reorderItems(groupModel, itemModels, draggedModel) {
groupModel.set('items', itemModels);
}
}
});
The modifier version does not support groupModel
, use the currying of action
or the fn
helper.
To change sort direction, define direction
on sortable-group
(default is y
):
component
modifier
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
):
component
modifier
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.
component
modifier
The disabled
attribute allows you to disable sorting for the entire group and its child items.
modifier
Sortable items can be in one of four states: default, dragging, dropping, and activated. 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>
<!-- Keyboard -->
<li class="sortable-item is-activated">...</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;
}
If the user presses space to activate and move an item via the keyboard, is-activated
is added. Once the user drops the item it is
removed. Use this class to add a visual indicator that the item is selected and being manipulated.
The onDragStart
and onDragStop
actions are available for the
sortable-item
s. 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')}`);
}
}
});
component
modifier
The modifier version uses a service behind the scenes for communication between the group and the items and to maintain state. It does this seemlessly when the elements are rendered on the screen. However, if there are two sortables rendered at the same time, either in the same component or different components, the state management does not know which items belong to which group.
Both the {{sortable-group}}
and {{sortable-item}}
take an additional argument groupName
. Should you encounter this conflict, assign a groupName
to the group and items. You only need to do this for one of the sortables in conflict, but you can on both if you wish.
Ensure that the same name is passed to both the group and the items, this would be best accomplished by creating property on the component and referring to that property. If you are able to use the {{#let}}
helper (useful in template only components), using {{#let}}
makes the usage clearer.
sortable-item
(component and modifier) exposes an optional disabled
(previously isDraggingDisabled
) flag that you can use to disable reordering for that particular item. Disabling and item won't prevent it from changing position in the array. The user can still move other non-disabled items to over it.
This flag is intended as an utility to make your life easier with 3 main benefits:
- You can now specify which
sortable-item
are not intended to be draggable/sortable. - You do not have to duplicate the
sortable-item
UI just for the purpose of disabling thesorting
behavior. - Allows you to access the entire list of
models
for youronChange
action, which can now be a mix of sortable and non-sortable items.
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.
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
.
The sortable-group
has support for the following accessibility functionality:
component
sortable-group
an ordered list,ol
, by default.sortable-item
a list item,li
, by default.
The modifier version can be attached to to any element that makes sense,
There are 4 modes during keyboard navigation:
- ACTIVATE
enables the keyboard navigation.
Activate via
ENTER/SPACE
- MOVE
enables item(s) to be moved up, down, left, or right based on
direction
. Activate viaARROW UP/DOWN/LEFT/RIGHT
- CONFIRM
submits the new sort order, invokes the
onChange
action. Activate viaENTER/SPACE
. - CANCEL
cancels the new sort order, reverts back to the old sort order.
Activate via
ESCAPE
or whenfocus
is lost.
- When
focus
is on aitem
orhandle
, user can effectively select theitem
viaENTER/SPACE
. This is theACTIVATE
mode. - While
ACTIVATE
, thefocus
is locked onsortable-group
container and will not be lost untilCONFIRM
,CANCEL
, orfocus
is lost.
The default language for ember-sortable
is English. Any language can be supported by passing in the configuration below in the appropriate language.
- a11yItemName
a name for the item. Defaults to
item
. - a11yAnnouncementConfig
a map of
action enums
tofunctions
that takes the followingconfig
, which is exposed bysortable-group
.
a11yAnnounceConfig = {
a11yItemName, // name associated with the name
index, // 0-based
maxLength, // length of the items
direction, // x or y
delta, // +1 means down or right, -1 means up or left
}
and returns a string
constructed from the config
.
Default value
{
ACTIVATE: function({ a11yItemName, index, maxLength, direction }) {
let message = `${a11yItemName} at position, ${index + 1} of ${maxLength}, is activated to be repositioned.`;
if (direction === 'y') {
message += 'Press up and down keys to change position,';
} else {
message += 'Press left and right keys to change position,';
}
message += ' Space to confirm new position, Escape to cancel.';
return message;
},
MOVE: function({ a11yItemName, index, maxLength, delta }) {
return `${a11yItemName} is moved to position, ${index + 1 + delta} of ${maxLength}. Press Space to confirm new position, Escape to cancel.`;
},
CONFIRM: function({ a11yItemName}) {
return `${a11yItemName} is successfully repositioned.`;
},
CANCEL: function({ a11yItemName }) {
return `Cancelling ${a11yItemName} repositioning`;
}
}
-
handleVisualClass This class will be added to the
sortable-handle
duringACTIVATE
andMOVE
operations. This allows you to add custom styles such asvisual arrows
viapseudo
classes. -
itemVisualClass This class will be added to the
sortable-item
duringACTIVATE
andMOVE
operations. The default class added isis-activated
. This is needed to creating avisual indicator
that mimicsfocus
b/c the nativefocus
is on the container.
ember-sortable
exposes some acceptance test helpers:
drag
: Drags elements by an offset specified in pixels.reorder
: Reorders elements to the specified state.keyboard
: Keycode constants for quick.
To include them in your application, you can import them:
import { drag, reorder } from 'ember-sortable/test-support/helpers';
import { ENTER_KEY_CODE, SPACE_KEY_CODE, ESCAPE_KEY_CODE, ARROW_KEY_CODES } from "ember-sortable/test-support/utils/keyboard";
Reorder
await reorder(
'mouse',
'[data-test-vertical-demo-handle]',
...order
);
Drag
await drag('mouse', '[data-test-scrollable-demo-handle] .handle', () => { return {dy: itemHeight() * 2 + 1, dx: undefined}});
Keyboard
await triggerKeyEvent(
'[data-test-vertical-demo-handle]',
'keydown',
ENTER_KEY_CODE
);
$ git clone [email protected]:adopted-ember-addons/ember-sortable
$ cd ember-sortable
$ ember install
$ ember serve
$ npm test
$ make demo