HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
Copy ButtonView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA button that copies a string to the clipboard and confirms the copy.StableSince 0.1.0ActionsUsageimport'@fusion.dev/helix/copy-button'import'@fusion.dev/helix-headless/copy-button'Preview
API ReferenceRoothelix-copy-buttonA button that copies a string to the clipboard and confirms the copy.
PropTypeDescriptioncommandForElementElement|nullThe element this button's command is sent to, resolved.copiedLabelstringDefault"Copied"The button's name and tooltip text after a copy.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.emphasis"ghost"|"outlined"|"solid"|"subtle"How much fill the control is drawn with.errorLabelstringDefault"Could not copy"The button's name and tooltip text after a press that put nothing on the
clipboard.feedbackDurationnumberDefault1600How long the confirmation or the failure stands, in milliseconds, before
the button goes back to label. The attribute also takes a CSS time, such
as 1.5s.focusablebooleanDefaulttrueWhether the button holds its group's tab stop.fromstringDefault""The element to copy from, by its id: key for its text, key[value] for
an attribute, and key.value for a property. Read at the press, and used
in place of value. An element that is not there copies nothing, which is
a failed copy.labelstringDefault"Copy"The button's name and tooltip text before a copy.namestringDefault""The name the control's value is submitted under.pendingbooleanDefaultfalseWhether the action the button started is still running.pendingLabelstringDefault"Loading"What a reader hears when the button becomes pending while it has focus.showLabelbooleanDefaultfalseDraws the name as words beside the icon, and the result in their place
after a press. The button stays as wide as the longest of them.tone"accent"|"danger"|"neutral"|"primary"Which color the control is drawn in, by what it means.tooltip"copy"|"full"|"none"When the tooltip shows: full on hover and focus and after a press,
copy only after a press, to show the result, and none never, for a
button whose result shows another way, such as under show-label.tooltipPlacement"bottom"|"bottom-end"|"bottom-start"|"left"|"left-end"|"left-start"|"right"|"right-end"|"right-start"|"top"|"top-end"|"top-start"Default"top"The side the tooltip prefers. It moves to another side where this one
does not fit.valuestringDefault""The text copied to the clipboard.
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescription(default)The icon shown before a copy. Defaults to a clipboard.copiedThe icon shown after a successful copy. Defaults to a check mark.failedThe icon shown after a copy that put nothing on the clipboard. Defaults to a cross.
EventTypeDescriptionhelix-copyHelixCopyEventFired after the clipboard write succeeds.helix-copy-errorHelixCopyErrorEventFired when a press put nothing on the clipboard: the browser did not allow the write, or there was nothing to copy.helix-pressHelixPressEventFired when a press acts, with detail.pointerType saying what pressed the button.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.click() => voidPresses the button, as click() presses a native one: the command is sent,
the form submits or resets, and helix-press says virtual.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.
PartDescriptionbuttonThe inner button.liveThe live region that says copied-label or error-label after a press, and pending-label when the button becomes pending under focus. It is rendered from the first time it says anything. Visually hidden in the styled tier.markThe clipboard icon, and the confirmation icon that replaces it.spinnerThe ring a pending button turns, an empty element the styled button draws over the icon. It is rendered only while the button is pending.textThe words beside the icon, under show-label. It holds all three, label, copied-label and error-label, with all but the current one hidden.tooltip-arrowThe tooltip's arrow, which points at the button.tooltip-arrow-bottomThe arrow while the bubble is below the button, on the bubble's top edge. Set together with tooltip-arrow.tooltip-arrow-leftThe arrow while the bubble is left of the button, on the bubble's right edge. Set together with tooltip-arrow.tooltip-arrow-rightThe arrow while the bubble is right of the button, on the bubble's left edge. Set together with tooltip-arrow.tooltip-arrow-topThe arrow while the bubble is above the button, on the bubble's bottom edge. Set together with tooltip-arrow.tooltip-surfaceThe tooltip bubble, forwarded from the tooltip inside the button.tooltip-surface-bottomThe bubble while it is below the button. Set together with tooltip-surface.tooltip-surface-leftThe bubble while it is left of the button. Set together with tooltip-surface.tooltip-surface-rightThe bubble while it is right of the button. Set together with tooltip-surface.tooltip-surface-topThe bubble while it is above the button. Set together with tooltip-surface.
CSS PropertyDescription--copy-button-colorThe icon's color at rest. A tone keeps its own.--copy-button-color-hoverThe icon's color under the pointer. Without it, --copy-button-color also applies on hover.--copy-button-error-colorThe cross's color after a copy that put nothing on the clipboard.--copy-button-icon-sizeThe width and height of the clipboard, check, and cross icons drawn by default.--copy-button-sizeEdge length of the button. Without it, --icon-button-size applies.--copy-button-success-colorThe check mark's color after a copy.--icon-button-backdropThe filter behind a button with material, which a translucent ground needs to be read.--icon-button-background-colorFill behind the button, in every state.--icon-button-background-color-activeFill behind the button while it is pressed. Without it, a press shows the fill of the state under it.--icon-button-background-color-hoverFill behind the button under the pointer. Without it, --icon-button-background-color also applies on hover.--icon-button-border-colorEdge color of the control, where its emphasis or raised draws an edge.--icon-button-border-widthEdge width of the control, one to four widths as border-width takes them. The theme's floating edge on a raised button, --helix-border-floating.--icon-button-foreground-colorIcon color.--icon-button-foreground-color-activeIcon color while the button is pressed. Without it, a press shows the color of the state under it.--icon-button-radiusCorner radius of the control, which a group flattens through --button-radius-start and --button-radius-end, or a corner at a time through --button-radius-start-start, --button-radius-start-end, --button-radius-end-start and --button-radius-end-end, as Button reads them.--icon-button-shadowShadow of a raised icon button. The theme's floating shadow, --helix-shadow-floating.--icon-button-sizeEdge length of the control.--icon-button-spinner-colorColor of the ring a pending button turns. It follows the icon's color.--icon-button-spinner-durationHow long the ring takes to turn once.--icon-button-spinner-sizeSize of the ring a pending button turns.
Custom stateDescriptioncopiedThe moment after a successful copy, while copied-label names the button.failedThe moment after a press that put nothing on the clipboard, while error-label names the button.pendingThe button is pending: pending is set.pressedA Button Group in a selection mode has this button pressed.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-copy-buttonA button that copies a string to the clipboard and confirms the copy.
PropTypeDescriptioncommandForElementElement|nullThe element this button's command is sent to, resolved.copiedLabelstringDefault"Copied"The button's name and tooltip text after a copy.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.errorLabelstringDefault"Could not copy"The button's name and tooltip text after a press that put nothing on the
clipboard.feedbackDurationnumberDefault1600How long the confirmation or the failure stands, in milliseconds, before
the button goes back to label. The attribute also takes a CSS time, such
as 1.5s.focusablebooleanDefaulttrueWhether the button holds its group's tab stop.fromstringDefault""The element to copy from, by its id: key for its text, key[value] for
an attribute, and key.value for a property. Read at the press, and used
in place of value. An element that is not there copies nothing, which is
a failed copy.labelstringDefault"Copy"The button's name and tooltip text before a copy.namestringDefault""The name the control's value is submitted under.pendingbooleanDefaultfalseWhether the action the button started is still running.pendingLabelstringDefault"Loading"What a reader hears when the button becomes pending while it has focus.showLabelbooleanDefaultfalseDraws the name as words beside the icon, and the result in their place
after a press. The button stays as wide as the longest of them.tooltip"copy"|"full"|"none"When the tooltip shows: full on hover and focus and after a press,
copy only after a press, to show the result, and none never, for a
button whose result shows another way, such as under show-label.tooltipPlacement"bottom"|"bottom-end"|"bottom-start"|"left"|"left-end"|"left-start"|"right"|"right-end"|"right-start"|"top"|"top-end"|"top-start"Default"top"The side the tooltip prefers. It moves to another side where this one
does not fit.valuestringDefault""The text copied to the clipboard.
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescription(default)The icon shown before a copy. Defaults to a clipboard.copiedThe icon shown after a successful copy. Defaults to a check mark.failedThe icon shown after a copy that put nothing on the clipboard. Defaults to a cross.
EventTypeDescriptionhelix-copyHelixCopyEventFired after the clipboard write succeeds.helix-copy-errorHelixCopyErrorEventFired when a press put nothing on the clipboard: the browser did not allow the write, or there was nothing to copy.helix-pressHelixPressEventFired when a press acts, with detail.pointerType saying what pressed the button.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.click() => voidPresses the button, as click() presses a native one: the command is sent,
the form submits or resets, and helix-press says virtual.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.
PartDescriptionbuttonThe inner button.liveThe live region that says copied-label or error-label after a press, and pending-label when the button becomes pending under focus. It is rendered from the first time it says anything. Visually hidden in the styled tier.markThe clipboard icon, and the confirmation icon that replaces it.spinnerThe ring a pending button turns, an empty element the styled button draws over the icon. It is rendered only while the button is pending.textThe words beside the icon, under show-label. It holds all three, label, copied-label and error-label, with all but the current one hidden.tooltip-arrowThe tooltip's arrow, which points at the button.tooltip-arrow-bottomThe arrow while the bubble is below the button, on the bubble's top edge. Set together with tooltip-arrow.tooltip-arrow-leftThe arrow while the bubble is left of the button, on the bubble's right edge. Set together with tooltip-arrow.tooltip-arrow-rightThe arrow while the bubble is right of the button, on the bubble's left edge. Set together with tooltip-arrow.tooltip-arrow-topThe arrow while the bubble is above the button, on the bubble's bottom edge. Set together with tooltip-arrow.tooltip-surfaceThe tooltip bubble, forwarded from the tooltip inside the button.tooltip-surface-bottomThe bubble while it is below the button. Set together with tooltip-surface.tooltip-surface-leftThe bubble while it is left of the button. Set together with tooltip-surface.tooltip-surface-rightThe bubble while it is right of the button. Set together with tooltip-surface.tooltip-surface-topThe bubble while it is above the button. Set together with tooltip-surface.
Custom stateDescriptioncopiedThe moment after a successful copy, while copied-label names the button.failedThe moment after a press that put nothing on the clipboard, while error-label names the button.pendingThe button is pending: pending is set.pressedA Button Group in a selection mode has this button pressed.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionEventsThe helix-copy event, sent after the text is on the clipboard.LabelThe name as words beside the icon with show-label, and a tooltip that shows only the result of a copy.PreviewA button that copies a string and shows a confirmation for a moment.PreviewA button that copies a string and shows a confirmation for a moment.