1---
2category: Elements
3---
4 
5# useDraggable
6 
7Make elements draggable.
8 
9## Usage
10 
11```vue
12<script setup lang="ts">
13import { useDraggable } from '@vueuse/core'
14import { useTemplateRef } from 'vue'
15 
16const el = useTemplateRef('el')
17 
18// `style` will be a helper computed for `left: ?px; top: ?px;`
19const { x, y, style } = useDraggable(el, {
20  initialValue: { x: 40, y: 40 },
21})
22</script>
23 
24<template>
25  <div ref="el" :style="style" style="position: fixed">
26    Drag me! I am at {{ x }}, {{ y }}
27  </div>
28</template>
29```
30 
31### Return Values
32 
33| Property     | Type                   | Description                             |
34| ------------ | ---------------------- | --------------------------------------- |
35| `x`          | `Ref<number>`          | Current x position                      |
36| `y`          | `Ref<number>`          | Current y position                      |
37| `position`   | `Ref<{x, y}>`          | Current position object                 |
38| `isDragging` | `ComputedRef<boolean>` | Whether currently dragging              |
39| `style`      | `ComputedRef<string>`  | CSS style string `left: ?px; top: ?px;` |
40 
41### Options
42 
43```ts
44useDraggable(el, {
45  // Initial position (default: { x: 0, y: 0 })
46  initialValue: { x: 40, y: 40 },
47  // Restrict dragging to specific axis: 'x', 'y', or 'both' (default)
48  axis: 'both',
49  // Only trigger when clicking directly on the element (default: false)
50  exact: false,
51  // Prevent default browser behavior (default: false)
52  preventDefault: true,
53  // Stop event propagation (default: false)
54  stopPropagation: false,
55  // Use capture phase for events (default: true)
56  capture: true,
57  // Disable dragging (default: false)
58  disabled: false,
59  // Mouse buttons that trigger drag (default: [0] - left button)
60  buttons: [0],
61  // Pointer types to listen to (default: ['mouse', 'touch', 'pen'])
62  pointerTypes: ['mouse', 'touch', 'pen'],
63  // Custom drag handle element (default: target element)
64  handle: handleRef,
65  // Container element for bounds (default: none)
66  containerElement: containerRef,
67  // Element to attach pointermove/pointerup events (default: window)
68  draggingElement: window,
69  // Callbacks
70  onStart: (position, event) => {
71    // Return false to prevent dragging
72  },
73  onMove: (position, event) => {},
74  onEnd: (position, event) => {},
75})
76```
77 
78### Prevent Default
79 
80Set `preventDefault: true` to override the default drag-and-drop behavior of certain elements in the browser (e.g., images).
81 
82```ts
83import { useDraggable } from '@vueuse/core'
84 
85const { x, y, style } = useDraggable(el, {
86  preventDefault: true,
87})
88```
89 
90### Container Bounds
91 
92Use `containerElement` to constrain dragging within a container.
93 
94```ts
95import { useDraggable } from '@vueuse/core'
96 
97const { x, y } = useDraggable(el, {
98  containerElement: containerRef,
99})
100```
101 
102Set `autoScroll: true` to enable auto-scroll when dragging near the edges.
103 
104```ts
105const { x, y, style } = useDraggable(el, {
106  autoScroll: {
107    speed: 2, // Control the speed of auto-scroll.
108    margin: 30, // Set the margin from the edge that triggers auto-scroll.
109    direction: 'both' // Determine the direction of auto-scroll.
110  },
111})
112```
113 
114## Component Usage
115 
116```vue
117<template>
118  <UseDraggable v-slot="{ x, y }" :initial-value="{ x: 10, y: 10 }">
119    Drag me! I am at {{ x }}, {{ y }}
120  </UseDraggable>
121</template>
122```
123 
124For component usage, additional props `storageKey` and `storageType` can be passed to the component and enable the persistence of the element position.
125 
126```vue
127<template>
128  <UseDraggable storage-key="vueuse-draggable" storage-type="session">
129    Refresh the page and I am still in the same position!
130  </UseDraggable>
131</template>
132```
133 
134## Type Declarations
135 
136```ts
137export interface UseDraggableOptions {
138  /**
139   * Only start the dragging when click on the element directly
140   *
141   * @default false
142   */
143  exact?: MaybeRefOrGetter<boolean>
144  /**
145   * Prevent events defaults
146   *
147   * @default false
148   */
149  preventDefault?: MaybeRefOrGetter<boolean>
150  /**
151   * Prevent events propagation
152   *
153   * @default false
154   */
155  stopPropagation?: MaybeRefOrGetter<boolean>
156  /**
157   * Whether dispatch events in capturing phase
158   *
159   * @default true
160   */
161  capture?: boolean
162  /**
163   * Element to attach `pointermove` and `pointerup` events to.
164   *
165   * @default window
166   */
167  draggingElement?: MaybeRefOrGetter<
168    HTMLElement | SVGElement | Window | Document | null | undefined
169  >
170  /**
171   * Element for calculating bounds (If not set, it will use the event's target).
172   *
173   * @default undefined
174   */
175  containerElement?: MaybeRefOrGetter<
176    HTMLElement | SVGElement | null | undefined
177  >
178  /**
179   * Handle that triggers the drag event
180   *
181   * @default target
182   */
183  handle?: MaybeRefOrGetter<HTMLElement | SVGElement | null | undefined>
184  /**
185   * Pointer types that listen to.
186   *
187   * @default ['mouse', 'touch', 'pen']
188   */
189  pointerTypes?: PointerType[]
190  /**
191   * Initial position of the element.
192   *
193   * @default { x: 0, y: 0 }
194   */
195  initialValue?: MaybeRefOrGetter<Position>
196  /**
197   * Callback when the dragging starts. Return `false` to prevent dragging.
198   */
199  onStart?: (position: Position, event: PointerEvent) => void | false
200  /**
201   * Callback during dragging.
202   */
203  onMove?: (position: Position, event: PointerEvent) => void
204  /**
205   * Callback when dragging end.
206   */
207  onEnd?: (position: Position, event: PointerEvent) => void
208  /**
209   * Axis to drag on.
210   *
211   * @default 'both'
212   */
213  axis?: "x" | "y" | "both"
214  /**
215   * Disabled drag and drop.
216   *
217   * @default false
218   */
219  disabled?: MaybeRefOrGetter<boolean>
220  /**
221   * Mouse buttons that are allowed to trigger drag events.
222   *
223   * - `0`: Main button, usually the left button or the un-initialized state
224   * - `1`: Auxiliary button, usually the wheel button or the middle button (if present)
225   * - `2`: Secondary button, usually the right button
226   * - `3`: Fourth button, typically the Browser Back button
227   * - `4`: Fifth button, typically the Browser Forward button
228   *
229   * @see https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button#value
230   * @default [0]
231   */
232  buttons?: MaybeRefOrGetter<number[]>
233  /**
234   * Whether to restrict dragging within the visible area of the container.
235   *
236   * If enabled, the draggable element will not leave the visible area of its container,
237   * ensuring it remains within the viewport of the container during the drag.
238   *
239   * @default false
240   */
241  restrictInView?: MaybeRefOrGetter<boolean>
242  /**
243   * Whether to enable auto-scroll when dragging near the edges.
244   *
245   * @default false
246   */
247  autoScroll?: MaybeRefOrGetter<
248    | boolean
249    | {
250        /**
251         * Speed of auto-scroll.
252         *
253         * @default 2
254         */
255        speed?: MaybeRefOrGetter<number | Position>
256        /**
257         * Margin from the edge to trigger auto-scroll.
258         *
259         * @default 30
260         */
261        margin?: MaybeRefOrGetter<number | Position>
262        /**
263         * Direction of auto-scroll.
264         *
265         * @default 'both'
266         */
267        direction?: "x" | "y" | "both"
268      }
269  >
270}
271export interface UseDraggableReturn {
272  x: Ref<number>
273  y: Ref<number>
274  position: Ref<Position>
275  isDragging: ComputedRef<boolean>
276  style: ComputedRef<string>
277}
278/**
279 * Make elements draggable.
280 *
281 * @see https://vueuse.org/useDraggable
282 * @param target
283 * @param options
284 */
285export declare function useDraggable(
286  target: MaybeRefOrGetter<HTMLElement | SVGElement | null | undefined>,
287  options?: UseDraggableOptions,
288): UseDraggableReturn
289```
290