VueUse

Appearance

Return to top
On this page

useDraggable

Category
Last Changed
3 months ago

Make elements draggable.

Demo

source

👋 Drag me!
I am at 48, 80
Renderless component
Position persisted in sessionStorage
51, 150

Usage 

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

<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. 

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

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

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

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

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

Type Declarations

Show Type Declarations
export interface UseDraggableOptions {
  /**
   * Only start the dragging when click on the element directly
   *
   * @default false
   */
  exact?: MaybeRef<boolean>
  /**
   * Prevent events defaults
   *
   * @default false
   */
  preventDefault?: MaybeRef<boolean>
  /**
   * Prevent events propagation
   *
   * @default false
   */
  stopPropagation?: MaybeRef<boolean>
  /**
   * Element to attach `pointermove` and `pointerup` events to.
   *
   * @default window
   */
  draggingElement?: MaybeRef<
    HTMLElement | SVGElement | Window | Document | null | undefined
  >
  /**
   * Pointer types that listen to.
   *
   * @default ['mouse', 'touch', 'pen']
   */
  pointerTypes?: PointerType[]
  /**
   * Initial position of the element.
   *
   * @default { x: 0, y: 0}
   */
  initialValue?: MaybeRef<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
}
/**
 * Make elements draggable.
 *
 * @see https://vueuse.org/useDraggable
 * @param target
 * @param options
 */
export declare function useDraggable(
  target: MaybeRef<HTMLElement | SVGElement | null | undefined>,
  options?: UseDraggableOptions
): {
  position: Ref<Position>
  isDragging: ComputedRef<boolean>
  style: ComputedRef<string>
  x: Ref<number>
  y: Ref<number>
}

export interface UseDraggableOptions {
  /**
   * Only start the dragging when click on the element directly
   *
   * @default false
   */
  exact?: MaybeRef<boolean>
  /**
   * Prevent events defaults
   *
   * @default false
   */
  preventDefault?: MaybeRef<boolean>
  /**
   * Prevent events propagation
   *
   * @default false
   */
  stopPropagation?: MaybeRef<boolean>
  /**
   * Element to attach `pointermove` and `pointerup` events to.
   *
   * @default window
   */
  draggingElement?: MaybeRef<
    HTMLElement | SVGElement | Window | Document | null | undefined
  >
  /**
   * Pointer types that listen to.
   *
   * @default ['mouse', 'touch', 'pen']
   */
  pointerTypes?: PointerType[]
  /**
   * Initial position of the element.
   *
   * @default { x: 0, y: 0}
   */
  initialValue?: MaybeRef<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
}
/**
 * Make elements draggable.
 *
 * @see https://vueuse.org/useDraggable
 * @param target
 * @param options
 */
export declare function useDraggable(
  target: MaybeRef<HTMLElement | SVGElement | null | undefined>,
  options?: UseDraggableOptions
): {
  position: Ref<Position>
  isDragging: ComputedRef<boolean>
  style: ComputedRef<string>
  x: Ref<number>
  y: Ref<number>
}

Source

Source • Demo • Docs

Contributors

Anthony Fu
webfansplz
Shigma
donotloveshampo
Julian Meinking
Jukka Raimovaara
wheat

Changelog

v8.6.0 on 5/31/2022
5e315 - fix: should pass the stopPropagation option for component (#1620)
v8.3.0 on 4/20/2022
0ef8f - fix: update type
v8.0.0 on 3/11/2022
7445f - feat: add stopPropagation option (#1391)
v7.6.0 on 2/8/2022
20df8 - fix(UseDraggable): add prop key[storageType] (#1191)
v7.5.4 on 1/21/2022
48792 - fix: onEnd() runs even if target wasn't dragged directly in exact mode (#1145)
v6.9.0 on 11/14/2021
07d48 - feat: add onEnd hook (#916)
v6.5.0 on 9/25/2021
9f19c - fix: SSR compatibility
v6.4.0 on 9/17/2021
e557f - feat: added 'as' prop to renderable components (#742)
9728a - fix(types): MaybeElementRef type, close #685
9a45b - fix: exports common types
v6.3.3 on 9/12/2021
1196c - fix: ssr support
v6.3.2 on 9/8/2021
4fbe8 - fix: update linter rule, close #729
v6.3.0 on 9/8/2021
a4199 - feat: new function (#727)