Sortable — Smart UI JavaScript API

Sortable — Smart UI JavaScript API

On this page + Quick start

Quick start · JavaScript

Complete starter source per framework. Run the scaffold/install command first, then replace the listed files with the full code below.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Sortable - JavaScript Quick Start</title>
  <link rel="stylesheet" href="./node_modules/smart-webcomponents/source/styles/smart.default.css" />
</head>
<body>
  <smart-sortable id="demo-sortable"></smart-sortable>

  <script type="module">
    import './node_modules/smart-webcomponents/source/modules/smart.sortable.js';

    const el = document.getElementById('demo-sortable');
    if (el) {

      el.mode = 'vertical';
      el.items = [
        { label: 'Backlog' },
        { label: 'In Progress' },
        { label: 'Done' }
      ];

      el.addEventListener('change', (event) => console.log('change:', event.detail || event));
    }
  </script>
</body>
</html>
For AI tooling

Developer Quick Reference

Component: Sortable   Framework: JavaScript   Selector: smart-sortable

API counts: 12 properties, 2 methods, 1 events

Common properties: 0, 1, 2, 3, 4, 5

Common methods: move(), updateItems()

Common events: dragEnd

Module hint: smart-webcomponents/source/modules/smart.sortable.js

Sortable allows you to rearrange a group of html elements.

Class

Sortable

Sortable

Sortable allows you to rearrange a group of html elements.

Selector

smart-sortable

Quick picks

disableditems

Properties

AanimationDefines or retrieves the current animation mode. When this property is set to 'none', all animations are disabled and elements will transition instantly without any animated effects. Use this property to enable, disable, or customize the animation behavior of components.
DdisabledControls whether items can be sorted. When enabled, users can rearrange items by sorting them; when disabled, sorting functionality is not available.
DdragModeDetermines how a sortable item can be dragged within the list. When set to 'item', users can drag the entire item itself to reorder it. When set to 'handle', a specific drag handle is displayed next to each item, and only dragging this handle will reorder the item. This property can be both retrieved (get) and modified (set) to control the user’s drag interaction method.
HhandlePositionSets or retrieves the position of the drag handle in relation to its associated sortable item. This property is only applicable when the dragMode option is set to 'handle', meaning that the user can initiate dragging only by interacting with the specified handle within the sortable item. Use this option to define where the handle appears (e.g., 'left', 'right', 'top', or 'bottom') relative to the item, allowing for precise customization of the drag-and-drop interface.
HhandleVisibilityDetermines whether the drag handle of a sortable item is always visible or only appears when the item is hovered over. This property is applicable only if dragMode is set to 'handle'. Use this setting to control the visibility of the item’s drag handle for user interaction.
IitemsSpecifies or retrieves a CSS selector used to identify which elements within the container are sortable items. By default, all direct child elements of the 'smart-sortable' custom element are considered sortable. You can customize this selector to restrict sortable functionality to specific child elements based on their class, tag, or other attributes.
LlocaleSpecifies or retrieves the current language code (e.g., 'en', 'fr', 'es'). This property determines which set of localized messages from the messages property will be used for displaying text or content. It ensures the correct language is applied throughout the application's interface.
LlocalizeFormatFunctionCallback function associated with the localization module, typically used to handle language or region-specific content updates or responses within the application.
MmessagesDefines or retrieves an object containing the localized strings that are displayed in the widget's user interface. This property allows you to customize all text elements for different languages and regions. It should be used together with the locale property to ensure the widget presents the appropriate translations based on the selected locale.
MmodeSets or retrieves the orientation (horizontal or vertical) in which sortable items are arranged and can be reordered by dragging. This determines whether items are stacked in a row or a column when using the sortable functionality.
RrightToLeftGets or sets a value that specifies whether the element's text direction is set to right-to-left (RTL), enabling proper alignment and layout for languages and locales that use right-to-left scripts, such as Arabic or Hebrew.
UunlockKeySets or retrieves the unlockKey, a unique value required to activate or grant access to the product's features. This property enables locking and unlocking the product based on its assigned key.

Events

DdragEndThis event is triggered whenever the order of items in a sortable list changes, indicating that one or more items have been repositioned within the list by the user. The event provides details about the updated order, allowing you to respond to changes, such as saving the new arrangement or updating the user interface.

Methods

MmoveRelocates a sortable item within a list from its current index to a specified target index, updating the order of items accordingly.
UupdateItemsRecalculates the list of sortable items within the custom element. This method should be called whenever items are dynamically added or removed to ensure that all current items are properly recognized and can be sorted as expected.

Properties

