# CopyButton

An icon `Button` that copies `value` to the clipboard and confirms with a short "Copied" toast beside it. Takes every `Button` prop but `children`.

## Use for

- copying an id, key, secret or URL to the clipboard
- a copy icon next to a value

## Practices

- Do: Pass localized `label` and `copiedLabel`.
- Do: Pass `onCopyError` to tell the user when the clipboard is blocked. Nothing shows otherwise.
- Don't: Call `preventDefault` in `onClick` unless you mean to skip the copy.

## API reference

### CopyButton

A `type="button"` icon button. The toast carries `cl-copy-button-toast` and its title `cl-copy-button-toast-title`.

Slot: `cl-button`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The text to copy. |
| `label` | `string` | `'Copy'` | Accessible name of the button. |
| `copiedLabel` | `string` | `'Copied'` | The toast text after a copy. |
| `side` | `ToastSide` | `'top'` | Side of the button the toast shows on. |
| `resetAfter` | `number` | `2000` | How long the toast stays, in ms. |
| `onCopy` | `(value: string) => void \| Promise<void>` |  | Replaces the clipboard write. Reject to show no toast. |
| `onCopyError` | `(error: unknown) => void` |  | Called when the copy fails. |
| `color` | `'primary' \| 'neutral' \| 'negative'` | `'neutral'` | The `Button` color. |
| `variant` | `'filled' \| 'outline' \| 'ghost' \| 'link'` | `'ghost'` | The `Button` variant. |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'xs'` | The `Button` size. |
| `shape` | `'default' \| 'square' \| 'circle'` | `'square'` | The `Button` shape. |

## Examples

### Copy an id

```tsx
<CopyButton value={user.id} label={m.copyId} copiedLabel={m.copied} />
```

## Related

- [Button](/docs/components/button.md)
