useClipboardItems

Category

Browser

Export Size

662 B

Last Changed

5 days ago

Related

useClipboard

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

Difference from useClipboard

useClipboard is a "text-only" function, while useClipboardItems is a ClipboardItem based function. You can use useClipboardItems to copy any content supported by ClipboardItem.

Usage

import { useClipboardItems } from '@reause/core'

const source = [
  new ClipboardItem({
    'text/plain': new Blob(['plain text'], { type: 'text/plain' }),
  }),
]

const [content, copy, { copied, isSupported }] = useClipboardItems({ source })

// by default, `copied` will be reset to `false` in 1.5s
// (configure it with the `copiedDuring` option, in milliseconds)
copy(source)

Return Values

• content — the clipboard items currently read from the system clipboard (plain state; updated by a successful copy, by controls.read() and, when read: true, by copy/cut events).
• copy(content?) — write ClipboardItems to the clipboard; may be called without arguments to copy the source option.
• controls.copied — whether the last copy call succeeded, auto-resets to false after copiedDuring milliseconds.
• controls.isSupported — whether the resolved navigator exposes the Clipboard API.
• controls.read() — manually read the current clipboard content into content.

The controls object ({ copied, isSupported, read }) keeps a stable identity while its members are unchanged.

Type Declarations

export interface UseClipboardItemsOptions<Source> {
    read?: boolean;
    source?: Source;
    copiedDuring?: number;
    navigator?: Navigator;
}

export type UseClipboardItemsReturn<Optional> = readonly [
    content: ClipboardItems,
    copy: Optional extends true ? (content?: ClipboardItems) => Promise<void> : (content: ClipboardItems) => Promise<void>,
    controls: {
        copied: boolean;
        isSupported: boolean;
        read: () => void;
    }
]

export function useClipboardItems(options?: UseClipboardItemsOptions<undefined>): UseClipboardItemsReturn<false>

export function useClipboardItems(options: UseClipboardItemsOptions<ClipboardItems>): UseClipboardItemsReturn<true>

Source

Source · Demo · VueUse

Contributors

Changelog

v0.1.7 on

9e07f - refactor(core)!: return a tuple from the clipboard hooks

v0.1.0 on

ceca0 - fix(core): resolve useClipboardItems audit findings (#531)

0a7e5 - feat(core): add useClipboardItems (#93)