animationDefines or retrieves the current animation mode. When this property is set to 'none', all animations are disabled and elements will transition instantly without any animated effects. Use this property to enable, disable, or customize the animation behavior of components."none" | "simple" | "advanced"

Defines or retrieves the current animation mode. When this property is set to 'none', all animations are disabled and elements will transition instantly without any animated effects. Use this property to enable, disable, or customize the animation behavior of components.

Allowed Values

  • "none" - animation is disabled
  • "simple" - ripple animation is disabled
  • "advanced" - all animations are enabled

Default value

"advanced"

Examples

Markup and runtime examples for animation:

HTML:

<smart-sortable animation="none"></smart-sortable>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-sortable');
el.animation = "simple";

Read the current value:

const el = document.querySelector('smart-sortable');
const animation = el.animation;

disabledControls whether items can be sorted. When enabled, users can rearrange items by sorting them; when disabled, sorting functionality is not available.boolean

Controls whether items can be sorted. When enabled, users can rearrange items by sorting them; when disabled, sorting functionality is not available.

Default value

false
Try a demo showcasing the disabled property.

Examples

Markup and runtime examples for disabled:

HTML attribute:

<smart-sortable disabled></smart-sortable>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-sortable');
el.disabled = false;

Read the current value:

const el = document.querySelector('smart-sortable');
const disabled = el.disabled;

dragModeDetermines how a sortable item can be dragged within the list. When set to 'item', users can drag the entire item itself to reorder it. When set to 'handle', a specific drag handle is displayed next to each item, and only dragging this handle will reorder the item. This property can be both retrieved (get) and modified (set) to control the user’s drag interaction method."item" | "handle"

Determines how a sortable item can be dragged within the list. When set to 'item', users can drag the entire item itself to reorder it. When set to 'handle', a specific drag handle is displayed next to each item, and only dragging this handle will reorder the item. This property can be both retrieved (get) and modified (set) to control the user’s drag interaction method.

Default value

"item"
Try a demo showcasing the dragMode property.

Examples

Markup and runtime examples for dragMode:

HTML:

<smart-sortable drag-mode="handle"></smart-sortable>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-sortable');
el.dragMode = "item";

Read the current value:

const el = document.querySelector('smart-sortable');
const dragMode = el.dragMode;

handlePositionSets or retrieves the position of the drag handle in relation to its associated sortable item. This property is only applicable when the dragMode option is set to 'handle', meaning that the user can initiate dragging only by interacting with the specified handle within the sortable item. Use this option to define where the handle appears (e.g., 'left', 'right', 'top', or 'bottom') relative to the item, allowing for precise customization of the drag-and-drop interface."right" | "left" | "top" | "bottom"

Sets or retrieves the position of the drag handle in relation to its associated sortable item. This property is only applicable when the dragMode option is set to 'handle', meaning that the user can initiate dragging only by interacting with the specified handle within the sortable item. Use this option to define where the handle appears (e.g., 'left', 'right', 'top', or 'bottom') relative to the item, allowing for precise customization of the drag-and-drop interface.

Default value

"right"
Try a demo showcasing the handlePosition property.

Examples

Markup and runtime examples for handlePosition:

HTML:

<smart-sortable handle-position="top"></smart-sortable>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-sortable');
el.handlePosition = "left";

Read the current value:

const el = document.querySelector('smart-sortable');
const handlePosition = el.handlePosition;

handleVisibilityDetermines whether the drag handle of a sortable item is always visible or only appears when the item is hovered over. This property is applicable only if dragMode is set to 'handle'. Use this setting to control the visibility of the item’s drag handle for user interaction."hover" | "visible"

Determines whether the drag handle of a sortable item is always visible or only appears when the item is hovered over. This property is applicable only if dragMode is set to 'handle'. Use this setting to control the visibility of the item’s drag handle for user interaction.

Default value

"hover"
Try a demo showcasing the handleVisibility property.

Examples

Markup and runtime examples for handleVisibility:

HTML:

<smart-sortable handle-visibility="visible"></smart-sortable>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-sortable');
el.handleVisibility = "hover";

Read the current value:

const el = document.querySelector('smart-sortable');
const handleVisibility = el.handleVisibility;

itemsSpecifies or retrieves a CSS selector used to identify which elements within the container are sortable items. By default, all direct child elements of the 'smart-sortable' custom element are considered sortable. You can customize this selector to restrict sortable functionality to specific child elements based on their class, tag, or other attributes.string | null

Specifies or retrieves a CSS selector used to identify which elements within the container are sortable items. By default, all direct child elements of the 'smart-sortable' custom element are considered sortable. You can customize this selector to restrict sortable functionality to specific child elements based on their class, tag, or other attributes.

