1---
2category: '@Integrations'
3---
4 
5# useSortable
6 
7Wrapper for [`sortable`](https://github.com/SortableJS/Sortable).
8 
9For more information on what options can be passed, see [`Sortable.options`](https://github.com/SortableJS/Sortable#options) in the `Sortable` documentation.
10 
11::: warning
12Currently, `useSortable` only implements drag-and-drop sorting for a single list.
13:::
14 
15## Install
16 
17```bash
18npm i sortablejs@^1
19```
20 
21## Usage
22 
23### Use template ref
24 
25```vue
26<script setup lang="ts">
27import { useSortable } from '@vueuse/integrations/useSortable'
28import { shallowRef, useTemplateRef } from 'vue'
29 
30const el = useTemplateRef('el')
31const list = shallowRef([{ id: 1, name: 'a' }, { id: 2, name: 'b' }, { id: 3, name: 'c' }])
32 
33useSortable(el, list)
34</script>
35 
36<template>
37  <div ref="el">
38    <div v-for="item in list" :key="item.id">
39      {{ item.name }}
40    </div>
41  </div>
42</template>
43```
44 
45### Use specifies the selector to operate on
46 
47```vue
48<script setup lang="ts">
49import { useSortable } from '@vueuse/integrations/useSortable'
50import { shallowRef, useTemplateRef } from 'vue'
51 
52const el = useTemplateRef('el')
53const list = shallowRef([{ id: 1, name: 'a' }, { id: 2, name: 'b' }, { id: 3, name: 'c' }])
54 
55const animation = 200
56 
57const { option } = useSortable(el, list, {
58  handle: '.handle',
59  // or option set
60  // animation
61})
62 
63// You can use the option method to set and get the option of Sortable
64option('animation', animation)
65// option('animation') // 200
66</script>
67 
68<template>
69  <div ref="el">
70    <div v-for="item in list" :key="item.id">
71      <span>{{ item.name }}</span>
72      <span class="handle">*</span>
73    </div>
74  </div>
75</template>
76```
77 
78### Use a selector to get the root element
79 
80```vue
81<script setup lang="ts">
82import { useSortable } from '@vueuse/integrations/useSortable'
83import { shallowRef } from 'vue'
84 
85const list = shallowRef([{ id: 1, name: 'a' }, { id: 2, name: 'b' }, { id: 3, name: 'c' }])
86 
87useSortable('#dv', list)
88</script>
89 
90<template>
91  <div id="dv">
92    <div v-for="item in list" :key="item.id">
93      <span>{{ item.name }}</span>
94    </div>
95  </div>
96</template>
97```
98 
99### Return Values
100 
101| Property | Description                                                      |
102| -------- | ---------------------------------------------------------------- |
103| `start`  | Initialize the Sortable instance (called automatically on mount) |
104| `stop`   | Destroy the Sortable instance                                    |
105| `option` | Get or set Sortable options at runtime                           |
106 
107```ts
108const { start, stop, option } = useSortable(el, list)
109 
110// Stop sorting
111stop()
112 
113// Start sorting again
114start()
115 
116// Get/set options
117option('animation', 200) // set
118const animation = option('animation') // get
119```
120 
121### Watch Element Changes
122 
123Use the `watchElement` option to automatically reinitialize Sortable when the element changes (useful with `v-if`).
124 
125```ts
126import { useSortable } from '@vueuse/integrations/useSortable'
127 
128useSortable(el, list, {
129  watchElement: true, // auto-reinitialize when element changes
130})
131```
132 
133### Custom Update Handler
134 
135If you want to handle the `onUpdate` yourself, you can pass in `onUpdate` parameters, and we also exposed a function to move the item position.
136 
137```ts
138import { moveArrayElement, useSortable } from '@vueuse/integrations/useSortable'
139 
140useSortable(el, list, {
141  onUpdate: (e) => {
142    // do something
143    moveArrayElement(list, e.oldIndex, e.newIndex, e)
144    // nextTick required here as moveArrayElement is executed in a microtask
145    // so we need to wait until the next tick until that is finished.
146    nextTick(() => {
147      /* do something */
148    })
149  }
150})
151```
152 
153### Helper Functions
154 
155The following helper functions are also exported:
156 
157| Function                                   | Description                                           |
158| ------------------------------------------ | ----------------------------------------------------- |
159| `moveArrayElement(list, from, to, event?)` | Move an element in an array from one index to another |
160| `insertNodeAt(parent, element, index)`     | Insert a DOM node at a specific index                 |
161| `removeNode(node)`                         | Remove a DOM node from its parent                     |
162 
163## Type Declarations
164 
165```ts
166export interface UseSortableReturn {
167  /**
168   * start sortable instance
169   */
170  start: () => void
171  /**
172   * destroy sortable instance
173   */
174  stop: () => void
175  /**
176   * Options getter/setter
177   * @param name a Sortable.Options property.
178   * @param value a value.
179   */
180  option: (<K extends keyof Sortable.Options>(
181    name: K,
182    value: Sortable.Options[K],
183  ) => void) &
184    (<K extends keyof Sortable.Options>(name: K) => Sortable.Options[K])
185}
186export interface UseSortableOptions extends Options, ConfigurableDocument {
187  /**
188   * Watch the element reference for changes and automatically reinitialize Sortable
189   * when the element changes.
190   *
191   * When `false` (default), Sortable is only initialized once on mount.
192   * You must manually call `start()` if the element reference changes.
193   *
194   * When `true`, automatically watches the element reference and reinitializes
195   * Sortable whenever it changes (e.g., conditional rendering with v-if).
196   *
197   * @default false
198   */
199  watchElement?: boolean
200}
201export declare function useSortable<T>(
202  selector: string,
203  list: MaybeRef<T[]>,
204  options?: UseSortableOptions,
205): UseSortableReturn
206export declare function useSortable<T>(
207  el: MaybeRefOrGetter<MaybeElement>,
208  list: MaybeRef<T[]>,
209  options?: UseSortableOptions,
210): UseSortableReturn
211/**
212 * Inserts a element into the DOM at a given index.
213 * @param parentElement
214 * @param element
215 * @param {number} index
216 * @see https://github.com/Alfred-Skyblue/vue-draggable-plus/blob/a3829222095e1949bf2c9a20979d7b5930e66f14/src/utils/index.ts#L81C1-L94C2
217 */
218export declare function insertNodeAt(
219  parentElement: Element,
220  element: Element,
221  index: number,
222): void
223/**
224 * Removes a node from the DOM.
225 * @param {Node} node
226 * @see https://github.com/Alfred-Skyblue/vue-draggable-plus/blob/a3829222095e1949bf2c9a20979d7b5930e66f14/src/utils/index.ts#L96C1-L102C2
227 */
228export declare function removeNode(node: Node): void
229export declare function moveArrayElement<T>(
230  list: MaybeRef<T[]>,
231  from: number,
232  to: number,
233  e?: Sortable.SortableEvent | null,
234): void
235```
236