useClipboard

Package

Share - Core

Category

Browser

Description

reactive [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API)

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.

Demo

Clipboard Permission: read | write

Current copied: none

Usage

<script setup lang="ts">
import { useClipboard } from '@hungpvq/shared-core';

const source = ref('Hello');
const { text, copy, copied, isSupported } = useClipboard({ source });
</script>

<template>
  <div v-if="isSupported">
    <button @click="copy(source)">
      <!-- by default, `copied` will be reset in 1.5s -->
      <span v-if="!copied">Copy</span>
      <span v-else>Copied!</span>
    </button>
    <p>
      Current copied: <code>{{ text || 'none' }}</code>
    </p>
  </div>
  <p v-else>Your browser does not support Clipboard API</p>
</template>

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

Type

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