# PasteButton

Icon button that reads the system clipboard and forwards the text to a callback. Defaults to a clipboard glyph; pair with a string-transform helper at the call site (URL extractor, code parser, normaliser).

[View examples](https://marsam.rahhal.app/components/paste-button) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/paste-button`

**Category:** `actions`

## Behavior

- Calls `navigator.clipboard.readText()` on click and forwards the text to `onPaste`.
- Returns silently when the read succeeds. On failure, fires `onError` if provided, otherwise shows `errorMessage` via the global `<Toaster />` (must be mounted at app root).
- Wraps `<Button>` and accepts every `<Button>` prop (`size`, `variant`, `disabled`, `className`, `ref`, …) via spread. Defaults: `size="icon"`, `variant="ghost"`.
- Icon defaults to lucide-react's `<Clipboard>`. Override with `children`.
- The component shadows React's native `onPaste` clipboard event handler — `onPaste` here receives the clipboard string, not a `ClipboardEvent`.

## Props

| prop | type | purpose |
| --- | --- | --- |
| onPaste | (text: string) => void | fires with raw clipboard text on success (required) |
| aria-label | string | screen-reader label (required — icon has no visible text) |
| errorMessage | string | toast text on clipboard-read failure |
| onError | (err: unknown) => void | custom error handler — overrides errorMessage |
| size | Button size | passthrough; defaults to "icon" |
| variant | Button variant | passthrough; defaults to "ghost" |
| children | ReactNode | override default <Clipboard /> glyph |

## Patterns

- **Inside an input** — wrap input + button in `relative`, give the input `pe-11` to reserve room, anchor the button with `absolute end-1 top-1/2 -translate-y-1/2`. Logical `end-*` flips correctly under RTL.
- **Standalone** — pass `size="sm"` with `variant="outline"` and a visible `children` label.
- **Failures are common** on iOS Safari without an explicit user gesture, on insecure (non-HTTPS) origins, and in private-browsing modes. Always pass `errorMessage` (or `onError`) so the user knows to fall back to manual paste.

## Related

- See `<SearchBar>` for the canonical "trailing icon inside an input" composition; `PasteButton` drops into that same slot.