Copy to Clipboard

Demo & usage

More examples

<sv-copy-to-clipboard [text]="apiKey" variant="icon-only" size="sm" successLabel="Copied!" (copyError)="onCopyError($event)" />

<sv-copy-to-clipboard variant="block"
  [text]="apiKey" [label]="apiKey"
  [sensitive]="true" sensitiveReveal="revealable" sensitiveField="apiKey"
  [revealAuthorized]="stepUpDone()"
  (revealRequest)="stepUp()"
  (copyAudited)="audit.log($event)" />

onCopyError(err: unknown) {
  if (err instanceof SvClipboardError && err.reason === 'insecure-context') {
    this.toast.show('Copying needs HTTPS — select the text and press Ctrl+C.');
  }
}

providers: [{ provide: SV_CLIPBOARD, useValue: { writeText: () => Promise.reject(new SvClipboardError('denied')) } }]

When to use

• Letting users copy a value (code snippet, API key, URL, token) in one click.
• You want built-in success feedback and a clipboard fallback for old browsers.
• For copying rich/multiple values, build a custom control around the clipboard API.

Async states

None — this component has nothing to load, so it has no loading, empty or error state to drive.

Outputs

Customization & theming

• Pass the `text` to copy and choose a `variant` (inline, block, icon-only) and `size`.
• Customize the `label` and the post-copy `successLabel` / `successDuration`.
• Listen to `copied` for success and `copyError` for failures, to trigger toasts or analytics.
• Sensitive values (`sensitive`, `sensitiveReveal`, `sensitiveField`, `sensitiveWarning`, `requireAuthorization` / `revealAuthorized` / `revealRequest`, `copyAudited`) follow the kit-wide sensitive-value policy, and `provideSvSensitivePrivacy()` re-masks the label while the screen is shared.
• The clipboard sits behind the `SV_CLIPBOARD` injection token (default `svBrowserClipboard`): provide your own to test denied permission or an insecure origin, or to target a native shell.
• Variant axes: `variant` and `size` are appearance; `sensitive` + `sensitiveReveal` are a behavioural mode that works with every variant, except that `icon-only` has no label to mask or reveal, so it only warns and audits.
• Busy state: a click while a copy is in flight is ignored and the button reports `aria-busy="true"`; the success timer is cleared when the component is destroyed, and a copy that settles after destruction emits nothing. A write that never settles is abandoned after `copyTimeout` (default 10 000 ms, `SV_COPY_TIMEOUT_MS`): `copyError` fires with reason `failed`, busy clears, and a late answer is ignored.
• Layout (X-9): not applicable — the button and label sit in normal flow; nothing is portalled, measured or scrolled, and no containing block or breakpoint matters. The execCommand fallback appends an off-screen `position: fixed` textarea to `<body>` for the duration of the copy only, and removes it whether the copy succeeded or not.
• Browser limits: the async Clipboard API needs a secure context (HTTPS or localhost) and a user gesture, and an iframe needs the `clipboard-write` permission policy. Elsewhere the component falls back to the deprecated `execCommand('copy')`, which iOS Safari only honours inside the tap handler and which browsers may remove. When both fail, `copyError` carries `reason` (`denied`, `insecure-context`, `unavailable`, `failed`) and the live region tells the user to select the text and copy it manually.

Best practices

• Do: Confirm the copy visibly (`successLabel`) so users know it worked.
• Do: Give icon-only variants an accessible name with `ariaLabel` that says what is copied ("Copy API key") — `label` is visible text, and may be the value itself.
• Tip: Use the `copied` event to fire a toast or analytics event.
• Do: Set `sensitive` for API keys, recovery codes and tokens: the label masks, the copy warns, and `copyAudited` gives you an audit trail that never contains the secret.
• Don't: Don't project a secret through `<ng-content>` in sensitive mode — projected markup is yours and is not masked. Pass it through `label`.

Accessibility

• Renders a labelled button with an accessible name even in icon-only mode.
• Success and failure are announced via a polite live region, not colour-only; a failure names its reason and the manual workaround.
• Falls back to execCommand when the Clipboard API is unavailable, and emits `copyError` if both fail.
• In sensitive mode the reveal toggle is a real button with `aria-pressed`, and the success announcement is the `sensitiveWarning`.
• Focus stays on the copy button: the fallback's scratch textarea hands focus back after it copies.