Inputs

CopyButton

A Button that copies a string to the clipboard and says so.

Import

TSX

import { CopyButton } from "@loamui/core";

Usage

Every example has a CSS tab. That’s the real, complete stylesheet for the component: plain, static CSS, with nothing running in the browser.

Copy a command

Click and the command is on the clipboard. The label reads Copied for a moment and a live region announces the same word, then the label reverts, so the button never claims a copy it made a while ago.

Icon only

An svg child is detected by Button as an icon, and the aria-label names the button and makes it square. The label swaps to Copied only when the button has visible text: an icon-only button keeps its icon and its name, and the confirmation is carried by the announcement alone, so pair it with a Tooltip or nearby text where a sighted user needs to see it.

Your own words

The rest label is the children; the confirmation and the failure are labels.copied and labels.failed, so every word can be translated or made specific. The timeout decides how long the confirmation stands.

After a copy

onCopy is called with the value once it is on the clipboard, and not on failure, so anything that depends on the copy having happened (a note, a step marked done) runs only when it did.

Nothing copied yet.

Guidance

When to use it

To put a short string on the clipboard in one action: an install command, a link, a token, an id, a code sample.
Next to text the reader would otherwise have to select precisely, especially where selection is awkward (a code block, a table cell, a value on a touch screen).

When not to

For a whole document or a large export: that is a download (a link to the file), not a clipboard write.
To share something with another app or person: that is navigator.share and a different button, with its own sheet and its own wording.

How it works

The announcement is the feedback

A label that changes from Copy to Copied is invisible to a screen reader, whose focus is sitting on the button it already named. So the same words go into a visually hidden role="status" region, which is polite: it is read after whatever is being read now, without moving focus. The region is in the DOM from the start, since a live region only announces a change, and it empties again after the timeout so the next copy is a change too.

The label reverts so the button stays honest

Copied is a confirmation, not a state: the clipboard can be overwritten by anything at any time, so a button that kept saying Copied would soon be wrong. The label goes back after the timeout, and there is no aria-pressed, because nothing is toggled. The default of 1.5 seconds is long enough to be read and short enough that a second copy does not have to wait for it.

Failure is said, not swallowed

The clipboard can refuse: there is no API on an insecure origin, the permission can be denied, and the document may not have focus. There is no selection to fall back on, so the button announces what happened and what to do (select the text and copy it yourself) through the same region, and leaves its label alone. A click that silently did nothing would leave the reader believing the value was copied.

Props

Status is not a prop: it comes from the surrounding --loam-context region. See the Contextualism guide.

Prop	Type	Default	Description
`value`	`string`	—	The text written to the clipboard.
`children`	`ReactNode`	`"Copy"`	The label at rest. An svg child is detected by Button as an icon.
`labels`	`{ copied?: ReactNode; failed?: ReactNode }`	`{ copied: "Copied", failed: "Copy failed: select the text and copy it yourself" }`	The words the button says: copied is shown, and announced, after a successful copy; failed is announced when the clipboard refuses, and the label is left as it was.
`timeout`	`number`	`1500`	How long the copied label and the announcement stand, in ms.
`onCopy`	`(value: string) => void`	—	Called with the value once it is on the clipboard. Replaces the native onCopy event, which fires on copying a selection a button never holds.
`...others`	`ButtonProps`	—	Every Button prop is forwarded, including className, style, ref and aria-label.