use-clipboard

Permission-aware clipboard access with a legacy copy fallback.

Usage

import { useClipboard } from "@vizejs/composable/use-clipboard";

Runtime contract

API

useClipboard

Permission-aware clipboard access with a legacy copy fallback. Text and rich items go through the async Clipboard API. When it is missing (insecure contexts, older engines) or refuses a write, copy falls back to document.execCommand("copy") unless legacy is false. Every action resolves to a discriminated ClipboardResult ("success", "permission-denied", "unsupported", "failed") instead of rejecting, and the read/write permission states are exposed reactively. Server rendering: nothing is read and no permission is queried; text is empty and supported is false. The copied reset timer and the optional copy/cut listeners are released when the owning scope stops. Inside a component the host is read after mounting, so hydration renders the server fallback first and never mismatches.

function useClipboard(options: UseClipboardOptions = {}): ClipboardControls

const { copy, copied } = useClipboard();
await copy("npm i

## Types

### `ClipboardItemLike`

One clipboard entry, compatible with the DOM `ClipboardItem`.

| Member | Type | Description |
| --- | --- | --- |
| `types` | `readonly string[]` | MIME types available in this item. |
| `getType` | `(type: string) => Promise<Blob>` | Read the item's data for one of its `types`. |

### `ClipboardLike`

Minimal async Clipboard API consumed by `useClipboard`.

| Member | Type | Description |
| --- | --- | --- |
| `readText` | `() => Promise<string>` | Read plain text. |
| `writeText` | `(text: string) => Promise<void>` | Write plain text. |
| `read`? | `() => Promise<readonly ClipboardItemLike[]>` | Read rich items. Absent in older browsers. |
| `write`? | `(items: readonly ClipboardItemLike[]) => Promise<void>` | Write rich items. Absent in older browsers. |

### `ClipboardHost`

Capabilities used by `useClipboard`; every member is optional.

| Member | Type | Description |
| --- | --- | --- |
| `clipboard`? | `ClipboardLike \| null` | Async Clipboard API (`navigator.clipboard`). |
| `permissions`? | `PermissionsHost \| null` | Permissions API used to report read/write permission state. |
| `legacyCopy`? | `((text: string) => boolean) \| null` | Synchronous legacy copy used when the async API is missing or refuses. Returns whether the copy succeeded. |
| `events`? | `EventTarget \| null` | Target of `copy`/`cut` events observed when `listen` is enabled. |

### `ClipboardSuccess`

Successful clipboard operation.

| Member | Type | Description |
| --- | --- | --- |
| `status` | `"success"` | The operation succeeded. |
| `value` | `Value` | Value that was read or written. |
| `method` | `"clipboard" \| "legacy"` | Mechanism that performed the operation. |

### `ClipboardFailure`

Failed clipboard operation.

| Member | Type | Description |
| --- | --- | --- |
| `status` | `ClipboardFailureReason` | Why the operation failed. |
| `error` | `unknown` | Exact error thrown by the host, when one was thrown. |

### `UseClipboardOptions`

Options for `useClipboard`.

| Member | Type | Description |
| --- | --- | --- |
| `host`? | `MaybeRefOrGetter<ClipboardHost \| null \| undefined>` | Clipboard capabilities for alternate runtimes and tests. |
| `legacy`? | `boolean` | Fall back to `document.execCommand("copy")` when the async API is unavailable or rejects a write. |
| `copiedDuringMs`? | `number` | Milliseconds for which `copied` stays `true` after a successful write. |
| `scheduler`? | `TimeoutScheduler` | Timer host used to reset `copied`. |
| `listen`? | `boolean` | Update `text` by reading the clipboard after every `copy`/`cut` event. |
| `queryPermissions`? | `boolean` | Query the `clipboard-read` / `clipboard-write` permissions. |

### `ClipboardControls`

Reactive state and actions returned by `useClipboard`.

| Member | Type | Description |
| --- | --- | --- |
| `supported` | `ComputedRef<boolean>` | Whether the async Clipboard API or the legacy fallback is available. |
| `text` | `Readonly<Ref<string>>` | Text most recently copied or read. |
| `copied` | `Readonly<Ref<boolean>>` | `true` for `copiedDuringMs` after a successful copy. |
| `error` | `Readonly<ShallowRef<ClipboardFailure \| undefined>>` | Most recent failure, cleared by the next success. |
| `readPermission` | `Readonly<Ref<PermissionQueryState>>` | State of the `clipboard-read` permission. |
| `writePermission` | `Readonly<Ref<PermissionQueryState>>` | State of the `clipboard-write` permission. |
| `copy` | `(text: string) => Promise<ClipboardResult<string>>` | Copy text, falling back to the legacy mechanism when allowed. |
| `readText` | `() => Promise<ClipboardResult<string>>` | Read plain text. |
| `writeItems` | `( items: readonly ClipboardItemLike[], ) => Promise<ClipboardResult<readonly ClipboardItemLike[]>>` | Write rich clipboard items. |
| `readItems` | `() => Promise<ClipboardResult<readonly ClipboardItemLike[]>>` | Read rich clipboard items. |