Skip to content

feat(dnd): support dragging collection items from handles only - #10738

Open
reidbarber wants to merge 45 commits into
mainfrom
drag-from-handle
Open

reidbarber wants to merge 45 commits into
mainfrom
drag-from-handle

Conversation

@reidbarber

@reidbarber reidbarber commented Oct 7, 2026 •

Copy link
Copy Markdown
Member

Closes #9739

Adds pointerDragSource: 'item' | 'handle' to useDragAndDrop, allowing collections with editable content to restrict mouse and touch dragging to the dedicated handle, instead of the entire item. The default is 'item', which is the existing behavior. This applies to RAC components (GridList, Table, and Tree), and S2 components (ListView, TableView, and TreeView).

In pointerDragSource: "handle" mode, native drag handlers are applied to the drag button while preserving the whole-item default preview and existing keyboard/screen-reader interactions.

For the S2 components specifically:

  • For non-touch devices, handles only appear if an item is keyboard focused, hovered, or selected.
  • For touch devices, handles are always shown. The handle hit area is expanded via a psuedo-element.
  • cursor: grab is applied when the handle is hovered.
  • cursor: grabbing is applied when the handle is pressed. Note that browsers do not allow manually setting this when a native drag is happening (it is instead determined by the current dropEffect).

As always, naming is up for debate. We could do dragSource: 'item' | 'handle', although it doesn't reflect that this setting doesn't affect keyboard interactivity.

✅ Pull Request Checklist:

  • Included link to corresponding React Spectrum GitHub Issue.
  • Added/updated unit tests and storybook for this change (for new code or code which already has tests).
  • Filled out test instructions.
  • Updated documentation (if it already exists for this component).
  • Looked at the Accessibility Practices for this feature - Aria Practices
  • I understand every change in this PR and can explain why it's there.
  • If AI-assisted, I followed our AI contribution guidance and pointed my assistant at AGENTS.md.

📝 Test Instructions:

Test stories and docs for S2 and RAC collection components with DnD. Test across browsers and device types.

React Spectrum docs

React Aria docs

🧢 Your Project:

@rspbot

rspbot commented Oct 7, 2026

Copy link
Copy Markdown


// Playwright's Firefox reports an empty pointerType for mouse presses, causing
// usePress to treat the release as virtual and start accessible dragging.
const itDrag = it.skipIf(/firefox/i.test(navigator.userAgent));

@reidbarber reidbarber Oct 7, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Skipping Firefox in the browser tests due to Playwright issues around pointerType. Everything works as expected in Firefox (non-Playwright) though. We could default the pointerType to 'mouse' in usePress to fix this, but I really didn't want to change usePress in this PR.

@rspbot

rspbot commented Oct 7, 2026

Copy link
Copy Markdown

@catherine catherine left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I need to loop back to check out/test the Stories, but this is looking good to me -- I also liked term swap from "dragButton" to "handle"

@rspbot

rspbot commented Oct 12, 2026

Copy link
Copy Markdown

@rspbot

rspbot commented Oct 12, 2026

Copy link
Copy Markdown

@rspbot

rspbot commented Oct 12, 2026

Copy link
Copy Markdown

@LFDanLu LFDanLu left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we want to consider adding this support to RAC ListBox as well? I know interactive elements are not supported inside ListBox items but maybe a user may want to set drag handle only dragging so that the text inside a listbox item is copyable via mouse click + drag.

// Spans the start padding and drag handle, stopping before the expand button.
default: 14,
// Also spans the checkbox's marginStart, which doesn't scale.
isCheckboxVisible: '[calc(0.875rem * var(--s2-scale) + 0.5rem)]'

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is the checkbox's marginStart not just 8?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could do calc(${size(14)} + ${space(8)}) to make it easier to read, here, but just 22 here would scale the margin too, which isn't right on touch devices.


GridList supports drag and drop interactions when the `dragAndDropHooks` prop is provided using the <TypeLink links={docs.links} type={docs.exports.useDragAndDrop} /> hook. Users can drop data on the list as a whole, on individual items, insert new items between existing ones, or reorder items. React Aria supports drag and drop via mouse, touch, keyboard, and screen reader interactions. See the [drag and drop guide](dnd?component=GridList) to learn more.

If items contain interactive elements such as text fields, set `pointerDragSource: 'handle'` to restrict mouse and touch dragging to the drag handle.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

might be worth a direct link to the specific section in the dnd docs, same for the other mentions in the other RAC and S2 components

@reidbarber