Try a demo showcasing the items property.

Examples

Markup and runtime examples for items:

HTML:

<smart-sortable items="li"></smart-sortable>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-sortable');
el.items = ".special-item";

Read the current value:

const el = document.querySelector('smart-sortable');
const items = el.items;

localeSpecifies or retrieves the current language code (e.g., 'en', 'fr', 'es'). This property determines which set of localized messages from the messages property will be used for displaying text or content. It ensures the correct language is applied throughout the application's interface.string

Specifies or retrieves the current language code (e.g., 'en', 'fr', 'es'). This property determines which set of localized messages from the messages property will be used for displaying text or content. It ensures the correct language is applied throughout the application's interface.

Default value

"en"

Examples

Markup and runtime examples for locale:

HTML:

<smart-sortable locale="de"></smart-sortable>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-sortable');
el.locale = "en";

Read the current value:

const el = document.querySelector('smart-sortable');
const locale = el.locale;

localizeFormatFunctionCallback function associated with the localization module, typically used to handle language or region-specific content updates or responses within the application.function | null

Callback function associated with the localization module, typically used to handle language or region-specific content updates or responses within the application.

Examples

Markup and runtime examples for localizeFormatFunction:

HTML:

<smart-sortable localize-format-function="function(){return '...'}"></smart-sortable>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-sortable');
el.localizeFormatFunction = "function(){return '...'}";

Read the current value:

const el = document.querySelector('smart-sortable');
const localizeFormatFunction = el.localizeFormatFunction;

messagesDefines or retrieves an object containing the localized strings that are displayed in the widget's user interface. This property allows you to customize all text elements for different languages and regions. It should be used together with the locale property to ensure the widget presents the appropriate translations based on the selected locale.object

Defines or retrieves an object containing the localized strings that are displayed in the widget's user interface. This property allows you to customize all text elements for different languages and regions. It should be used together with the locale property to ensure the widget presents the appropriate translations based on the selected locale.

Default value




"en": {

"propertyUnknownType": "'{{name}}' property is with undefined 'type' member!",

"propertyInvalidValue": "Invalid '{{name}}' property value! Actual value: '{{actualValue}}', Expected value: '{{value}}'!",

"propertyInvalidValueType": "Invalid '{{name}}' property value type! Actual type: '{{actualType}}', Expected type: '{{type}}'!",

"methodInvalidValueType": "Invalid '{{name}}' method argument value type! Actual type: '{{actualType}}', Expected type: '{{type}}' for argument with index: '{{argumentIndex}}'!",

"methodInvalidArgumentsCount": "Invalid '{{name}}' method arguments count! Actual arguments count: '{{actualArgumentsCount}}', Expected at least: '{{argumentsCount}}' argument(s)!",

"methodInvalidReturnType": "Invalid '{{name}}' method return type! Actual type: '{{actualType}}', Expected type: '{{type}}'!",

"elementNotInDOM": "Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.",

"moduleUndefined": "Module is undefined.",

"missingReference": "{{elementType}}: Missing reference to '{{files}}'.",

"htmlTemplateNotSuported": "{{elementType}}: Web Browser doesn't support HTMLTemplate elements.",

"invalidTemplate": "{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."

}

Examples

Markup and runtime examples for messages:

HTML:

<smart-sortable messages="{"de":{"propertyUnknownType":"'{{name}}' Eigenschaft ist mit undefined 'Typ'-Member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: '{{actualValue}}', Expected value: '{{value}}'!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: '{{actualType}}', Expected type: '{{type}}'!","methodInvalidValueType":"Invalid '{{name}}' method argument value type! Actual type: '{{actualType}}', Expected type: '{{type}}' for argument with index: '{{argumentIndex}}'!","methodInvalidArgumentsCount":"Invalid '{{name}}' method arguments count! Actual arguments count: '{{actualArgumentsCount}}', Expected at least: '{{argumentsCount}}' argument(s)!","methodInvalidReturnType":"Invalid '{{name}}' method return type! Actual type: '{{actualType}}', Expected type: '{{type}}'!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Modul ist nicht definiert.","missingReference":"{{elementType}}: Fehlender Verweis auf {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Web Browser doesn't support HTMLTemplate elements.","invalidTemplate":"{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."}}"></smart-sortable>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-sortable');
el.messages = {"en":{"propertyUnknownType":"'{{name}}' property is with undefined 'type' member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: '{{actualValue}}', Expected value: '{{value}}'!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: '{{actualType}}', Expected type: '{{type}}'!","methodInvalidValueType":"Invalid '{{name}}' method argument value type! Actual type: '{{actualType}}', Expected type: '{{type}}' for argument with index: '{{argumentIndex}}'!","methodInvalidArgumentsCount":"Invalid '{{name}}' method arguments count! Actual arguments count: '{{actualArgumentsCount}}', Expected at least: '{{argumentsCount}}' argument(s)!","methodInvalidReturnType":"Invalid '{{name}}' method return type! Actual type: '{{actualType}}', Expected type: '{{type}}'!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Module is undefined.","missingReference":"{{elementType}}: Missing reference to '{{files}}'.","htmlTemplateNotSuported":"{{elementType}}: Web Browser doesn't support HTMLTemplate elements.","invalidTemplate":"{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."}};

