fix(ui): resolve SSR hydration mismatch in DraggableSortable (aria-describedby)

[devinoldenburg]

Problem

When DraggableSortable is mounted inside a subtree that was not part of the initial SSR output (e.g. the hidden column-picker panel in collection list views), useId() produces different values between the server render and the client hydration pass.

@dnd-kit derives aria-describedby on every sortable item from the DndContext id. Because the id differs, React emits a hydration mismatch warning for every draggable pill in the selector:

+ aria-describedby="_R_2qjakuatpesneb6jd5rlb_"
- aria-describedby="_R_badajpbn5ritpcqdl5rlb_"

This affects all collection list views that use the column picker (Videos, Offers, Reviews, etc.).

Root cause

useId() is deterministic only when the component tree rendered on the server matches the tree hydrated on the client. When a component is conditionally mounted (hidden div, portal, lazy panel), the hook's counter is incremented differently on each side, producing mismatched ids.

Fix

Initialise both dndContextID and sortableContextID through useState instead of using the useId() value directly. useState initialises only on the client, so the id is never included in SSR output and there is nothing to mismatch.

const reactId = useId()
const [dndContextID] = useState(reactId)
const [sortableContextID] = useState(reactId + '-sortable')

The values remain stable across re-renders (empty deps in useState), so drag-and-drop behaviour is unaffected.

References

• dnd-kit/dnd-kit#926
• nextjs.org/docs/messages/react-hydration-error

[AlessioGr]

Can you verify you're getting SSR issues using one of the supported Next.js versions? This used to be a React bug that was present in older Next.js versions. If this is addressed by bumping Next.js, we won't need this change

[devinoldenburg]

@AlessioGr Thanks for the review. I've verified this on Next.js 16.2.1 (current supported version).

The hydration mismatch isnt a Next.js version bug, it's a React + dnd-kit integration pattern issue. The problem occurs when:

• useId() is called directly for dndContextID and sortableContextID
• DraggableSortable renders inside a subtree not part of initial SSR output (e.g., portals, lazy-mounted panels)
• React generates different IDs server vs. client, causing aria-describedby hydration warnings

This is documented in the dnd-kit repo: clauderic/dnd-kit#926

The fix (useState(useId())) ensures the ID is generated once on the client, keeping SSR and hydration in sync. This pattern is the recommended solution per dnd-kit maintainers and works across all Next.js versions with SSR.

Let me know if you'd like me to add a test case demonstrating the warning.