CopyController
Copies text to the clipboard on a click and reports copied or error as a data attribute and an announcement.
Reach for it for a copy button on a code sample, an invite link or a token, where the button must show the result and a screen reader must hear it.
Import
import { CopyController, createCopyController } from '@ecopages/radiant-ui/controllers';Try it
Press the button. It gets data-copy-state="copied" for 1.5 seconds, then the attribute is removed, and the message goes to the status line, which is a polite live region.
pnpm add @ecopages/radiant-ui<div data-example="copy">
<code>pnpm add @ecopages/radiant-ui</code>
<button type="button">Copy</button>
<p data-status role="status"></p>
</div>import { CopyController } from '@ecopages/radiant-ui/controllers';
export function mount(root: HTMLElement): () => void {
const button = root.querySelector('button')!;
const source = root.querySelector('code')!;
const status = root.querySelector('[data-status]')!;
const copy = new CopyController({
getText: () => source.textContent ?? '',
getTrigger: () => button,
resetDelay: 1500,
announce: (message) => (status.textContent = message),
});
copy.attach();
return () => copy.destroy();
}mount runs once for each example element on the page, and the function it returns undoes it; see how the examples run.
Recipe: a copy button on every code block
One listener on the container serves every button, including blocks added later. The button label changes with the state through CSS, so the markup keeps one accessible name.
import { CopyController } from '@ecopages/radiant-ui/controllers';
const copy = new CopyController({
getRoot: () => document.querySelector('main'),
selector: '[data-copy-button]',
getText: (button) => button!.closest('figure')!.querySelector('code')!.textContent ?? '',
announce: (message) => (document.querySelector('#copy-status')!.textContent = message),
});
copy.attach();[data-copy-button][data-copy-state='copied']::after {
content: ' copied';
}
[data-copy-button][data-copy-state='error']::after {
content: ' failed, try again';
}Config
| Option | Meaning |
|---|---|
getText | The text, or a function returning it (or a promise of it), read at copy time. Receives the trigger, null for a copy() call without one. |
getTrigger | The element whose click copies, read on attach(). Also the default trigger of copy(). |
getRoot | With selector, the element that listens for clicks on behalf of every matching descendant, read on attach(). |
selector | The delegated trigger selector, used with getRoot. |
getFeedbackTarget | The element that carries data-copy-state instead of the trigger, called with the trigger. |
resetDelay | Milliseconds copied and error show before idle. Default 2000. |
onCopy | Called with the text after a successful copy. |
onError | Called with the error after a failed one. |
announce | Called with "Copied" or "Could not copy" for a polite live region you own. The controller creates no DOM. |
getState() returns idle, copied or error. copy() copies now and resolves with { state: 'copied', text }, { state: 'error', error } or { state: 'idle' } when copy() ran before attach() or after destroy(), or a newer copy() superseded it, and the controller is not attached; it never rejects.
Lifecycle
attach() listens for the click. A copy writes with navigator.clipboard.writeText; only when that API does not exist, as on an insecure page, it uses a hidden textarea and document.execCommand('copy'). The textarea is mounted inside the trigger's [aria-modal="true"] or open dialog, otherwise beside the trigger, so a focus trap does not refuse it; the page selection and focus are restored afterwards. The state is written as data-copy-state and, after resetDelay, returns to idle and the attribute is removed, so CSS written against [data-copy-state] never matches idle; a second copy while copied shows starts the delay again. destroy() removes the listener and the pending timer and the attribute, and a copy still in flight then changes nothing.
With a host, createCopyController(host, config) does the same on connect and disconnect; see bindController.
Accessibility
A changed attribute is not announced. Pass announce and write the message into a live region that is in the page before the copy (role="status" or aria-live="polite"), as the example does. Keep the button's accessible name the same in every state and show the result visually with CSS on data-copy-state, so the name does not flicker under a screen reader. The button should be a real button so it takes Enter and Space.
Caveats
- Browsers allow the clipboard write only in response to a user gesture and, for the async API, in a secure context (HTTPS or localhost). Call
copy()from an event handler. A copy started later, from a timer or after a long await, can be refused and ends aserror. - The async API may also be refused by a permissions policy in an iframe. That is
errortoo. - A
getTextthat awaits a slow request can outlive the gesture in some browsers. On theexecCommandfallback that can make the copy fail witherror; resolve the text ahead of time when you can. - Repeating the same announcement does not re-read in every screen reader. Clearing the region before writing it again is the owner's job.
Protected hooks
None. It decides nothing an owner would change.