CopyButton

Usage examples

import { useState } from 'react';
import { CopyButton } from '@rookcom/monarch-react';

function WithErrorReport() {
  const [problem, setProblem] = useState<string | null>(null);
  return (
    <div style={{ display: 'grid', gap: 'var(--mn-space-2)', justifyItems: 'start' }}>
      <CopyButton
        value="https://example.com/invite/7f3a"
        label="Copy invite link"
        copiedLabel="Link copied"
        onCopy={() => setProblem(null)}
        onCopyError={(error) => setProblem(error.message)}
      />
      {problem ? (
        <p style={{ margin: 0, fontSize: 'var(--mn-text-xs)' }}>
          Copy failed ({problem}). Select the link and copy it manually.
        </p>
      ) : null}
    </div>
  );
}

<WithErrorReport />

import { useCopyToClipboard, Button } from '@rookcom/monarch-react';

function HookDemo() {
  const { copy, status } = useCopyToClipboard();
  return (
    <Button size="sm" onClick={() => void copy('ORDER-2024-0193')}>
      {status === 'copied' ? 'Reference copied' : 'Copy reference'}
    </Button>
  );
}

<HookDemo />

Purpose

One button that copies a value (a link, a key, a DNS record), shows a short "Copied" state, announces the result in a polite live region and hands errors to the caller. useCopyToClipboard is the same logic for custom controls.

Design principles

• Feedback is visible and spoken: the icon becomes a check and the label "Copied", and a polite live region says "Copied to clipboard".
• Never fails silently. The Clipboard API is tried first, then the legacy execCommand path; if both fail the button shows "Couldn't copy", announces it, and calls onCopyError.
• The button keeps its width: all three labels share one grid cell, so nothing jumps when the state changes.
• Built on Button, so variants, sizes, focus and disabled behaviour are the same as every other action.

API reference

import { CopyButton, useCopyToClipboard, writeToClipboard } from '@rookcom/monarch-react';

CopyButton forwards its ref to the <button>. It renders a visually hidden role="status" sibling for announcements.

useCopyToClipboard({ resetAfter, onCopy, onError }) returns { copy, status, error, reset }. copy(value) resolves true or false and never rejects.

writeToClipboard(text) is the low-level write (Clipboard API, then the legacy fallback); it rejects with an Error when both fail.

Generated from the TypeScript declarations of packages/react/src/components/actions/copy-button.

Properties

All Button props except children, asChild and leadingIcon pass through, including variant and size.

Variants

States

Interaction behaviour

• Click, Enter or Space copies value. A function value is called at that moment and may be async.
• Your onClick runs first; call event.preventDefault() in it to skip the copy.
• Each attempt clears and refills the live region, so copying twice is announced twice.
• The state returns to idle after resetAfter; 0 keeps it until the next attempt.

Keyboard support

Accessibility

Role

button

Accessible name

The visible label, plus the visually hidden target ("Copy" + "invite link"). Icon-only: label (+ target) as aria-label.

• The result is announced through a role="status" live region outside the button, so it is not part of the button name.
• Icon-only buttons keep a stable aria-label; the change is announced instead of renamed.
• Use target when several copy buttons share a screen, so each has a distinct name (WCAG 2.4.6). The visible text stays at the start of the name (WCAG 2.5.3).
• Icons are decorative (aria-hidden).

Responsive behaviour

• Same height as Button at every width (--mn-control-*).
• The label never wraps; use iconOnly in tight rows such as table cells.

Theme support

• Colours come from Button and the success and danger tokens, so light, dark and more-contrast themes apply automatically.
• On primary and danger buttons the state icon inherits the on-solid text colour.
• The icon colour transition is removed under prefers-reduced-motion: reduce.

Do and don't

Related components

• CopyField: Shows the value, read-only, with this button beside it.
• SecretField: Copies a masked secret without revealing it.
• Button: The control CopyButton is built on.
• Toast: A product-level way to report onCopyError.

Dependencies

Testing coverage

• Copies the value, shows the copied state, and announces "Copied to clipboard".
• Copies with Enter and Space.
• A refused write calls onCopyError, shows the error state and announces it.
• Falls back to execCommand when the Clipboard API rejects; rejects when nothing is available.
• Returns to idle after resetAfter.
• Accepts sync and async function values.
• Icon-only keeps a stable accessible name.
• Does not copy when disabled or when onClick prevents default.
• Inactive labels are hidden from the accessible name.
• useCopyToClipboard exposes status, error and reset.

Tests: packages/react/src/components/actions/copy-button