Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wsmd/use-clipboard-copy
📋 Lightweight copy to clipboard hook for React
https://github.com/wsmd/use-clipboard-copy
clipboard clipboard-copy clipboard-js clipboardjs copy-to-clipboard hook react react-hooks reactjs
Last synced: about 6 hours ago
JSON representation
📋 Lightweight copy to clipboard hook for React
- Host: GitHub
- URL: https://github.com/wsmd/use-clipboard-copy
- Owner: wsmd
- License: mit
- Created: 2019-04-04T02:57:48.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-07T04:27:27.000Z (almost 2 years ago)
- Last Synced: 2024-10-30T18:06:03.492Z (14 days ago)
- Topics: clipboard, clipboard-copy, clipboard-js, clipboardjs, copy-to-clipboard, hook, react, react-hooks, reactjs
- Language: TypeScript
- Homepage: https://use-clipboard-copy.now.sh
- Size: 844 KB
- Stars: 387
- Watchers: 3
- Forks: 15
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
use-clipboard-copy
📖 Table of Contents
- [Motivation](#motivation)
- [Getting Started](#getting-started)
- [Usage](#usage)
- [Copying Text of Another Target Element](#copying-text-of-another-target-element)
- [Copying Text Imperatively (Without a Target Element)](#copying-text-imperatively-without-a-target-element)
- [Displaying a Temporary Success State](#displaying-a-temporary-success-state)
- [Handling Success and Errors](#handling-success-and-errors)
- [Browser Support](#browser-support)
- [API](#api)
- [`useClipboard(options?: UseClipboardOptions): ClipboardAPI`](#useclipboardoptions-useclipboardoptions-clipboardapi)
- [`UseClipboardOptions`](#useclipboardoptions)
- [`copiedTimeout?: number`](#copiedtimeout-number)
- [`onSuccess?: () => void`](#onsuccess---void)
- [`onError?: () => void`](#onerror---void)
- [`selectOnCopy?: boolean`](#selectoncopy-boolean)
- [`selectOnError?: boolean`](#selectonerror-boolean)
- [`ClipboardAPI`](#clipboardapi)
- [`copy: (text?: string) => void`](#copy-text-string--void)
- [`target: React.RefObject`](#target-reactrefobjectany)
- [`isSupported: () => boolean`](#issupported---boolean)
- [`copied: boolean`](#copied-boolean)
- [Acknowledgements](#acknowledgements)
- [License](#license)
## Motivation
There are various copy-to-clipboard solutions for Javascript – really good ones, but getting them to work with React can feel a little odd... they don't feel very _React-y_.
`use-clipboard-copy` is a **lightweight** (< 1KB) React hook that makes it possible to add a copy-to-clipboard functionality to your React application with very little code! A simple implementation looks like this:
```js
function CopyText() {
const clipboard = useClipboard();
return (
Copy
);
}
```
P.S. You can do more than that with `use-clipboard-copy`. Keep reading!
## Getting Started
To get started, add `use-clipboard-copy` to your project:
```
npm install --save use-clipboard-copy
```
Please note that `use-clipboard-copy` requires `react@^16.8.0` as a peer dependency.
## Usage
### Copying Text of Another Target Element
A simple copy-to-clipboard interface consists of two parts:
- The `target`, an element who holds the value to be copied, usually an input.
- The `copy` action.
```jsx
import { useClipboard } from 'use-clipboard-copy';
export default function PublicUrl({ url }) {
const clipboard = useClipboard();
return (
Copy Link
);
}
```
### Copying Text Imperatively (Without a Target Element)
It is also possible to perform a copy action imperatively (programmatically). For example, a copy-to-clipboard interface may consist of a single copy button without any additional inputs or values displayed to the user. By passing a string to the `clipboard.copy` action, the specified string will be copied to the clipboard.
```jsx
import { useClipboard } from 'use-clipboard-copy';
export default function PublicUrl({ id }) {
const clipboard = useClipboard();
const handleClick = React.useCallback(
() => {
const url = Utils.formatUrl({ query: { id } });
clipboard.copy(url); // programmatically copying a value
},
[clipboard.copy, id]
);
return (
Copy Link
);
}
```
### Displaying a Temporary Success State
Sometimes it can be helpful to notify the user that the text was successfully copied to the clipboard, usually by displaying a temporary "Copied" state after they trigger the copy action.
By passing the `copiedTimeout` option to `useClipboard()`, you can use `clipboard.copied` as a way to toggle the copied state in the UI.
```jsx
import { useClipboard } from 'use-clipboard-copy';
export default function PublicUrl({ url }) {
const clipboard = useClipboard({
copiedTimeout: 600, // timeout duration in milliseconds
});
return (
{clipboard.copied ? 'Copied' : 'Copy Link'}
);
}
```
### Handling Success and Errors
Copy to clipboard in browsers can be tricky some times - there are various reasons that can contribute to preventing the copy action from working. Therefore, you should always handle such cases.
By passing an `onSuccess` and `onError` callbacks to the `useClipboard` options, you will be able to handle whether the `copy` action was performed successfully.
```js
function CopyText() {
const clipboard = useClipboard({
onSuccess() {
console.log('Text was copied successfully!')
},
onError() {
console.log('Failed to copy text!')
}
});
return (
Copy
);
}
```
In case the `copy` action fails, `useClipboard` will handle that gracefully by selecting the `target` input instead so that users can copy the text manually. This behavior can be disabled by passing `selectOnError: false` to the clipboard options.
## Browser Support
`use-clipboard-copy` is supported in all browsers that [supports the native clipboard APIs](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard), including major browsers such as **Chrome, Firefox, Edge, Safari, IE11**.
This hook provides an `isSupported` method that you can use to check for browser support and update the UI accordingly:
```jsx
function ClipboardSupport() {
const clipboard = useClipboard();
return (
{clipboard.isSupported()
? "yay! copy-to-clipboard is supported"
: "meh. copy-to-clipboard is not supported"}
);
}
```
## API
### `useClipboard(options?: UseClipboardOptions): ClipboardAPI`
`use-clipboard-copy` exposes a named export `useClipboard` which is the hook function itself. It takes an optional options object, and returns an object to control the clipboard.
```js
import { useClipboard } from 'use-clipboard-copy';
function CopyText() {
const clipboard = useClipboard();
return (
// ...
);
}
```
### `UseClipboardOptions`
`useClipboard` takes an optional object with the following properties:
- [`copiedTimeout?: number`](#copiedtimeout-number)
- [`onSuccess?: () => void`](#onsuccess---void)
- [`onError?: () => void`](#onerror---void)
- [`selectOnCopy?: boolean`](#selectoncopy-boolean)
- [`selectOnError?: boolean`](#selectonerror-boolean)
#### `copiedTimeout?: number`
The duration in milliseconds used to toggled the [`copied`](#copied-boolean) state upon a successful copy action.
#### `onSuccess?: () => void`
A callback function that will be called upon a successful copy action.
#### `onError?: () => void`
A callback function that will be called when the copy action fails.
#### `selectOnCopy?: boolean`
Defaults to `false`.
A boolean indicating whether the text of the [`target`](#target-reactrefobjectany) element (if set) will be selected upon a successful copy action.
#### `selectOnError?: boolean`
Defaults to `true`.
A boolean indicating whether the text of the [`target`](#target-reactrefobjectany) element (if set) will be selected when the copy action fails.
### `ClipboardAPI`
`useClipboard` returns an object with the following properties:
- [`copied: boolean`](#copied-boolean)
- [`copy: (text?: string) => void`](#copy-text-string--void)
- [`isSupported: () => boolean`](#issupported---boolean)
- [`target: React.RefObject`](#target-reactrefobjectany)
#### `copy: (text?: string) => void`
A method that will be used to preform the copy action. If it's used without passing a string, the `copy` action will use the text of the [`target`](#target-reactrefobjectany) element (if set).
```jsx
;
;
```
Optionally, `copy` takes a `string` to perform the copy action imperatively (programmatically). When this is used, the [`target`](#target-reactrefobjectany) element (if set) will be ignored.
```jsx
clipboard.copy('a text to copy')} />;
```
#### `target: React.RefObject`
A React Ref object used on input and textarea elements that holds the text to be copied.
```jsx
;
```
#### `isSupported: () => boolean`
A function that returns a boolean indicating whether the browser supports the clipboard APIs. Useful to deterministically update the UI if the browser does not support the clipboard functionality for whatever reason.
#### `copied: boolean`
A boolean indicating whether the copy action was just performed. Must be used with the [`copiedTimeout`](#copiedtimeout-number) option. Useful to update the UI to display temporary success state.
## Acknowledgements
This hook is powered by [clipboard-copy](https://github.com/feross/clipboard-copy), the lightweight copy to clipboard for the web.
## License
MIT