CopyButton

Copy an exact value

Supply the precise string and an action label identifying it. The visible action is “Copy”; label supplies its accessible name and identifies the request in feedback. Keep the associated value readable and selectable beside the action.

<code>{equipment.id}</code>
<CopyButton value={equipment.id} label="Copy equipment ID" size="sm" />

The component preserves whitespace, line breaks and supplied precision. It uses the browser clipboard write API only on activation. Browser permissions and availability determine whether the write succeeds.

Sizes

Disabled

Use disabled when the action itself is unavailable. An unsupported browser reports copy failure on activation, so the user can still select the associated value manually.

Request feedback and callbacks

The live status shows pending feedback until the write settles. Success appears only after resolution; unavailable support and rejected writes show visible failure. Feedback persists until the next activation or a change to value or label. It reads the label, then the outcome, so it makes sense with or without a leading verb: "Copy equipment ID: copied", "Copy equipment ID: failed. Select the value and copy it manually."

onCopy receives { value } after a successful write. onCopyError receives { value, error } for a failed request. Both refer to the string captured at activation. Changes to value or label, or unmounting, suppress late feedback and callbacks. Another activation is allowed after the pending request settles. Exceptions thrown by consumer callbacks do not change the clipboard outcome.

<CopyButton
  value={equipment.id}
  label="Copy equipment ID"
  onCopy={({ value }) => recordCopiedValue(value)}
  onCopyError={({ value, error }) => recordCopyFailure(value, error)}
/>

Props

Accessibility

• Tab reaches the native button; Enter and Space activate it.
• A required identifying label names the action, and the decorative icon is hidden from assistive technology.
• The polite live status announces pending, success and failure as text, the label first.
• The action is a tertiary Button, so its boundary is the control outline, and its icon is drawn at the size other Buttons with an icon use (12, 16 and 20 px for sm, md and lg).
• Focus remains on the button while pending. aria-disabled communicates that further requests are blocked until settlement.
• A forwarded ref targets the native button. className also applies to that button.
• Existing Button sizing, focus styling, forced colors and reduced motion behavior apply.
• Keep the exact source value readable and selectable for manual copying when clipboard writing fails.

Manifest entry

<CopyButton value={equipment.id} label="Copy equipment ID" size="sm" />

{
  "description": "Copies a supplied exact string with visible pending, success and failure feedback.",
  "props": {
    "value": {
      "type": "string",
      "required": true,
      "description": "Exact string to copy; whitespace and precision are preserved."
    },
    "label": {
      "type": "string",
      "required": true,
      "description": "Accessible action name identifying the value. Feedback reads this label, then the outcome: \"Copy equipment ID: copied\"."
    },
    "size": {
      "type": "enum",
      "values": [
        "sm",
        "md",
        "lg"
      ],
      "default": "md"
    },
    "disabled": {
      "type": "boolean",
      "default": false
    },
    "className": {
      "type": "string",
      "description": "Classes applied to the native action button."
    },
    "onCopy": {
      "type": "function",
      "description": "Receives { value } after the requested write resolves. Suppressed after context changes or unmount."
    },
    "onCopyError": {
      "type": "function",
      "description": "Receives { value, error } if writing fails or is unavailable. Suppressed after context changes or unmount."
    }
  },
  "composable_with": [
    "DescriptionList",
    "EntityPreview",
    "Popover",
    "Inspector",
    "Toolbar"
  ],
  "never_inside": [
    "Button",
    "Link"
  ],
  "example": "<CopyButton value={equipment.id} label=\"Copy equipment ID\" size=\"sm\" />"
}