NestableList

Components/Lists

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/nestablelist

Overview

Copy

Nestable lists let users sort their list items into sub-levels using drag and drop.

Do

  • Organize items into sub-levels and categories.
  • Create lists that users can add to.

Don't

  • Don't show static lists. Use <Accordion/> or <Table/> instead.
  • Don't use them for lists that span across multiple pages.

Feature examples

Add items

Let users add new parent items or child items with the addItemLabel prop.

Copy

Maximum depth

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.

Copy

Indent size

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.
Copy

Dividers

Turn off dividers with dividers prop to give the component more minimal look, by setting the property to false. Dividers are on by default.

Copy

Prevent changing depth

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.

Copy

Lock dragging

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.

Copy

Read only mode

Prevent any reordering in the list with the readOnly prop. The list won't display any interactive icons.

Copy

Collapse items

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.

Copy

Bottom border

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.

Copy

Common use case examples

Sort items into sub-categories

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.

Copy

Rearrange the order 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.

Copy

In panels

Use it to help manage complex lists

Copy

Code

Copy

Props

NameTypeDefaultDescription
actionsAction[]—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.
addItemLabelstring—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.
dataHookstring—Can be applied in the tests as a data-hook HTML attribute.
dividersboolean—Sets the divider visibility.
dragHandleSize"small" | "large"'large'Size of the drag handle.
enforcePinnedOrderbooleanfalseAllows dragging and dropping an item only on its pin section.
fullWidthItemsbooleanfalseStretches items to the full width of the list container, indenting each item's inner controls instead of the item itself. Suppresses hierarchyIndicator.
hierarchyIndicatorbooleantrueDisplays hierarchyIndicator from the parent to children.
indentSize"small" | "medium" | "large"—Sets the indent size.
itemHeightnumber—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.
maxDepthnumber10Defines a maximum depth (number of levels) for the list.
offscreenRowCountnumber5Extra 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.
preventChangeDepthbooleanfalseAllows dragging and dropping an item only on its own depth (inside the same level).
preventChangeParentbooleanfalseAllows dragging and dropping an item only on its own parent.
readOnlyboolean—Prevents the list from being reordered by removing the dragging grip icons.
showDragHandleOnHoverbooleanfalseShows the drag handle only on hover.
viewportHeightnumber—Scroll viewport height in px. Required when virtualized is true.
virtualizedbooleanfalseOpt into windowed rendering for large lists. Requires itemHeight and viewportHeight.
withBottomBorderboolean—Adds a bottom border (divider) to the last item.
zIndexnumber—Defines the zIndex of the draggable layer.

Testkit

No testkit for this component — it doesn't expose a unidriver testkit.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.336.0 (2026-10-13) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.308.0 (2026-08-04) — feat: new 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 changes
  • 1.295.0 (2026-07-03) — maintenance release, no component-specific changes
  • 1.294.0 (2026-07-02) — fix: reveal drag handle on mobile (#16457) — has visual changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.280.0 (2026-05-19) — feat: show not-allowed cursor when canDrop rejects a drop (#16263)
  • 1.279.0 (2026-05-13) — feat: add canDrop callback for per-position drop validation (#16260)
  • 1.278.0 (2026-05-08) — feat: add virtualized rendering (#16227)
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.262.0 (2026-03-25) — fix: prevent item state reset during drag when parent re-renders (#16055)
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.250.0 (2026-01-27) — maintenance release, no component-specific changes
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — fix: add auto scroll + delay before drag on touch (#15629)
  • 1.239.0 (2025-12-12) — maintenance release, no component-specific changes
  • 1.230.0 (2025-11-19) — feat: expose onDragStart & onDragEnd props (#15535)
  • 1.217.0 (2025-09-08) — maintenance release, no component-specific changes
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.198.0 (2025-06-07) — feat: static items & draggable items without visible dragHandle (#14845)
  • 1.190.0 (2025-05-21) — fix: add missing hierarchyIndicator type (#14875)
  • 1.189.0 (2025-05-15) — feat: add hierarchyIndicator prop (#14850)
  • 1.187.0 (2025-05-07) — breaking: expandable and non-expandable siblings are now aligned (#14819)
  • 1.176.0 (2025-04-02) — feat: add dragHandle props (#14673)
  • 1.174.0 (2025-03-28) — maintenance release, no component-specific changes
  • 1.170.0 (2025-03-12) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.123.0 (2024-08-26) — fix: fix random item duplication and removal when dragging (#14055)
  • 1.116.0 (2024-07-22) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — feat: add dividers and indentSize props (#13938)
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.93.0 (2024-02-08) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?