Components/Lists
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/nestablelist
Nestable lists let users sort their list items into sub-levels using drag and drop.
<Accordion/> or <Table/> instead.Let users add new parent items or child items with the addItemLabel prop.
Define a maximum number of sub-levels that can be added to the list with the maxDepth prop.
By default, the maximum maxDepth value is set to 10.
Control arrow indent size with indentSize prop:
small is best for very narrow layouts, such as settings panels.medium is for smaller layouts.large (default) is used for admin tables.Turn off dividers with dividers prop to give the component more minimal look, by setting the property to false. Dividers are on by default.
Lock the existing depth for all items in the list with the preventChangeDepth prop. This property allows users to change the order of items, but only at the same level of hierarchy.
By default the value of the preventChangeDepth property is false. This means users can drag and drop any item to any level.
To lock an individual item's position, use the items prop and set draggable to false.
Items that aren't locked can still freely change their position in the list.
Prevent any reordering in the list with the readOnly prop. The list won't display any interactive icons.
To hide children and only show the parent item, use the items prop and set isCollapsed to true.
By default, parent items hide their children when they're being selected and dragged.
Add a bottom border to the last item in the list with the withBottomBorder prop. The default value is set to false.
Use the border when the list is outside the card or modal, for example, in the sidebar and on white backgrounds.
Use nestable lists to let the users organize their items (posts, articles, products, etc.) into categories and subcategories.
Use any necessary <TableListItem/> props to format the style and content inside the list of items.
Use nestable lists to allow quick rearrangement of list items.
In <SidePanel/> or on other white backgrounds, use the withBottomBorder prop to add a border divider at the end of the list.
Use it to help manage complex lists
| Name | Type | Default | Description |
|---|---|---|---|
actions | Action[] | — | Adds a row of text button actions below the list. Each action shows its label and prefixIcon, and calls its onClick when clicked. When set, it replaces the addItemLabel button. With a single action, a click anywhere on the row calls it. |
addItemLabel | string | — | Adds a button to create a new item (to the Root or a child to the existing item). |
canDrop | (dragItem: NestableListItem, hoverItem: NestableListItem) => boolean | — | Returns false to reject a drop while the cursor hovers over hoverItem. Runs after the built-in constraint flags. When it returns false, no placeholder is shown and the drop is rejected at hover time — useful for arbitrary per-position rules that the built-in flags can't express. |
dataHook | string | — | Can be applied in the tests as a data-hook HTML attribute. |
dividers | boolean | — | Sets the divider visibility. |
dragHandleSize | "small" | "large" | 'large' | Size of the drag handle. |
enforcePinnedOrder | boolean | false | Allows dragging and dropping an item only on its pin section. |
fullWidthItems | boolean | false | Stretches items to the full width of the list container, indenting each item's inner controls instead of the item itself. Suppresses hierarchyIndicator. |
hierarchyIndicator | boolean | true | Displays hierarchyIndicator from the parent to children. |
indentSize | "small" | "medium" | "large" | — | Sets the indent size. |
itemHeight | number | — | Fixed row height in px. Required when virtualized is true. |
items (required) | NestableListItem[] | — | Defines each Nestable List item individually, using the following props: * id - specifies an item's ID. * addItemLabel - creates the "Add new ..." button with a given label at the bottom of the item. * isCollapsed - bool prop, defines whether to render the item's children. * children - defines an item's children. * draggable - bool prop, turns on / off dragging ability for an item. * hideDragHandle - bool prop, turns on / off drag handle for an item. * All <TableListItem/> props can be used to format an item's style and content. |
maxDepth | number | 10 | Defines a maximum depth (number of levels) for the list. |
offscreenRowCount | number | 5 | Extra rows to render above and below the visible window. |
onAddItem | (item: NestableListItem) => void | — | Triggers function when the "Add new ..." button is clicked. |
onChange | (data: { items: NestableListItem[]; item: NestableListItem; }) => void | — | Triggers function when the item's order or nesting position is changed. |
onDragEnd | () => void | — | Triggers function when the drag of item ends. |
onDragStart | () => void | — | Triggers function when the drag of item starts. |
preventChangeDepth | boolean | false | Allows dragging and dropping an item only on its own depth (inside the same level). |
preventChangeParent | boolean | false | Allows dragging and dropping an item only on its own parent. |
readOnly | boolean | — | Prevents the list from being reordered by removing the dragging grip icons. |
showDragHandleOnHover | boolean | false | Shows the drag handle only on hover. |
viewportHeight | number | — | Scroll viewport height in px. Required when virtualized is true. |
virtualized | boolean | false | Opt into windowed rendering for large lists. Requires itemHeight and viewportHeight. |
withBottomBorder | boolean | — | Adds a bottom border (divider) to the last item. |
zIndex | number | — | Defines the zIndex of the draggable layer. |
No testkit for this component — it doesn't expose a unidriver testkit.
fullWidthItems prop stretches items to the full width of the list container, indenting each item's inner controls instead of the item itself. (#16721) — has visual changesonDragStart & onDragEnd props (#15535)hierarchyIndicator type (#14875)Last updated: 22 October 2026