Vue Clipboard Package

A powerful Vue 3 package providing a directive, composable, and component for copying text to the clipboard. This package offers flexible solutions with modern clipboard APIs and fallback mechanisms for legacy browsers.

Features

• Directive: Simple, flexible directive for clipboard functionality.
• Composable: Programmatic access to clipboard operations via a composable function.
• Component: A complete, customizable button component with feedback for successful or failed clipboard actions.

Demo

Installation

Install the package via npm or yarn:

npm install vue-clipboard-package

or

yarn add vue-clipboard-package

Usage

1. Using the ClipboardButton Component

The ClipboardButton is a customizable button component with built-in clipboard functionality and feedback (success/error).

Example

<template>
  <ClipboardButton
    :value="textToCopy"
    :disabled="isDisabled"
    copy-label="Copy Text"
    success-label="Copied!"
    error-label="Error Copying"
    tooltip-placement="top"
    feedback-duration="1500"
    legacy="true"
  >
    <template #copy-icon>
      <IconCopy /> <!-- Custom copy icon slot -->
    </template>
    <template #success-icon>
      <IconChecked /> <!-- Custom success icon slot -->
    </template>
    <template #error-icon>
      <IconError /> <!-- Custom error icon slot -->
    </template>
  </ClipboardButton>
</template>

<script setup>
import { ref } from 'vue';
import { ClipboardButton } from 'vue-clipboard-package';

const textToCopy = ref('Hello World');
const isDisabled = ref(false);
</script>

Props

• value (string, required): The text to copy to the clipboard.
• disabled (boolean, default: false): Disables the clipboard action and UI.
• copyLabel (string, default: 'Copy'): Tooltip or label text before copying.
• successLabel (string, default: 'Copied'): Tooltip or label text after successful copy.
• errorLabel (string, default: 'Error'): Tooltip or label text after a failed copy.
• tooltipPlacement (string, default: 'top'): Position of the tooltip (top, bottom, left, right).
• feedbackDuration (number, default: 1000): Duration (ms) to show success or error message.
• legacy (boolean, default: true): Enables the legacy fallback for older browsers.

Slots

• #copy-icon: Slot to customize the copy icon.
• #success-icon: Slot to customize the success icon.
• #error-icon: Slot to customize the error icon.

2. Using the vClipboard Directive

The vClipboard directive provides an easy way to add clipboard functionality to any element.

Example

<template>
  <button v-clipboard="textToCopy">Copy Text</button>
</template>

<script setup>
import { ref } from 'vue';
import { vClipboard } from 'vue-clipboard-package';

const textToCopy = ref('This text will be copied');
</script>

Usage with Event Modifiers You can customize the event type (e.g., click, dblclick) and pass optional arguments like duration and legacy support via the arg.

<template>
  <button v-clipboard:click="{ value: textToCopy, duration: 2000, legacy: true }">Copy on Click</button>
</template>

Modifiers

• duration (optional): Duration for which the feedback (success/error) will be shown.
• legacy (optional): Enables or disables legacy clipboard fallback.
• event (optional): Specify the event type to trigger clipboard copy (e.g., click, dblclick).

3. Using the useCopyToClipboard Composable

The useCopyToClipboard composable provides programmatic access to clipboard operations, with feedback on success or failure. Example

<template>
  <div>
    <button @click="handleCopy">Copy to Clipboard</button>
    <p v-if="copied">Copied to clipboard!</p>
    <p v-if="isError">Failed to copy.</p>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { useCopyToClipboard } from 'vue-clipboard-package';

const { copy, copied, isError } = useCopyToClipboard({ duration: 1500, legacy: true });

const handleCopy = () => {
  copy('Text to be copied');
};
</script>

Return Values

• copied (ref, boolean): true when the text has been successfully copied, false otherwise.
• isError (ref, boolean): true when there was an error copying text, false otherwise.
• copy (function): Function to copy the provided text to the clipboard. Options
• duration (number, default: 1000): Duration (ms) for how long the copied or error state will be active.
• legacy (boolean, default: true): Whether to use a legacy fallback for older browsers that do not support the clipboard API.

API Reference

Props (for ClipboardButton)

| Prop | Type | Default | Description | |------------------|---------|--------------|-------------------------------------------------------------| | value | String | N/A | The text to copy to the clipboard. (Required) | | disabled | Boolean | false | Disables the clipboard action and UI. | | copyLabel | String | 'Copy' | Tooltip or label text before copying. | | successLabel | String | 'Copied' | Tooltip or label text after successful copy. | | errorLabel | String | 'Error' | Tooltip or label text after a failed copy. | | tooltipPlacement | String | 'top' | Position of the tooltip relative to the button. | | feedbackDuration | Number | 1000 | Duration (in ms) for which feedback (success/error) is shown.| | legacy | Boolean | true | Enables legacy support for older browsers. |

Slots (for ClipboardButton)

| Slot Name | Description | |-----------------|------------------------------------------| | copy-icon | Slot for the custom icon before copying. | | success-icon | Slot for the custom icon after copying. | | error-icon | Slot for the custom icon on error. |

Emits (for ClipboardButton)

| Event | Payload | Description | |---------|------------------|-----------------------------------------| | copied | N/A | Emitted when the text is successfully copied. | | error | Error object | Emitted when there is an error during copying. |

Directive Modifiers (for vClipboard)

| Modifier | Type | Default | Description | |---------------|---------|---------------|-----------------------------------------------------------------------------| | event | String | 'click' | Specifies the event type that triggers the copy action (e.g., click, dblclick). | | duration | Number | 1000 | The duration (in milliseconds) for showing feedback after copying. | | legacy | Boolean | true | Enables legacy clipboard support for older browsers using execCommand. |

Composable Options (for useCopyToClipboard)

| Option | Type | Default | Description | |--------------|---------|----------|------------------------------------------------------------------------------| | duration | Number | 1000 | The duration (in milliseconds) for showing feedback after copying. | | legacy | Boolean | true | Enables legacy clipboard support for older browsers using execCommand. |

Installation and Setup

Register Globally (Optional)

If you want to use the package globally in your Vue application, you can register it in your main.ts or main.js file:

import { createApp } from 'vue';
import App from './App.vue';
import ClipboardPlugin from 'vue-clipboard-package';

const app = createApp(App);
app.use(ClipboardPlugin);
app.mount('#app');

License

This package is licensed under the MIT License.