Copy link
Copy Markdown
Member Author

do we want to consider adding this support to RAC ListBox as well? I know interactive elements are not supported inside ListBox items but maybe a user may want to set drag handle only dragging so that the text inside a listbox item is copyable via mouse click + drag.

@LFDanLu I guess it would be more like a fake button where you would restrict pointer dragging to that element's content area? It wouldn't be keyboard-focusable, which would be strange, and it seems hacky for the user to have to style it as focused when the item itself is what's focused. Also it would require a completely different API, so I would in favor of holding off.

@rspbot

rspbot commented Oct 23, 2026

Copy link
Copy Markdown

@rspbot

rspbot commented Nov 2, 2026

Copy link
Copy Markdown

LFDanLu
LFDanLu previously approved these changes Nov 6, 2026
@rspbot

rspbot commented Nov 12, 2026

Copy link
Copy Markdown

@snowystinger snowystinger left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Test that asserts you can't drag from elsewhere? i see we check !draggable, but what happens if we try to drag anyways? or is this truly a good enough check? (some ignorance on my end about dragging)

);
}

// Firefox doesn't isolate focus and hover state between pages, so these tests are flaky when test files run in parallel.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe I've set concurrency to 1 so that they can't be run in parallel anymore since FF was so very bad, so can remove this comment now i hope

setting was fileParallelism: false,

hopefully means we can stop skipping it as well

* Native drag props, only provided via context by collection items whose drag button is the
* native drag source (e.g. pointerDragSource="handle"). Drag event handlers remain on the item.
*/
nativeDragProps?: ButtonNativeDragProps;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

anything wrong with exposing the draggable attributes on buttons in general?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm I guess not, I'll add them.

<GridList aria-label="Test" selectionMode="multiple" dragAndDropHooks={dragAndDropHooks}>
<GridListItem id="cat" textValue="Cat">
<Button slot="drag">≡</Button>
<ShadowText text="Cat" />

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why shadow text? what about shadow button?

}
});

// Expands the handle's touch target without affecting layout. The pseudo-element is positioned

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

probably should apply this in the starters as well, they're a little small

Comment on lines +137 to +151
// Expands the handle's touch target without affecting layout. The pseudo-element is positioned
// relative to the item (or cell), spanning its full height from the start edge to
// --dragHandleHitAreaWidth, so it doesn't overlap the selection checkbox.
const dragHandleHitArea = css(`
@media not ((hover: hover) and (pointer: fine)) {
&::before {
content: "";
position: absolute;
top: 0;
bottom: 0;
inset-inline-start: 0;
width: var(--dragHandleHitAreaWidth);
}
}
`);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@reidbarber

Copy link
Copy Markdown
Member Author

@snowystinger In that ListView screenshot, is touch device emulation on? It should only appear in that case.

@snowystinger

Copy link
Copy Markdown
Member

Ahhh, that makes sense

@rspbot

rspbot commented Nov 13, 2026

Copy link
Copy Markdown

@rspbot

rspbot commented Nov 13, 2026

Copy link
Copy Markdown
## API Changes

react-aria-components

/react-aria-components:Button

