Skip to content

useDraggable ​

Category
Export Size
1.36 kB
Last Changed
3 weeks ago

Make elements draggable.

Demo ​

Check the floating boxes

👋 Drag me!
I am at 48, 80
Renderless component
Position persisted in sessionStorage
51, 150
👋 Drag here!
Handle that triggers the drag event
I am at 56, 240

Usage ​

vue
<script setup lang="ts">
import { ref } from 'vue'
import { useDraggable } from '@vueuse/core'

const el = ref<HTMLElement | null>(null)

// `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>

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
typescript
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>
}
/**
 * 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
  }>
  isDragging: ComputedRef<boolean>
  style: ComputedRef<string>
  x: Ref<number>
  y: Ref<number>
}
export type UseDraggableReturn = ReturnType<typeof useDraggable>

Source ​

Source • Demo • Docs

Contributors ​

Anthony Fu
huiliangShen
丶远方
webfansplz
Shigma
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 ​

Pending for release...
9f10a - fix: should ignore right clicks (#3850)
v10.8.0 on 2/20/2024
dee9a - feat: add disabled parameter (#3613)
55b94 - fix: avoid moving out of container (#3768)
v10.7.2 on 1/14/2024
bdd79 - fix: can not work well when parent element is scrollable (#3692)
v10.6.0 on 11/9/2023
08246 - fix: element can't relative parent element move (#3531)
v10.4.0 on 8/25/2023
c08e5 - feat: allowing calculations of bounds with fixed element (#3335)
v10.2.0 on 6/16/2023
6b670 - feat: improve component props (#3075)
v10.0.0-beta.4 on 4/13/2023
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 4/12/2023
0842a - feat: introduce axis option (#2948)
v9.11.0 on 1/17/2023
d5321 - fix(components): mark defineComponent as pure (#2623)
e39c2 - fix: write to useStorage (#2575)
v9.7.0 on 12/16/2022
c9186 - fix: use clientX instead of pageX, close #2053 (#2054)
v9.2.0 on 9/5/2022
33587 - feat: support customizing trigger element (#2133)

Released under the MIT License.