Skip to content

useSortable

Category
Export Size
572 B
Package
@vueuse/integrations
Last Changed
2 months ago

Wrapper for sortable.

For more information on what options can be passed, see Sortable.options in the Sortable documentation.

WARNING

Currently, useSortable only implements drag-and-drop sorting for a single list.

Demo

a
b
c
[{"id":1,"name":"a"},{"id":2,"name":"b"},{"id":3,"name":"c"}]
Available in the @vueuse/integrations add-on.

Install

bash
npm i sortablejs@^1

Usage

Use template ref

vue
<script setup lang="ts">
import { 
useSortable
} from '@vueuse/integrations/useSortable'
import {
shallowRef
,
useTemplateRef
} from 'vue'
const
el
=
useTemplateRef
<HTMLElement>('el')
const
list
=
shallowRef
([{
id
: 1,
name
: 'a' }, {
id
: 2,
name
: 'b' }, {
id
: 3,
name
: 'c' }])
useSortable
(
el
,
list
)
</script> <template> <
div
ref
="
el
">
<
div
v-for="
item
in
list
"
:key
="
item
.
id
">
{{
item
.
name
}}
</
div
>
</
div
>
</template>

Use specifies the selector to operate on

vue
<script setup lang="ts">
import { 
useSortable
} from '@vueuse/integrations/useSortable'
import {
shallowRef
,
useTemplateRef
} from 'vue'
const
el
=
useTemplateRef
<HTMLElement>('el')
const
list
=
shallowRef
([{
id
: 1,
name
: 'a' }, {
id
: 2,
name
: 'b' }, {
id
: 3,
name
: 'c' }])
const
animation
= 200
const {
option
} =
useSortable
(
el
,
list
, {
handle
: '.handle',
// or option set // animation }) // You can use the option method to set and get the option of Sortable
option
('animation',
animation
)
// option('animation') // 200 </script> <template> <
div
ref
="
el
">
<
div
v-for="
item
in
list
"
:key
="
item
.
id
">
<
span
>{{
item
.
name
}}</
span
>
<
span
class
="handle">*</
span
>
</
div
>
</
div
>
</template>

Use a selector to get the root element

vue
<script setup lang="ts">
import { 
useSortable
} from '@vueuse/integrations/useSortable'
import {
shallowRef
} from 'vue'
const
list
=
shallowRef
([{
id
: 1,
name
: 'a' }, {
id
: 2,
name
: 'b' }, {
id
: 3,
name
: 'c' }])
useSortable
('#dv',
list
)
</script> <template> <
div
id
="dv">
<
div
v-for="
item
in
list
"
:key
="
item
.
id
">
<
span
>{{
item
.
name
}}</
span
>
</
div
>
</
div
>
</template>

Tips

If you want to handle the onUpdate yourself, you can pass in onUpdate parameters, and we also exposed a function to move the item position.

ts
import { 
moveArrayElement
,
useSortable
} from '@vueuse/integrations/useSortable'
useSortable
(el, list, {
onUpdate
: (
e
) => {
// do something
moveArrayElement
(list,
e
.
oldIndex
,
e
.
newIndex
,
e
)
// nextTick required here as moveArrayElement is executed in a microtask // so we need to wait until the next tick until that is finished.
nextTick
(() => {
/* do something */ }) } })

Type Declarations

Show Type Declarations
ts
export interface UseSortableReturn {
  /**
   * start sortable instance
   */
  
start
: () => void
/** * destroy sortable instance */
stop
: () => void
/** * Options getter/setter * @param name a Sortable.Options property. * @param value a value. */
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 declare function
useSortable
<
T
>(
selector
: string,
list
:
MaybeRef
<
T
[]>,
options
?:
UseSortableOptions
,
): UseSortableReturn export declare function
useSortable
<
T
>(
el
:
MaybeRefOrGetter
<
MaybeElement
>,
list
:
MaybeRef
<
T
[]>,
options
?:
UseSortableOptions
,
): UseSortableReturn /** * Inserts a element into the DOM at a given index. * @param parentElement * @param element * @param {number} index * @see https://github.com/Alfred-Skyblue/vue-draggable-plus/blob/a3829222095e1949bf2c9a20979d7b5930e66f14/src/utils/index.ts#L81C1-L94C2 */ export declare function
insertNodeAt
(
parentElement
: Element,
element
: Element,
index
: number,
): void /** * Removes a node from the DOM. * @param {Node} node * @see https://github.com/Alfred-Skyblue/vue-draggable-plus/blob/a3829222095e1949bf2c9a20979d7b5930e66f14/src/utils/index.ts#L96C1-L102C2 */ export declare function
removeNode
(
node
: Node): void
export declare function
moveArrayElement
<
T
>(
list
:
MaybeRef
<
T
[]>,
from
: number,
to
: number,
e
?: Sortable.
SortableEvent
| null,
): void

Source

SourceDemoDocs

Contributors

Anthony Fu
IlyaL
丶远方
Anthony Fu
James Garbutt
Michael Cozzolino
Doctorwu
SerKo
IlyaL
Yu Lia
Robin
Robin
David Gonzalez
Tycho
George Kinsman

Changelog

v13.3.0 on
16692 - fix: fix type misalignment (#4760)
v13.1.0 on
15917 - feat: Add possibility to use it with Component ref (#4684)
v12.8.0 on
7432f - feat(types): deprecate MaybeRef and MaybeRefOrGetter in favor of Vue's native (#4636)
v12.3.0 on
59f75 - feat(toValue): deprecate toValue from @vueuse/shared in favor of Vue's native
v12.0.0-beta.1 on
0a9ed - feat!: drop Vue 2 support, optimize bundles and clean up (#4349)
v11.3.0 on
9e78e - fix: wrong order of elements (#4332)
v10.8.0 on
a086e - fix: stricter types
v10.6.0 on
d9846 - fix: prevent from creating multi instances (#3501)
v10.4.0 on
b8515 - fix: fixed moveArrayElement repeatedly triggering side effects (#3322)
v10.2.0 on
14283 - feat: add option set get method (#3108)
v10.0.0-beta.4 on
4d757 - feat(types)!: rename MaybeComputedRef to MaybeRefOrGetter
0a72b - feat(toValue): rename resolveUnref to toValue
v10.0.0-beta.3 on
3a508 - fix: order of dom and array is different (#2926)

Released under the MIT License.

Build faster with AI
New Masterclass to help you leverage AI in your Vue workflow
Get Early Access