Skip to content
On this page

useClipboard

Category
Export Size
1.41 kB
Last Changed
last month

Reactive 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. Without user permission, reading or altering the clipboard contents is not permitted.

Learn how to reactively save text to the clipboard with this FREE video lesson from Vue School!

Demo

Your browser does not support Clipboard API

Usage

js
import { useClipboard } from '@vueuse/core'

const source = ref('Hello')
const { text, copy, copied, isSupported } = useClipboard({ source })
import { useClipboard } from '@vueuse/core'

const source = ref('Hello')
const { text, copy, copied, isSupported } = useClipboard({ source })
html
<button @click='copy()'>
  <!-- by default, `copied` will be reset in 1.5s -->
  <span v-if='!copied'>Copy</span>
  <span v-else>Copied!</span>
</button>
<button @click='copy()'>
  <!-- by default, `copied` will be reset in 1.5s -->
  <span v-if='!copied'>Copy</span>
  <span v-else>Copied!</span>
</button>

Set legacy: true to keep the ability to copy if Clipboard API is not available. It will handle copy with execCommand as fallback.

Type Declarations

Show Type Declarations
typescript
export interface UseClipboardOptions<Source> extends ConfigurableNavigator {
  /**
   * Enabled reading for clipboard
   *
   * @default false
   */
  read?: boolean
  /**
   * Copy source
   */
  source?: Source
  /**
   * Milliseconds to reset state of `copied` ref
   *
   * @default 1500
   */
  copiedDuring?: number
  /**
   * Whether fallback to document.execCommand('copy') if clipboard is undefined.
   *
   * @default false
   */
  legacy?: boolean
}
export interface UseClipboardReturn<Optional> {
  isSupported: Ref<boolean>
  text: ComputedRef<string>
  copied: ComputedRef<boolean>
  copy: Optional extends true
    ? (text?: string) => Promise<void>
    : (text: string) => Promise<void>
}
/**
 * Reactive Clipboard API.
 *
 * @see https://vueuse.org/useClipboard
 * @param options
 */
export declare function useClipboard(
  options?: UseClipboardOptions<undefined>
): UseClipboardReturn<false>
export declare function useClipboard(
  options: UseClipboardOptions<MaybeComputedRef<string>>
): UseClipboardReturn<true>
export interface UseClipboardOptions<Source> extends ConfigurableNavigator {
  /**
   * Enabled reading for clipboard
   *
   * @default false
   */
  read?: boolean
  /**
   * Copy source
   */
  source?: Source
  /**
   * Milliseconds to reset state of `copied` ref
   *
   * @default 1500
   */
  copiedDuring?: number
  /**
   * Whether fallback to document.execCommand('copy') if clipboard is undefined.
   *
   * @default false
   */
  legacy?: boolean
}
export interface UseClipboardReturn<Optional> {
  isSupported: Ref<boolean>
  text: ComputedRef<string>
  copied: ComputedRef<boolean>
  copy: Optional extends true
    ? (text?: string) => Promise<void>
    : (text: string) => Promise<void>
}
/**
 * Reactive Clipboard API.
 *
 * @see https://vueuse.org/useClipboard
 * @param options
 */
export declare function useClipboard(
  options?: UseClipboardOptions<undefined>
): UseClipboardReturn<false>
export declare function useClipboard(
  options: UseClipboardOptions<MaybeComputedRef<string>>
): UseClipboardReturn<true>

Source

SourceDemoDocs

Contributors

Anthony Fu
Jelf
Sanxiaozhizi
Lumdzeehol
Lumdzeehol
Curt Grimes
wheat
洪布斯
karma
Shinigami
Alex Kozack
Antério Vieira

Changelog

v9.4.0 on 10/25/2022
5ec65 - feat: support legacy copy (#2336)
v8.9.3 on 7/14/2022
16856 - fix!: rename type ClipboardOptions to UseClipboardOptions and ClipboardReturn to UseClipboardReturn (#1861)
v8.9.2 on 7/12/2022
81d92 - fix(all)!: isSupported becomes Ref instead of boolean for SSR compatibility (#1800)
v8.9.1 on 7/8/2022
a9ccc - feat(all): use MaybeComputedRef (#1768)
v7.0.0 on 11/20/2021
77a87 - fix!: disable read by default (#941)

Released under the MIT License.