Skip to content

useDraggable

Category
Export Size
1.37 kB
Last Changed
5 months ago

Make elements draggable.

Demo

Check the floating boxes

👋 Drag me!
I am at 343, 80
Renderless component
Position persisted in sessionStorage
369, 150
👋 Drag here!
Handle that triggers the drag event
I am at 400, 240
Not Use Captured Element
Dragging here will not work
436, 330

Usage

vue
<script setup lang="ts">
import { 
useDraggable
} from '@vueuse/core'
import {
useTemplateRef
} from 'vue'
const
el
=
useTemplateRef
<HTMLElement>('el')
// `style` will be a helper computed for `left: ?px; top: ?px;` const {
x
,
y
,
style
} =
useDraggable
(
el
, {
initialValue
: {
x
: 40,
y
: 40 },
}) </script> <template> <
div
ref
="
el
"
:style
="
style
"
style
="position: fixed">
Drag me! I am at {{
x
}}, {{
y
}}
</
div
>
</template>

Set preventDefault: true to override the default drag-and-drop behavior of certain elements in the browser.

ts
const { 
x
,
y
,
style
} =
useDraggable
(el, {
preventDefault
: true,
// with `preventDefault: true` // you can disable the native behavior (e.g., for img) // and control the drag-and-drop, preventing the browser interference. })

Component Usage

This function also provides a renderless component version via the @vueuse/components package. Learn more about the usage.

vue
<template>
  <UseDraggable v-slot="{ 
x
,
y
}"
:initial-value
="{
x
: 10,
y
: 10 }">
Drag me! I am at {{
x
}}, {{
y
}}
</UseDraggable> </template>

For component usage, additional props storageKey and storageType can be passed to the component and enable the persistence of the element position.

vue
<template>
  <UseDraggable 
storage-key
="vueuse-draggable"
storage-type
="session">
Refresh the page and I am still in the same position! </UseDraggable> </template>

Type Declarations

Show Type Declarations
ts
export interface UseDraggableOptions {
  /**
   * Only start the dragging when click on the element directly
   *
   * @default false
   */
  
exact
?:
MaybeRefOrGetter
<boolean>
/** * Prevent events defaults * * @default false */
preventDefault
?:
MaybeRefOrGetter
<boolean>
/** * Prevent events propagation * * @default false */
stopPropagation
?:
MaybeRefOrGetter
<boolean>
/** * Whether dispatch events in capturing phase * * @default true */
capture
?: boolean
/** * Element to attach `pointermove` and `pointerup` events to. * * @default window */
draggingElement
?:
MaybeRefOrGetter
<
HTMLElement | SVGElement | Window | Document | null | undefined > /** * Element for calculating bounds (If not set, it will use the event's target). * * @default undefined */
containerElement
?:
MaybeRefOrGetter
<
HTMLElement | SVGElement | null | undefined > /** * Handle that triggers the drag event * * @default target */
handle
?:
MaybeRefOrGetter
<HTMLElement | SVGElement | null | undefined>
/** * Pointer types that listen to. * * @default ['mouse', 'touch', 'pen'] */
pointerTypes
?:
PointerType
[]
/** * Initial position of the element. * * @default { x: 0, y: 0 } */
initialValue
?:
MaybeRefOrGetter
<
Position
>
/** * Callback when the dragging starts. Return `false` to prevent dragging. */
onStart
?: (
position
:
Position
,
event
: PointerEvent) => void | false
/** * Callback during dragging. */
onMove
?: (
position
:
Position
,
event
: PointerEvent) => void
/** * Callback when dragging end. */
onEnd
?: (
position
:
Position
,
event
: PointerEvent) => void
/** * Axis to drag on. * * @default 'both' */
axis
?: "x" | "y" | "both"
/** * Disabled drag and drop. * * @default false */
disabled
?:
MaybeRefOrGetter
<boolean>
/** * Mouse buttons that are allowed to trigger drag events. * * - `0`: Main button, usually the left button or the un-initialized state * - `1`: Auxiliary button, usually the wheel button or the middle button (if present) * - `2`: Secondary button, usually the right button * - `3`: Fourth button, typically the Browser Back button * - `4`: Fifth button, typically the Browser Forward button * * @see https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button#value * @default [0] */
buttons
?:
MaybeRefOrGetter
<number[]>
} /** * Make elements draggable. * * @see https://vueuse.org/useDraggable * @param target * @param options */ export declare function
useDraggable
(
target
:
MaybeRefOrGetter
<HTMLElement | SVGElement | null | undefined>,
options
?: UseDraggableOptions,
): | {
position
:
Ref
<
{
x
: number
y
: number
}, |
Position
| {
x
: number
y
: number
} >
isDragging
:
ComputedRef
<boolean>
style
:
ComputedRef
<string>
x
:
Ref
<number, number>
y
:
Ref
<number, number>
} | {
position
:
Ref
<
{
x
: number
y
: number
}, |
Position
| {
x
: number
y
: number
} >
isDragging
:
ComputedRef
<boolean>
style
:
ComputedRef
<string>
x
:
Ref
<number, number>
y
:
Ref
<number, number>
} export type
UseDraggableReturn
=
ReturnType
<typeof
useDraggable
>

Source

SourceDemoDocs

Contributors

Anthony Fu
huiliangShen
Anthony Fu
IlyaL
丶远方
webfansplz
Shigma
SerKo
wgh970312
IlyaL
Robin
Fernando Fernández
Alex Peshkov
Joona Tiinanen
GU Yiling
wangliangxin
Kazim Duran
Jessé Correia Lins
faga
vaakian X
Akiho Nagao
stefnotch
btea
guolao
vaakian X
Jelf
donotloveshampo
Julian Meinking
Jukka Raimovaara
wheat

Changelog

v13.6.0 on
547f8 - fix: add capture prop to component (#4911)
v12.8.0 on
7432f - feat(types): deprecate MaybeRef and MaybeRefOrGetter in favor of Vue's native (#4636)
v12.4.0 on
dd316 - feat: use passive event handlers everywhere is possible (#4477)
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.1.0 on
7f25b - fix: draggable component not work with container (#4192)
v11.0.0-beta.2 on
e9938 - feat: add buttons option (#4084)
v10.10.0 on
9f10a - fix: should ignore right clicks (#3850)
v10.8.0 on
dee9a - feat: add disabled parameter (#3613)
55b94 - fix: avoid moving out of container (#3768)
v10.7.2 on
bdd79 - fix: can not work well when parent element is scrollable (#3692)
v10.6.0 on
08246 - fix: element can't relative parent element move (#3531)
v10.4.0 on
c08e5 - feat: allowing calculations of bounds with fixed element (#3335)
v10.2.0 on
6b670 - feat: improve component props (#3075)
v10.0.0-beta.4 on
3996d - feat: support capture option (#2725)
4d757 - feat(types)!: rename MaybeComputedRef to MaybeRefOrGetter
0a72b - feat(toValue): rename resolveUnref to toValue
v10.0.0-beta.3 on
0842a - feat: introduce axis option (#2948)

Released under the MIT License.

FREE WEEKEND
48 Hours of Unlimited Official Vue.js Certification Training
Reserve Your Spot
23-24 August