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### Using Component
100 
101```vue
102<script setup lang="ts">
103import { UseSortable } from '@vueuse/integrations/useSortable/component'
104import { shallowRef } from 'vue'
105 
106const list = shallowRef([
107  { id: 1, name: 'a' },
108  { id: 2, name: 'b' },
109  { id: 3, name: 'c' },
110])
111</script>
112 
113<template>
114  <UseSortable v-model="list" as="ol" :options="{ animation: 150 }">
115    <li v-for="item in list" :key="item.id">
116      {{ item.name }}
117    </li>
118  </UseSortable>
119</template>
120```
121 
122You can also access the helper functions like `start`, `stop`, and `option` from the slot scope:
123 
124```vue
125<template>
126  <UseSortable v-slot="{ stop, start }" v-model="list">
127    <button @click="stop()">
128      Stop Sorting
129    </button>
130    <button @click="start()">
131      Start Sorting
132    </button>
133    <div v-for="item in list" :key="item.id">
134      {{ item.name }}
135    </div>
136  </UseSortable>
137</template>
138```
139 
140### Return Values
141 
142| Property | Description                                                      |
143| -------- | ---------------------------------------------------------------- |
144| `start`  | Initialize the Sortable instance (called automatically on mount) |
145| `stop`   | Destroy the Sortable instance                                    |
146| `option` | Get or set Sortable options at runtime                           |
147 
148```ts
149const { start, stop, option } = useSortable(el, list)
150 
151// Stop sorting
152stop()
153 
154// Start sorting again
155start()
156 
157// Get/set options
158option('animation', 200) // set
159const animation = option('animation') // get
160```
161 
162### Watch Element Changes
163 
164Use the `watchElement` option to automatically reinitialize Sortable when the element changes (useful with `v-if`).
165 
166```ts
167import { useSortable } from '@vueuse/integrations/useSortable'
168 
169useSortable(el, list, {
170  watchElement: true, // auto-reinitialize when element changes
171})
172```
173 
174### Custom Update Handler
175 
176If you want to handle the `onUpdate` yourself, you can pass in `onUpdate` parameters, and we also exposed a function to move the item position.
177 
178```ts
179import { moveArrayElement, useSortable } from '@vueuse/integrations/useSortable'
180 
181useSortable(el, list, {
182  onUpdate: (e) => {
183    // do something
184    moveArrayElement(list, e.oldIndex, e.newIndex, e)
185    // nextTick required here as moveArrayElement is executed in a microtask
186    // so we need to wait until the next tick until that is finished.
187    nextTick(() => {
188      /* do something */
189    })
190  }
191})
192```
193 
194### Helper Functions
195 
196The following helper functions are also exported:
197 
198| Function                                   | Description                                           |
199| ------------------------------------------ | ----------------------------------------------------- |
200| `moveArrayElement(list, from, to, event?)` | Move an element in an array from one index to another |
201| `insertNodeAt(parent, element, index)`     | Insert a DOM node at a specific index                 |
202| `removeNode(node)`                         | Remove a DOM node from its parent                     |
203 
204## Type Declarations
205 
206```ts
207export interface UseSortableReturn {
208  /**
209   * start sortable instance
210   */
211  start: () => void
212  /**
213   * destroy sortable instance
214   */
215  stop: () => void
216  /**
217   * Options getter/setter
218   * @param name a Sortable.Options property.
219   * @param value a value.
220   */
221  option: (<K extends keyof Sortable.Options>(
222    name: K,
223    value: Sortable.Options[K],
224  ) => void) &
225    (<K extends keyof Sortable.Options>(name: K) => Sortable.Options[K])
226}
227export interface UseSortableOptions extends Options, ConfigurableDocument {
228  /**
229   * Watch the element reference for changes and automatically reinitialize Sortable
230   * when the element changes.
231   *
232   * When `false` (default), Sortable is only initialized once on mount.
233   * You must manually call `start()` if the element reference changes.
234   *
235   * When `true`, automatically watches the element reference and reinitializes
236   * Sortable whenever it changes (e.g., conditional rendering with v-if).
237   *
238   * @default false
239   */
240  watchElement?: boolean
241}
242export declare function useSortable<T>(
243  selector: string,
244  list: MaybeRef<T[]>,
245  options?: UseSortableOptions,
246): UseSortableReturn
247export declare function useSortable<T>(
248  el: MaybeRefOrGetter<MaybeElement>,
249  list: MaybeRef<T[]>,
250  options?: UseSortableOptions,
251): UseSortableReturn
252/**
253 * Inserts a element into the DOM at a given index.
254 * @param parentElement
255 * @param element
256 * @param {number} index
257 * @see https://github.com/Alfred-Skyblue/vue-draggable-plus/blob/a3829222095e1949bf2c9a20979d7b5930e66f14/src/utils/index.ts#L81C1-L94C2
258 */
259export declare function insertNodeAt(
260  parentElement: Element,
261  element: Element,
262  index: number,
263): void
264/**
265 * Removes a node from the DOM.
266 * @param {Node} node
267 * @see https://github.com/Alfred-Skyblue/vue-draggable-plus/blob/a3829222095e1949bf2c9a20979d7b5930e66f14/src/utils/index.ts#L96C1-L102C2
268 */
269export declare function removeNode(node: Node): void
270export declare function moveArrayElement<T>(
271  list: MaybeRef<T[]>,
272  from: number,
273  to: number,
274  e?: Sortable.SortableEvent | null,
275): void
276```
277