Read the current value:

const el = document.querySelector('smart-sortable');
const messages = el.messages;

modeSets or retrieves the orientation (horizontal or vertical) in which sortable items are arranged and can be reordered by dragging. This determines whether items are stacked in a row or a column when using the sortable functionality."horizontal" | "vertical"

Sets or retrieves the orientation (horizontal or vertical) in which sortable items are arranged and can be reordered by dragging. This determines whether items are stacked in a row or a column when using the sortable functionality.

Default value

"vertical"
Try a demo showcasing the mode property.

Examples

Markup and runtime examples for mode:

HTML:

<smart-sortable mode="horizontal"></smart-sortable>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-sortable');
el.mode = "vertical";

Read the current value:

const el = document.querySelector('smart-sortable');
const mode = el.mode;

rightToLeftGets or sets a value that specifies whether the element's text direction is set to right-to-left (RTL), enabling proper alignment and layout for languages and locales that use right-to-left scripts, such as Arabic or Hebrew.boolean

Gets or sets a value that specifies whether the element's text direction is set to right-to-left (RTL), enabling proper alignment and layout for languages and locales that use right-to-left scripts, such as Arabic or Hebrew.

Default value

false
Try a demo showcasing the rightToLeft property.

Examples

Markup and runtime examples for rightToLeft:

HTML attribute:

<smart-sortable right-to-left></smart-sortable>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-sortable');
el.rightToLeft = true;

Read the current value:

const el = document.querySelector('smart-sortable');
const rightToLeft = el.rightToLeft;

unlockKeySets or retrieves the unlockKey, a unique value required to activate or grant access to the product's features. This property enables locking and unlocking the product based on its assigned key.string

Sets or retrieves the unlockKey, a unique value required to activate or grant access to the product's features. This property enables locking and unlocking the product based on its assigned key.

Default value

""

Examples

Markup and runtime examples for unlockKey:

HTML:

<smart-sortable unlock-key=""></smart-sortable>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-sortable');
el.unlockKey = "1111-2222-3333-4444-5555";

Read the current value:

const el = document.querySelector('smart-sortable');
const unlockKey = el.unlockKey;

Events

dragEndThis event is triggered whenever the order of items in a sortable list changes, indicating that one or more items have been repositioned within the list by the user. The event provides details about the updated order, allowing you to respond to changes, such as saving the new arrangement or updating the user interface.CustomEvent

This event is triggered whenever the order of items in a sortable list changes, indicating that one or more items have been repositioned within the list by the user. The event provides details about the updated order, allowing you to respond to changes, such as saving the new arrangement or updating the user interface.

  • Bubbles Yes
  • Cancelable Yes
  • Interface CustomEvent
  • Event handler property onDragEnd

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the dragEnd event.

Examples

Listen for dragEnd using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-sortable')?.addEventListener('dragEnd', (event) => {
	// event handling code goes here.
})

Methods

move( fromIndex?: number, toIndex?: number): voidRelocates a sortable item within a list from its current index to a specified target index, updating the order of items accordingly.

Relocates a sortable item within a list from its current index to a specified target index, updating the order of items accordingly.

Arguments

fromIndex?number

The original index of the item.

toIndex?number

The index to move the item to.

On the custom element in the DOM (narrow the selector, e.g. to #my-sortable, if you host multiple widgets):

document.querySelector('smart-sortable')?.move("0, 5");

Try a demo showcasing the move method.

updateItems(): voidRecalculates the list of sortable items within the custom element. This method should be called whenever items are dynamically added or removed to ensure that all current items are properly recognized and can be sorted as expected.

Recalculates the list of sortable items within the custom element. This method should be called whenever items are dynamically added or removed to ensure that all current items are properly recognized and can be sorted as expected.

On the custom element in the DOM (narrow the selector, e.g. to #my-sortable, if you host multiple widgets):

document.querySelector('smart-sortable')?.updateItems();

Try a demo showcasing the updateItems method.

CSS Variables

--smart-sortable-handle-sizevar()

Default value

"25px"

smartSortable handle size