Button ✦Documentation has not yet been reviewed by a human.

ButtonCopy is a Button preset for copy-to-clipboard. Its copy glyph changes to a check on success or an x on failure, then returns to its resting state. onCopied(ok) reports the result. Omit the label for an icon-only copy button.

The preset composes a regular Button with <a-copy>. Use <a-copy> directly when you need the same behavior in another control.

<ButtonCopy copy="npm i @antadesign/anta" label="Copy install command" />
<ButtonCopy copy="https://anta.design" priority="tertiary" />

Icon placement

Set iconPlacement to leading, trailing, or none. With none, the button does not change. Successful pointer activation shows a confirmation beside the pointer; keyboard activation shows it at the button’s inline start. Use copiedLabel to change the message.

<ButtonCopy copy={value} label="Leading" />
<ButtonCopy copy={value} label="Trailing" iconPlacement="trailing" />
<ButtonCopy copy={value} label="No icon" iconPlacement="none" />

Copy a DOM node

Use copyNode to copy a rendered region as text/html and plain text. Bare copyNode finds the nearest data-copy-source; a string selects an ancestor. The copy control itself is omitted from the copied content.

<div data-copy-source>
  <Text>The quick brown fox jumps over the lazy dog.</Text>
  <ButtonCopy copyNode label="Copy card" />
</div>

Copy the page URL

Use copyUrl to copy location.href. copyWithUrl prefixes copied text with // URL: <current page URL>.

<ButtonCopy copyUrl label="Copy link" />
<ButtonCopy copy={snippet} copyWithUrl label="Copy snippet" />

Copy dynamic text

copy is controlled. For text generated on demand, initialize it to '' and update it in onCopyRequest. The callback fires on pointerdown or Enter/Space keydown, before activation writes the current copy value. Its return value is ignored.

const [report, setReport] = useState('')

<ButtonCopy
  copy={report}
  label="Copy report"
  onCopyRequest={() => setReport(generateReport())}
/>

Why copy is controlled

Anta supports applications whose JSX renderer runs in a worker. The DOM copy control and Clipboard API remain on the browser’s UI thread, and a callback cannot cross that boundary as a callable reference.

onCopyRequest asks the application to calculate the text. The resulting state update sends a serializable copy string to the DOM control, which writes it during the user activation required by the Clipboard API. A lazyCopy callback would only hide this state update in a main-thread wrapper and would not work across renderers. Separate copy, copyNode, and copyUrl inputs also keep the clipboard format explicit.

For client-side routing, wrap your router’s link and add role="button" and data-anta to its anchor output.

import { Link } from 'react-router-dom'

export const LinkButton = ({ label, ...props }) => (
  <Link role="button" data-anta {...props}>
    <a-button-label>{label}</a-button-label>
  </Link>
)

Beyond a plain click, a button can submit or reset a native form and dispatch a named custom event.

Form submission

For non-link buttons, type="submit" and type="reset" integrate with native forms. The form prop associates a button with a form elsewhere on the page. Submitting calls form.requestSubmit(), so the form’s validation and submit event still run. It also dispatches submitdetailed on the form with { formData, submitter: { tag, attrs } } in detail, which can identify the trigger in analytics or multi-button forms.

<form id="signup">
  <Button tone="brand" type="submit" label="Sign up" />
  <Button priority="tertiary" type="reset" label="Clear" />
</form>
<Button type="submit" form="signup" label="Submit from outside" />

Custom click events

Set data-custom-event="<name>" to dispatch a bubbling CustomEvent("<name>") on click. This is useful for declarative actions or analytics that should not take ownership of onClick.

<Button label="Save" data-custom-event="save-clicked" />

When using <a-button> directly, add its button role and keyboard tab stop.

<a-button role="button" tabindex="0" priority="primary">
  <a-icon shape="plus" aria-hidden="true"></a-icon>
  <a-button-label>Create project</a-button-label>
</a-button>

Native HTML button

Add data-anta to a native <button> to use Anta’s button styles with native keyboard and form behavior. Set type="button" for actions that should not submit a surrounding form. Use type="submit" or type="reset" for form actions.

<button type="button" data-anta tone="brand" priority="primary">Save changes</button>
<button type="button" data-anta disabled>Unavailable</button>

Copy feedback

Put <a-copy> directly inside an activatable control. Add toast for the floating success confirmation and copied-label to change its text. The confirmation uses a manual shadow popover, escapes clipping ancestors, and lets pointer events pass through. Style it with a-copy::part(feedback).

<button type="button" data-anta>
  Copy command
  <a-copy copy="npm i @antadesign/anta" toast copied-label="Copied"></a-copy>
</button>

copyrequest asks for a controlled copy refresh before activation. copydone reports { ok: boolean } after the clipboard attempt. Both events are non-bubbling. Full-bundle imports and the granular elements/a-copy entry include feedback styling. Under CSP, load their emitted CSS from an allowed URL.

Use tone, priority, size, and round before adding custom CSS. For a distinct treatment, target a class on the button and cover its interaction states.

a-button.checkout {
  color: #fff;
  background: #673de6;
  border-radius: 999px;
  padding-inline: 20px;
}

a-button.checkout:hover { background: #5931c4; }
a-button.checkout:active { background: #48269f; }

Style the copy confirmation with a-copy::part(feedback). If you customize display, use a-copy::part(feedback):popover-open so closed popovers stay hidden.