-Button {
+Button extends HTMLAttributes {
   aria-controls?: string
   aria-current?: boolean | 'true' | 'false' | 'page' | 'step' | 'location' | 'date' | 'time'
   aria-describedby?: string
   aria-disabled?: boolean | 'true' | 'false'
   aria-expanded?: boolean | 'true' | 'false'
   aria-haspopup?: boolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' | 'true' | 'false'
   aria-label?: string
   aria-labelledby?: string
   aria-pressed?: boolean | 'true' | 'false' | 'mixed'
   autoFocus?: boolean
   children?: ChildrenOrFunction<ButtonRenderProps>
   className?: ClassNameOrFunction<ButtonRenderProps> = 'react-aria-Button'
   excludeFromTabOrder?: boolean
   form?: string
   formAction?: ButtonHTMLAttributes<HTMLButtonElement>['formAction']
   formEncType?: string
   formMethod?: string
   formNoValidate?: boolean
   formTarget?: string
   id?: string
   isDisabled?: boolean
   isPending?: boolean
   name?: string
   onBlur?: (FocusEvent<Target>) => void
   onClick?: (MouseEvent<FocusableElement>) => void
   onFocus?: (FocusEvent<Target>) => void
   onFocusChange?: (boolean) => void
   onHoverChange?: (boolean) => void
   onHoverEnd?: (HoverEvent) => void
   onHoverStart?: (HoverEvent) => void
   onKeyDown?: (KeyboardEvent) => void
   onKeyUp?: (KeyboardEvent) => void
   onPress?: (PressEvent) => void
   onPressChange?: (boolean) => void
   onPressEnd?: (PressEvent) => void
   onPressStart?: (PressEvent) => void
   onPressUp?: (PressEvent) => void
   preventFocusOnPress?: boolean
   render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, ButtonRenderProps>
   slot?: string | null
   style?: StyleOrFunction<ButtonRenderProps>
   type?: 'button' | 'submit' | 'reset' = 'button'
   value?: string
 }

/react-aria-components:DragAndDropOptions

 DragAndDropOptions <T = {}> {
   acceptedDragTypes?: 'all' | Array<string | symbol> = 'all'
   dropTargetDelegate?: DropTargetDelegate
   getAllowedDropOperations?: () => Array<DropOperation>
   getDropOperation?: (DropTarget, DragTypes, Array<DropOperation>) => DropOperation
   getItems?: (Set<Key>, Array<T>) => Array<DragItem> = () => []
   isDisabled?: boolean
   onDragEnd?: (DraggableCollectionEndEvent) => void
   onDragMove?: (DraggableCollectionMoveEvent) => void
   onDragStart?: (DraggableCollectionStartEvent) => void
   onDrop?: (DroppableCollectionDropEvent) => void
   onDropActivate?: (DroppableCollectionActivateEvent) => void
   onDropEnter?: (DroppableCollectionEnterEvent) => void
   onDropExit?: (DroppableCollectionExitEvent) => void
   onInsert?: (DroppableCollectionInsertDropEvent) => void
   onItemDrop?: (DroppableCollectionOnItemDropEvent) => void
   onMove?: (DroppableCollectionReorderEvent) => void
   onReorder?: (DroppableCollectionReorderEvent) => void
   onRootDrop?: (DroppableCollectionRootDropEvent) => void
+  pointerDragSource?: 'item' | 'handle' = 'item'
   renderDragPreview?: (Array<DragItem>) => JSX.Element | {
     element: JSX.Element
   x: number
   y: number
   renderDropIndicator?: (DropTarget) => JSX.Element
   shouldAcceptItemDrop?: (ItemDropTarget, DragTypes) => boolean
 }

@react-spectrum/s2

/@react-spectrum/s2:DragAndDropOptions

 DragAndDropOptions <T = {}> {
   acceptedDragTypes?: 'all' | Array<string | symbol> = 'all'
   dropTargetDelegate?: DropTargetDelegate
   getAllowedDropOperations?: () => Array<DropOperation>
   getDropOperation?: (DropTarget, DragTypes, Array<DropOperation>) => DropOperation
   getItems?: (Set<Key>, Array<T>) => Array<DragItem> = () => []
   isDisabled?: boolean
   onDragEnd?: (DraggableCollectionEndEvent) => void
   onDragMove?: (DraggableCollectionMoveEvent) => void
   onDragStart?: (DraggableCollectionStartEvent) => void
   onDrop?: (DroppableCollectionDropEvent) => void
   onDropActivate?: (DroppableCollectionActivateEvent) => void
   onDropEnter?: (DroppableCollectionEnterEvent) => void
   onDropExit?: (DroppableCollectionExitEvent) => void
   onInsert?: (DroppableCollectionInsertDropEvent) => void
   onItemDrop?: (DroppableCollectionOnItemDropEvent) => void
   onMove?: (DroppableCollectionReorderEvent) => void
   onReorder?: (DroppableCollectionReorderEvent) => void
   onRootDrop?: (DroppableCollectionRootDropEvent) => void
+  pointerDragSource?: 'item' | 'handle' = 'item'
   renderDragPreview?: (Array<DragItem>) => JSX.Element | {
     element: JSX.Element
   x: number
   y: number
   shouldAcceptItemDrop?: (ItemDropTarget, DragTypes) => boolean
 }

@rspbot

rspbot commented Nov 13, 2026

Copy link
Copy Markdown

Agent Skills Changes

Modified (27)
Install

React Spectrum S2:

npx skills add https://d1pzu54gtk2aed.cloudfront.net/pr/fd0957f7d4b406bc4635f26fa0d6a62eeca2a987/

React Aria:

npx skills add https://d5iwopk28bdhl.cloudfront.net/pr/fd0957f7d4b406bc4635f26fa0d6a62eeca2a987/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Can't restrict Table drag to a drag handle

6 participants