Skip to content

Copy

A button that copies another element's text or shares a link, and says Copied or Copy failed.

<div class="cap-specimen-row">
  <p>The post is at <a id="post-link" href="https://example.com/field-notes">example.com/field-notes</a>.</p>
  <span class="cap-copy">
    <button type="button" class="cap-btn cap-copy-button" data-variant="secondary" id="copy-link" command="--copy" commandfor="post-link" data-cap-copied="Link copied">
      <span class="cap-copy-icon"><svg aria-hidden="true"><use href="#glyph-copy" /></svg></span>
      <span class="cap-copy-done"><svg aria-hidden="true"><use href="#glyph-done" /></svg></span>
      Copy link
    </button>
    <span class="cap-copy-tip" role="status"></span>
  </span>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/copy.css";
import { enhance } from "capsomer/behavior/copy";

enhance();

Usage

<span class="cap-copy">
  <button type="button" class="cap-btn cap-copy-button" data-variant="quiet"
          command="--copy" commandfor="api-key" aria-label="Copy API key">
    <span class="cap-copy-icon"><svg aria-hidden="true">…</svg></span>
    <span class="cap-copy-done"><svg aria-hidden="true">…</svg></span>
  </button>
  <span class="cap-copy-tip" role="status"></span>
</span>
<code id="api-key">fh_live_…</code>
<CopyButton text={key} aria-label="Copy API key" />
<CopyButton share={{ url, title }}>Share</CopyButton>

Examples

Copied and failed

<div class="cap-specimen-row">
  <span class="cap-copy">
    <button type="button" class="cap-btn cap-copy-button" data-variant="quiet" data-state="done" id="copy-done" aria-label="Copy release notes">
      <span class="cap-copy-icon"><svg aria-hidden="true"><use href="#glyph-copy" /></svg></span>
      <span class="cap-copy-done"><svg aria-hidden="true"><use href="#glyph-done" /></svg></span>
    </button>
    <span class="cap-copy-tip" id="tip-done">Copied</span>
  </span>
  <span class="cap-copy">
    <button type="button" class="cap-btn cap-copy-button" data-variant="quiet" data-state="failed" id="copy-failed" aria-label="Copy annual report link">
      <span class="cap-copy-icon"><svg aria-hidden="true"><use href="#glyph-copy" /></svg></span>
      <span class="cap-copy-done"><svg aria-hidden="true"><use href="#glyph-done" /></svg></span>
    </button>
    <span class="cap-copy-tip" id="tip-failed">Copy failed</span>
  </span>
</div>

Icon only, over a repeated block

<div class="cap-copyable">
  <pre tabindex="0"><code id="snippet">npm install capsomer</code></pre>
  <span class="cap-copy">
    <button type="button" class="cap-btn cap-copy-button" data-variant="quiet" id="copy-snippet" command="--copy" commandfor="snippet" aria-label="Copy install command">
      <span class="cap-copy-icon"><svg aria-hidden="true"><use href="#glyph-copy" /></svg></span>
      <span class="cap-copy-done"><svg aria-hidden="true"><use href="#glyph-done" /></svg></span>
    </button>
    <span class="cap-copy-tip" role="status"></span>
  </span>
</div>

API reference

CopyButton

PropTypeRequiredDoes
textstring | (() => string)What is copied: a string, or a function read at the press (a field's current value).
share{ url: string; title?: string }Share this link with the system share sheet; copies it where sharing is missing.
childrenReactNodeThe visible label. Leave it out for an icon-only button, and give aria-label instead, naming what is copied ("Copy API key").
copiedMessagestring
failedMessagestring
variant"default" | "quiet" | "secondary"
size"xs" | "sm"
onCopied(ok: boolean) => void

And every attribute of <button>.

Functions

FunctionSignatureDoes
useCopy(messages?: { copied?: string | undefined; failed?: string | undefined; }): { copy: (text: string) => Promise<boolean>; share: (data: { url: string; title?: string | undefined; }) => Promise<...>; state: "failed" | ... 1 more ... | undefined; message: string; }The copy state for a React control: run() copies (or shares) and keeps the outcome and its message for as long as the message should show. A repeat restarts it. Never throws.
copyText(text: string): Promise<boolean>Writes text to the clipboard. Never throws, synchronously or not: a missing clipboard (an insecure page) or a refused write is false. Sites are served over HTTPS, so there is no execCommand fallback (the guide keeps that for pages that cannot control their protocol).
shareLink(data: { url: string; title?: string | undefined; text?: string | undefined; }): Promise<ShareOutcome>Shares a link with the system share sheet where there is one, and copies it where there is not. A share the person cancels (AbortError) is not a failure and says nothing.
textOf(target: Element): stringThe text a target holds: a form control's value, a link's address, or the rendered text (innerText keeps line breaks that textContent loses).
messageFor(outcome: "copied" | "failed" | "shared" | "canceled", button?: HTMLElement | undefined): stringThe message for an outcome. A button may name its own with data-copied and data-failed ("Link copied"); share outcomes use data-shared.
distinct(message: string): string
report(button: HTMLElement, outcome: "copied" | "failed" | "shared" | "canceled"): voidShows an outcome on a button and its bubble (the next .cap-copy-tip in its .cap-copy), then clears both. A repeat press restarts the message rather than stacking timers. The button is never disabled, so focus stays and a failed copy can be retried at once.
run(button: HTMLElement, target: Element, command: string): Promise<void>Runs one command from a button on its target: --copy copies the target's text, --share shares the target link's address (or the page's) and copies it where sharing is missing.
enhance(root?: ParentNode): () => voidAttaches to every copy button under root. Where Invoker Commands exist the browser resolves commandfor and sends a command event (it does not bubble, so it is caught in the capture phase); elsewhere a click listener resolves commandfor the same way. Only one path is registered, so a press never copies twice. Returns a function that detaches.

Parts and data attributes

ClassIs
.cap-copythe root
.cap-copy-buttona part
.cap-copy-donea part
.cap-copy-icona part
.cap-copy-tipa part
.cap-copyableits own class
AttributeValues
data-statedone
StateRead from
:emptythe platform
:focus-visiblethe platform
:focus-withinthe platform
:hoverthe platform

Accessibility

KeyDoes
TabMoves to the button; in a repeated block, also reveals it
Enter, SpaceCopies, or opens the share sheet
  • An icon-only button is named for what it copies (aria-label="Copy API key"); a button with visible text is named by that text.
  • At least var(--target) in each direction, and allowed to grow.
  • In a repeated block the button is hidden with opacity only where hover exists, and shows on hover, on focus within the block and while its message shows. On touch it stays visible, in flow beside the block. It is never hidden, inert or aria-hidden.
  • Forced colors: the bubble has an edge.