feat(useSortable): add watchElement option for auto-reinitialize on element change (#5189)

Mini-ghost · ilyaliao · web-flow · commit 17ea28810f79 · 2026-01-14T08:14:14.000Z
Co-authored-by: IlyaL &lt;ilyaliao324@gmail.com&gt;
diff --git a/packages/integrations/useSortable/index.browser.test.ts b/packages/integrations/useSortable/index.browser.test.ts
@@ -6,7 +6,7 @@ import { defineComponent, shallowRef, useTemplateRef } from 'vue'
 import { useSortable } from './index'
 
 describe('useSortable', () => {
-  it('should initialise Sortable', () => {
+  it('should initialize Sortable', () => {
     const wrapper = mount(defineComponent({
       template: '<div ref="el"></div>',
       setup() {
@@ -179,4 +179,141 @@ describe('useSortable', () => {
       wrapper.unmount()
     }
   })
+
+  describe('watchElement', () => {
+    it('should auto-reinitialize when element changes with watchElement: true', async () => {
+      const wrapper = mount(defineComponent({
+        template: '<div v-if="show" ref="el"></div>',
+        setup() {
+          const el = useTemplateRef<HTMLElement>('el')
+          const show = shallowRef(true)
+          const list = shallowRef<string[]>([])
+          const result = useSortable(el, list, {
+            watchElement: true,
+          })
+
+          return { ...result, el, show }
+        },
+      }))
+      const vm = wrapper.vm
+      try {
+        await wrapper.vm.$nextTick()
+
+        expect(vm.el).toBeDefined()
+        let sortable = Sortable.get(vm.el!)
+        expect(sortable).toBeDefined()
+
+        vm.show = false
+        await wrapper.vm.$nextTick()
+        expect(vm.el).toBeNull()
+
+        vm.show = true
+        await wrapper.vm.$nextTick()
+        await wrapper.vm.$nextTick()
+        expect(vm.el).toBeDefined()
+
+        // Should be automatically reinitialized
+        sortable = Sortable.get(vm.el!)
+        expect(sortable).toBeDefined()
+      }
+      finally {
+        wrapper.unmount()
+      }
+    })
+
+    it('should NOT auto-reinitialize when element changes with watchElement: false', async () => {
+      const wrapper = mount(defineComponent({
+        template: '<div v-if="show" ref="el"></div>',
+        setup() {
+          const el = useTemplateRef<HTMLElement>('el')
+          const show = shallowRef(true)
+          const list = shallowRef<string[]>([])
+          const result = useSortable(el, list, {
+            watchElement: false,
+          })
+
+          return { ...result, el, show }
+        },
+      }))
+      const vm = wrapper.vm
+      try {
+        expect(vm.el).toBeDefined()
+        const firstElement = vm.el!
+        let sortable = Sortable.get(firstElement)
+        expect(sortable).toBeDefined()
+        const firstInstance = sortable
+
+        vm.show = false
+        await wrapper.vm.$nextTick()
+        expect(vm.el).toBeNull()
+
+        vm.show = true
+        await wrapper.vm.$nextTick()
+        expect(vm.el).toBeDefined()
+        const secondElement = vm.el!
+
+        expect(secondElement).not.toBe(firstElement)
+
+        // New element should not have Sortable
+        sortable = Sortable.get(secondElement)
+        expect(sortable).toBeFalsy()
+
+        // Old instance still bound to removed element
+        sortable = Sortable.get(firstElement)
+        expect(sortable).toBe(firstInstance)
+
+        // Manual cleanup and reinitialize required
+        vm.stop()
+        vm.start()
+        sortable = Sortable.get(secondElement)
+        expect(sortable).toBeDefined()
+      }
+      finally {
+        wrapper.unmount()
+      }
+    })
+
+    it('should work with conditional rendering using watchElement: true', async () => {
+      const wrapper = mount(defineComponent({
+        template: `
+          <div>
+            <div v-if="condition === 'a'" ref="el" data-test="a"></div>
+            <div v-if="condition === 'b'" ref="el" data-test="b"></div>
+          </div>
+        `,
+        setup() {
+          const el = useTemplateRef<HTMLElement>('el')
+          const condition = shallowRef<'a' | 'b'>('a')
+          const list = shallowRef<string[]>([])
+          const result = useSortable(el, list, {
+            watchElement: true,
+          })
+
+          return { ...result, el, condition }
+        },
+      }))
+      const vm = wrapper.vm
+      try {
+        await wrapper.vm.$nextTick()
+
+        expect(vm.el?.getAttribute('data-test')).toBe('a')
+        let sortable = Sortable.get(vm.el!)
+        expect(sortable).toBeDefined()
+        const firstInstance = sortable
+
+        vm.condition = 'b'
+        await wrapper.vm.$nextTick()
+        await wrapper.vm.$nextTick()
+        expect(vm.el?.getAttribute('data-test')).toBe('b')
+
+        // Should be a new instance
+        sortable = Sortable.get(vm.el!)
+        expect(sortable).toBeDefined()
+        expect(sortable).not.toBe(firstInstance)
+      }
+      finally {
+        wrapper.unmount()
+      }
+    })
+  })
 })
diff --git a/packages/integrations/useSortable/index.ts b/packages/integrations/useSortable/index.ts
@@ -3,7 +3,7 @@ import type { Options } from 'sortablejs'
 import type { MaybeRef, MaybeRefOrGetter } from 'vue'
 import { defaultDocument, tryOnMounted, tryOnScopeDispose, unrefElement } from '@vueuse/core'
 import Sortable from 'sortablejs'
-import { isRef, nextTick, toValue } from 'vue'
+import { computed, isRef, nextTick, toValue, watch } from 'vue'
 
 export interface UseSortableReturn {
   /**
@@ -23,7 +23,21 @@ export interface UseSortableReturn {
   option: (<K extends keyof Sortable.Options>(name: K, value: Sortable.Options[K]) => void) & (<K extends keyof Sortable.Options>(name: K) => Sortable.Options[K])
 }
 
-export type UseSortableOptions = Options & ConfigurableDocument
+export interface UseSortableOptions extends Options, ConfigurableDocument {
+  /**
+   * Watch the element reference for changes and automatically reinitialize Sortable
+   * when the element changes.
+   *
+   * When `false` (default), Sortable is only initialized once on mount.
+   * You must manually call `start()` if the element reference changes.
+   *
+   * When `true`, automatically watches the element reference and reinitializes
+   * Sortable whenever it changes (e.g., conditional rendering with v-if).
+   *
+   * @default false
+   */
+  watchElement?: boolean
+}
 
 export function useSortable<T>(selector: string, list: MaybeRef<T[]>,
   options?: UseSortableOptions): UseSortableReturn
@@ -43,24 +57,31 @@ export function useSortable<T>(
 ): UseSortableReturn {
   let sortable: Sortable | undefined
 
-  const { document = defaultDocument, ...resetOptions } = options
+  const { document = defaultDocument, watchElement = false, ...resetOptions } = options
 
   const defaultOptions: Options = {
     onUpdate: (e) => {
       moveArrayElement(list, e.oldIndex!, e.newIndex!, e)
     },
   }
 
-  const start = () => {
-    const target = (typeof el === 'string' ? document?.querySelector(el) : unrefElement(el))
+  const element = computed(() => (typeof el === 'string' ? document?.querySelector(el) : unrefElement(el)))
+
+  const cleanup = () => {
+    sortable?.destroy()
+    sortable = undefined
+  }
+
+  const initSortable = (target: Element) => {
     if (!target || sortable !== undefined)
       return
     sortable = new Sortable(target as HTMLElement, { ...defaultOptions, ...resetOptions })
   }
 
-  const stop = () => {
-    sortable?.destroy()
-    sortable = undefined
+  const start = () => {
+    const target = element.value
+    if (target)
+      initSortable(target)
   }
 
   const option = <K extends keyof Options>(name: K, value?: Options[K]) => {
@@ -70,9 +91,34 @@ export function useSortable<T>(
       return sortable?.option(name)
   }
 
-  tryOnMounted(start)
+  // Conditionally set up element watching
+  let stopWatch: (() => void) | undefined
+
+  if (watchElement && typeof el !== 'string') {
+    // New behavior: watch element changes and auto-reinitialize
+    stopWatch = watch(
+      element,
+      (newElement) => {
+        cleanup()
+        if (newElement)
+          initSortable(newElement)
+      },
+      { immediate: true, flush: 'post' },
+    )
+  }
+  else {
+    // Default behavior: initialize once on mount
+    tryOnMounted(start)
+  }
+
+  const stop = () => {
+    cleanup()
+  }
 
-  tryOnScopeDispose(stop)
+  tryOnScopeDispose(() => {
+    stopWatch?.()
+    cleanup()
+  })
 
   return {
     stop,
