1---
2category: Browser
3---
4 
5# useClipboard
6 
7Reactive [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API). Provides the ability to respond to clipboard commands (cut, copy, and paste) as well as to asynchronously read from and write to the system clipboard. Access to the contents of the clipboard is gated behind the [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API). Without user permission, reading or altering the clipboard contents is not permitted.
8 
9<CourseLink href="https://vueschool.io/lessons/reactive-browser-wrappers-in-vueuse-useclipboard?friend=vueuse">Learn how to reactively save text to the clipboard with this FREE video lesson from Vue School!</CourseLink>
10 
11## Usage
12 
13```vue
14<script setup lang="ts">
15import { useClipboard } from '@vueuse/core'
16 
17const source = ref('Hello')
18const { text, copy, copied, isSupported } = useClipboard({ source })
19</script>
20 
21<template>
22  <div v-if="isSupported">
23    <button @click="copy(source)">
24      <!-- by default, `copied` will be reset in 1.5s -->
25      <span v-if="!copied">Copy</span>
26      <span v-else>Copied!</span>
27    </button>
28    <p>Current copied: <code>{{ text || 'none' }}</code></p>
29  </div>
30  <p v-else>
31    Your browser does not support Clipboard API
32  </p>
33</template>
34```
35 
36### Options
37 
38| Option         | Type                       | Default | Description                                                       |
39| -------------- | -------------------------- | ------- | ----------------------------------------------------------------- |
40| `source`       | `MaybeRefOrGetter<string>` | —       | Default content to copy when `copy()` is called without arguments |
41| `read`         | `boolean`                  | `false` | Enable reading clipboard content on copy/cut events               |
42| `copiedDuring` | `number`                   | `1500`  | Milliseconds before `copied` resets to `false`                    |
43| `legacy`       | `boolean`                  | `false` | Fallback to `document.execCommand` if Clipboard API unavailable   |
44 
45### Return Values
46 
47| Property      | Type                               | Description                                       |
48| ------------- | ---------------------------------- | ------------------------------------------------- |
49| `isSupported` | `ComputedRef<boolean>`             | Whether clipboard is supported (native or legacy) |
50| `text`        | `Ref<string>`                      | Current clipboard content (when `read: true`)     |
51| `copied`      | `Ref<boolean>`                     | `true` after successful copy, auto-resets         |
52| `copy`        | `(text?: string) => Promise<void>` | Copy text to clipboard                            |
53 
54### Legacy Mode
55 
56Set `legacy: true` to keep the ability to copy if [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API) is not available. It will handle copy with [execCommand](https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand) as fallback.
57 
58```ts
59const { copy, isSupported } = useClipboard({ legacy: true })
60```
61 
62## Component Usage
63 
64```vue
65<template>
66  <UseClipboard v-slot="{ copy, copied }" source="copy me">
67    <button @click="copy()">
68      {{ copied ? 'Copied' : 'Copy' }}
69    </button>
70  </UseClipboard>
71</template>
72```
73 
74## Type Declarations
75 
76```ts
77export interface UseClipboardOptions<Source> extends ConfigurableNavigator {
78  /**
79   * Enabled reading for clipboard
80   *
81   * @default false
82   */
83  read?: boolean
84  /**
85   * Copy source
86   */
87  source?: Source
88  /**
89   * Milliseconds to reset state of `copied` ref
90   *
91   * @default 1500
92   */
93  copiedDuring?: number
94  /**
95   * Whether fallback to document.execCommand('copy') if clipboard is undefined.
96   *
97   * @default false
98   */
99  legacy?: boolean
100}
101export interface UseClipboardReturn<Optional> extends Supportable {
102  text: Readonly<ShallowRef<string>>
103  copied: Readonly<ShallowRef<boolean>>
104  copy: Optional extends true
105    ? (text?: string) => Promise<void>
106    : (text: string) => Promise<void>
107}
108/**
109 * Reactive Clipboard API.
110 *
111 * @see https://vueuse.org/useClipboard
112 * @param options
113 *
114 * @__NO_SIDE_EFFECTS__
115 */
116export declare function useClipboard(
117  options?: UseClipboardOptions<undefined>,
118): UseClipboardReturn<false>
119export declare function useClipboard(
120  options: UseClipboardOptions<MaybeRefOrGetter<string>>,
121): UseClipboardReturn<true>
122```
123