# useClipboard

> A React copy-to-clipboard hook with a copied flag that resets itself, and a fallback for pages without the Clipboard API.

- Type: React hook (Hooks & Utilities)
- Access: Free (the source is open to everyone)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add use-clipboard`
- Docs: https://wingo-ui.com/components/use-clipboard

## Interaction

Press Copy next to an IBAN, a tax ID or an invoice link: the icon turns into a check for the timeout and the last copied text shows below. Paste it anywhere to check. Set the timeout to 0 and the check stays until the next copy.

## Installation

```bash
npx wingo-ui@latest add use-clipboard
```

The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add https://wingo-ui.com/r/use-clipboard.json`

Files:

- `hooks/use-clipboard.ts`

## Usage

```tsx
import { Check, Copy } from "lucide-react"
import { useClipboard } from "@/hooks/use-clipboard"

export function CopyIban({ iban }: { iban: string }) {
  const { copy, copied } = useClipboard()
  return (
    <button type="button" onClick={() => copy(iban)} aria-label={copied ? "Copied" : "Copy IBAN"}>
      {copied ? <Check /> : <Copy />}
    </button>
  )
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `timeout?` | `number` | `2000` | How long copied stays true after a copy, in ms. 0 keeps it until reset() or the next copy. |
| `onCopy / onError?` | `(text: string) => void / (error: Error) => void` |  | Called after each copy; the latest callbacks are always used, so there is nothing to memoize. |
| `useClipboard?` | `(options?: { timeout?: number; onCopy?; onError? }) => { copy(source: string \| (() => string \| Promise<string>), options?: { html?: string }): Promise<boolean>; copied: boolean; error: Error \| null; text: string \| null; reset(): void }` |  | copy takes a string or a function read at click time (the latest form value, a link fetched on demand) and resolves true on success. Pass html to put a rich version next to the plain text. |

## Parts

### copyToClipboard (function)

The same copy without state, for event handlers: navigator.clipboard where it exists, a hidden textarea with execCommand on plain http and old webviews. Focus returns to where it was. Signature: (text: string, options?: { html?: string }) => Promise<boolean>.

## Examples

- **Share link**: copy takes a function, read at click time. The button label flips to Copied and a live region announces it.

## See also

- [Code Block](https://wingo-ui.com/components/code-block) ([Markdown](https://wingo-ui.com/components/code-block.md))
- [useShortcut](https://wingo-ui.com/components/use-shortcut) ([Markdown](https://wingo-ui.com/components/use-shortcut.md))

---

Canonical: https://wingo-ui.com/components/use-clipboard
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt