HyCopyButton

Usage examples on this page are written for Lit / plain HTML (<hy-copy-button>). The same component ships as HyCopyButton in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A button that copies a string to the clipboard with built-in feedback.

Copies either a static value or — via from — the resolved value of another element by id (from="tok", from="tok.value", from="link[href]"), runs a rest → success → error feedback machine that auto-reverts after feedback-duration, swaps the icon per state, and surfaces the state label through a built-in hy-tooltip (never title=).

Key Features:

• value (static) or from (resolve another element by id / property / attribute)
• rest → success → error machine with auto-revert
• Per-state icon names + a11y/tooltip labels
• Optional transform to wrap/trim before copy (e.g. v => \var(${v})``)
• size / emphasis forwarded to the inner hy-icon-button, whose square corner is the action radius (--hy-radius-action-md), so the copy button rounds with the buttons

When to use

• Next to text people paste elsewhere: a code, a key, a link, a command, an id.

Do

• Place it right after the text it copies.
• Copy exactly the text shown, with value or from.

When not to use

• Any action other than a clipboard write: hy-icon-button for an icon, hy-button for a labeled action.
• Confirming a successful copy: the built-in icon swap and tooltip. Do not add an hy-toast.

Accessibility: your part

• When several copy buttons share a view, set copy-label and success-label to say what each one copies ("Copy link").
• Do not wrap it in an hy-tooltip. Its own tooltip already carries its label.
• When a value cannot be copied, say why in text beside it. A disabled copy button cannot be focused.

Examples

Copy a static value

<hy-copy-button value="--hy-background-brand-rest"></hy-copy-button>

Copy the resolved value of another element

<code id="tok">#4f46e5</code> <hy-copy-button from="tok"></hy-copy-button>

API

Properties

Property	Attribute	Type	Default	Description
value	value	string | undefined	—	Static string to copy. Ignored when from resolves a value.
from	from	string | undefined	—	Copy from another element by id. Forms: id, id.prop, id[attr]. Resolved within the copy button's root (document or shadow root).
feedbackDuration	feedback-duration	number	1000	Auto-revert delay (ms) for the success/error state.
copyIcon	copy-icon	string	'copy'	Rest-state icon name (a registered glyph). The React copyIcon takes the SVG node itself (default IconCopy, the same glyph) — icons are nodes in React by design, so the two defaults differ in type, not in what renders.
successIcon	success-icon	string	'check'	Success-state icon name. React takes the SVG node (IconCheck).
errorIcon	error-icon	string	'close'	Error-state icon name. React takes the SVG node (IconClose).
copyLabel	copy-label	string	'Copy'	Rest-state a11y + tooltip label.
successLabel	success-label	string	'Copied'	Success-state a11y + tooltip label.
errorLabel	error-label	string	'Could not copy'	Error-state a11y + tooltip label.
disabled	disabled	boolean	false	Whether the button is disabled.
size	size	'small' | 'medium' | 'large'	'medium'	Size forwarded to the inner icon-button.
emphasis	emphasis	'solid' | 'soft' | 'outlined' | 'tinted' | 'plain'	'plain'	Emphasis forwarded to the inner icon-button.
tooltipPlacement	tooltip-placement	'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'right'	'top'	Tooltip placement.
transform	—	(raw: string) => string | undefined	—	Transform the resolved value before copying. Property-only (not an attribute).

Events

Event	Detail	Description
copy	—	Fired after a successful copy. Detail: { value: string }
error	—	Fired when the clipboard write fails (non-bubbling; listen on the element). Detail: {}

CSS Parts

Part	Description
base	The host wrapper.

CSS Custom Properties

The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.

Property	Default	Description
--hy-copy-button-foreground-success-rest	var(--hy-foreground-success-rest)	Icon color in the success state.
--hy-copy-button-foreground-danger-rest	var(--hy-foreground-danger-rest)	Icon color in the error state.

Methods

setTabIndex()

Projects a tabindex onto the inner icon button — called by a parent roving-tabindex controller (hy-toolbar) so the copy button joins its single tab stop instead of staying one of its own.

focus()

Focuses the inner icon button.