# useClipboard

Copy text with success feedback, errors, and a reset timer.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).





Copying is an asynchronous action, not an immediate guarantee. A browser can reject a clipboard write, and a button that always says “Copied” can report success even when nothing was copied.

useClipboard combines the write with its feedback state: `copy` performs the request, `copied` becomes true after success, and `error` explains a failure. A reset timer returns the control to its normal label so it is ready for the next copy.

## Feedback belongs to the result [#feedback-belongs-to-the-result]

Use it for a copyable input, an install command, or a code block. Start the write from a user action and display success only from the returned state. This hook writes text; it does not read the clipboard or handle image copying.

Repeated copies restart the success interval. A late result from an older request cannot overwrite a newer request's feedback. Browser security requirements still apply, so failure should remain visible rather than being silently treated as success.

Edit the text below, copy it, and watch the feedback reset. The Docs' code-copy controls share this implementation through the existing compatibility hook.

## Preview [#preview]

<DocsPreview code="<ComponentSource src=&#x22;examples/hooks/clipboard.tsx&#x22; />">
  <ClipboardDemo />
</DocsPreview>

## Installation [#installation]

The starter includes `hooks/use-clipboard.ts`. Import the hook directly; no application-wide provider is required.

## Usage [#usage]

```tsx
import { useClipboard } from "@/hooks/use-clipboard";

const { copy, copied, error } = useClipboard({ timeout: 2000 });
<Button onClick={() => void copy("Hello")}>
  {copied ? "Copied" : "Copy"}
</Button>;
```

## API Reference [#api-reference]

| API          | Type               | Behavior / default                         |
| ------------ | ------------------ | ------------------------------------------ |
| `timeout`    | `number`           | `2000ms; 0 keeps the success state`        |
| `copy(text)` | `Promise<boolean>` | `true after the browser accepts the write` |
| `copied`     | `boolean`          | `Current success state`                    |
| `error`      | `Error or null`    | `Last copy failure`                        |

## Behavior [#behavior]

The editable input above is an InputCopy-style example. The Code tabs and the Docs' existing CopyButton use the same implementation through useCopyToClipboard. Clipboard writes require a secure context such as HTTPS or localhost and browser permission. A newer request supersedes stale async results. Timers are reset on repeated copies and cleared on unmount.

## Implementation [#implementation]

<ComponentSource src="hooks/use-clipboard.ts" />