DragList

The DragList widget is a scrolling list whose items you can reorder by dragging.
Use it on screens where people need to rearrange list items themselves.

info

This widget is locked on the Free plan and available on the Pro and Enterprise plans.

Definition and role

The DragList widget draws a list that scrolls vertically (the default) or horizontally, and lets you drag items to reorder them. It supports drag handle icons, whole-item dragging, multi-select moves, scroll-end detection, and entrance animations.

• Category: Layouts
• Default scroll direction: vertical (vertical)
• Default item count (itemCount): 0

Features

Feature	Description
Drag to reorder	Drag and drop an item to change its position. When the move ends, the bound data list is reordered too.
Drag handle	Show a drag handle icon on each item, and set its color, size, alignment, and padding.
Whole-item drag	Let people grab the entire item and drag it, with no handle.
Multi-select move	Pair the list with a Checkbox widget to move several items at once.
Scroll control	Adjust scroll behavior such as direction, reverse, physics, and padding.
Entrance animation	Play a staggered animation as the list appears.

How to use

1. Open the Layouts category in the left widget palette.
2. Drag and drop the DragList item onto the canvas.
3. Use data binding to connect the items the list shows and the item count (itemCount).
4. Adjust the drag handle display (useDragHandler), icon, and color as needed.
5. To handle reordering, connect the reorder events (onReorder and others) in a script.

Properties

note

The table below covers the top-level properties you see as soon as you expand the Properties panel. Grouped properties such as animation and scrollController reveal more options when expanded, and this version of the document covers only the top-level entries. The table follows the same order as the Properties panel.

Property	Description	Default	Value / Type
useDragHandler	Whether each item shows the default drag handle icon	true (on)	True/false
selectWidgetId	ID of the Checkbox widget used for multi-select	Not set	String (widget ID)
selectPropertyName	Name of the property to read the selection state from (value when not set)	Not set	String
handlerColor	Color of the drag handle icon	Not set	Color
dragHandleIcon	Icon to use for the drag handle	Not set (default handle icon)	Icon settings
iconSize	Size of the handle icon	24	Number (px)
iconAlignment	Position of the handle inside the item	Center right	Alignment value
dragHandlePadding	Padding around the handle	Not set	Padding value
fullItemDraggable	Grab and drag the entire item instead of the handle	false	True/false
padding	Outer padding of the list	Not set	Padding value
itemPadding	Inner padding of each item	Not set	Padding value
scrollDirection	Scroll (layout) direction	vertical vertical	horizontal, vertical
reverse	Reverse the scroll direction	false	True/false
scrollController	External scroll controller	Not set	Scroll controller
primary	Whether this is the primary scroll view	Not set	True/false
physics	Scroll physics	Not set	bouncing, clamping, alwaysScrollable, rangeMaintaining, neverScrollable, page
shrinkWrap	Shrink the list to fit its content	false	True/false
anchor	Scroll anchor position	0.0	Number (0–1)
cacheExtent	Off-screen area to render ahead of time	Not set	Number (px)
dragStartBehavior	How the start of a drag is detected	start	down, start
keyboardDismissBehavior	How the keyboard is dismissed while scrolling	Not set	manual, onDrag
restorationId	ID for restoring the scroll position	Not set	String
clipBehavior	Clipping method	hardEdge	none, hardEdge, antiAlias, antiAliasWithSaveLayer
itemExtent	Fixed item size	Not set	Number (px)
autoScrollerVelocityScalar	Speed multiplier for auto-scrolling at the edges	800	Number
itemCount	Number of items the list shows (data binding)	0	Number (integer)
animation	Entrance (staggered) animation settings	Not set	Animation settings

note

Reorder and scroll events (onReorder, onScrollEnd, and others) along with item count and selection control come as script Widget Controls — see the document under Learn more below.

Notes and tips

warning

Multi-select moves work only when selectWidgetId points to the ID of the Checkbox widget that holds the selection state. Leave it unset and items move one at a time.

tip

You don't have to set dragHandleIcon — as long as useDragHandler is on, the default drag handle icon appears. Turn on fullItemDraggable to grab and drag the entire item instead of the handle.

Learn more

tip

For the full set of Widget Controls (Property, Method, and Event) that script this widget, see DragList Widget Control.