# CopyButton

Copies a value to the clipboard and confirms the copy.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/CopyButton.tsx)

## Overview

A copy button is an icon-only button that writes a value to the clipboard and confirms the copy for two seconds.

## Examples

### Basic

```tsx
import { CopyButton } from '@tempoxyz/ds'

export function Demo() {
  return <CopyButton value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/CopyButton/Basic.tsx)

### Size

Set `size` to `small` (default), `medium`, or `large`.

```tsx
import { CopyButton, style } from '@tempoxyz/ds'

const address = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['small', 'medium', 'large'] as const).map((size) => (
        <CopyButton key={size} size={size} value={address} />
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/CopyButton/Size.tsx)

### Variant

Set `variant` to any [Button](/docs/components/button) variant, such as `tertiary` (default) or `secondary`.

```tsx
import { CopyButton, style } from '@tempoxyz/ds'

const address = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'

export function Demo() {
  return (
    <div {...styles.row()}>
      <CopyButton value={address} />
      <CopyButton value={address} variant="secondary" />
      <CopyButton size="medium" value={address} variant="secondary" />
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/CopyButton/Variant.tsx)

### Disabled

```tsx
import { CopyButton } from '@tempoxyz/ds'

export function Demo() {
  return <CopyButton disabled value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/CopyButton/Disabled.tsx)

### Copy Error

Pass `onCopyError` to show a recovery when the clipboard refuses the write. The button keeps its copy icon and name.

```tsx
/**
 * CopyButton demo for the Copy Error example: a recovery message after a refused write.
 * @module
 */
import { CopyButton, style } from '@tempoxyz/ds'
import { useState } from 'react'

const link = 'https://tempo.xyz/invite/example'

/** Renders a selectable value whose copy button reports a refused write. */
export function Demo() {
  const [failed, setFailed] = useState(false)

  return (
    <div {...styles.stack()}>
      <span {...styles.row()}>
        <span {...styles.value()}>{link}</span>
        <CopyButton
          aria-label="Copy invite link"
          onCopy={() => setFailed(false)}
          onCopyError={() => setFailed(true)}
          value={link}
        />
      </span>
      {failed && (
        <span role="alert" {...styles.error()}>
          Couldn’t copy. Select the link and copy it.
        </span>
      )}
    </div>
  )
}

namespace styles {
  export const error = style({ color: 'content.negative', typography: 'body.b2' })

  export const row = style({ alignItems: 'center', columnGap: '4', display: 'flex' })

  export const stack = style({ display: 'grid', gap: '8', justifyItems: 'start' })

  export const value = style({ color: 'content.primary', typography: 'mono.m1' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/CopyButton/Error.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { CopyButton } from '@tempoxyz/ds'

<CopyButton />
```

## Guidelines

### When to Use

* Copy a value you'd otherwise select by hand, such as a webhook ID or an invite link.
* Add copying beside a value in your own layout, such as a table cell.

### When Not to Use

* Use [Hex](/docs/components/hex) with `copy` for addresses and transaction hashes. It truncates the middle and adds this button.
* Use [Snippet](/docs/components/snippet) for a command or code value.
* Use [SecretValue](/docs/components/secret-value) for API keys and other secrets that stay hidden until revealed.
* Use a [Button](/docs/components/button) for other actions, such as Share or Download.

### Place It Right After the Value

Put the button on the same line, immediately after the value. Give each value its own button.

**Do:** Place a copy button directly after each value.

```tsx
/**
 * Do example for "Place It Right After the Value" on the CopyButton page.
 * Place a copy button directly after each value.
 * @module
 */
import { CopyButton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.rows()}>
      <div {...styles.row()}>
        <span {...styles.label()}>Webhook ID</span>
        <span {...styles.value()}>
          wh_51c8e20d
          <CopyButton aria-label="Copy webhook ID" value="wh_51c8e20d" />
        </span>
      </div>
      <div {...styles.row()}>
        <span {...styles.label()}>Key ID</span>
        <span {...styles.value()}>
          key_9f2c41a7
          <CopyButton aria-label="Copy key ID" value="key_9f2c41a7" />
        </span>
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const row = style({
    alignItems: 'center',
    display: 'flex',
    justifyContent: 'space-between',
    minHeight: '32',
  })

  export const rows = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
    width: '16rem !custom',
  })

  export const value = style({
    alignItems: 'center',
    color: 'content.primary',
    columnGap: '4',
    display: 'flex',
    typography: 'mono.m1',
  })
}
```

**Don't:** Place one copy button away from the values, where its target is unclear.

```tsx
/**
 * Don't example for "Place It Right After the Value" on the CopyButton page.
 * Don't place one copy button away from the values, where its target is unclear.
 * @module
 */
import { CopyButton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.rows()}>
      <div {...styles.header()}>
        <span {...styles.title()}>Webhook</span>
        <CopyButton aria-label="Copy" value="wh_51c8e20d" />
      </div>
      <div {...styles.row()}>
        <span {...styles.label()}>Webhook ID</span>
        <span {...styles.value()}>wh_51c8e20d</span>
      </div>
      <div {...styles.row()}>
        <span {...styles.label()}>Key ID</span>
        <span {...styles.value()}>key_9f2c41a7</span>
      </div>
    </div>
  )
}

namespace styles {
  export const header = style({
    alignItems: 'center',
    display: 'flex',
    justifyContent: 'space-between',
    marginBottom: '4',
  })

  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const row = style({
    alignItems: 'center',
    display: 'flex',
    justifyContent: 'space-between',
    minHeight: '32',
  })

  export const rows = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
    width: '16rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'body.b1Strong' })

  export const value = style({ color: 'content.primary', typography: 'mono.m1' })
}
```

### Copy the Full Value

Pass the complete value to `value`, even when the screen shows a shortened form.

**Do:** Copy the complete value behind a shortened display.

```tsx
/**
 * Do example for "Copy the Full Value" on the CopyButton page.
 * Copy the complete value behind a shortened display.
 * @module
 */
import { CopyButton, style } from '@tempoxyz/ds'

const url = 'https://hooks.tempo.xyz/v1/payments/wh_51c8e20d'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <span {...styles.value()}>
        hooks.tempo.xyz/…/wh_51c8e20d
        <CopyButton aria-label="Copy webhook URL" copied value={url} />
      </span>
      <div {...styles.clipboard()}>
        <span {...styles.label()}>Clipboard</span>
        <span {...styles.copied()}>{url}</span>
      </div>
    </div>
  )
}

namespace styles {
  export const clipboard = style({
    backgroundColor: 'container.regular',
    borderRadius: '2xs',
    display: 'flex',
    flexDirection: 'column',
    paddingBlock: '8',
    paddingInline: '12',
    rowGap: '2px !custom',
  })

  export const copied = style({ color: 'content.primary', typography: 'mono.m1' })

  export const label = style({ color: 'content.secondary', typography: 'body.b3' })

  export const stack = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
    width: '17rem !custom',
  })

  export const value = style({
    alignItems: 'center',
    color: 'content.primary',
    columnGap: '4',
    display: 'flex',
    typography: 'mono.m1',
  })
}
```

**Don't:** Copy the shortened text that the screen shows.

```tsx
/**
 * Don't example for "Copy the Full Value" on the CopyButton page.
 * Don't copy the shortened text that the screen shows.
 * @module
 */
import { CopyButton, style } from '@tempoxyz/ds'

const display = 'hooks.tempo.xyz/…/wh_51c8e20d'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <span {...styles.value()}>
        {display}
        <CopyButton aria-label="Copy webhook URL" copied value={display} />
      </span>
      <div {...styles.clipboard()}>
        <span {...styles.label()}>Clipboard</span>
        <span {...styles.copied()}>{display}</span>
      </div>
    </div>
  )
}

namespace styles {
  export const clipboard = style({
    backgroundColor: 'container.regular',
    borderRadius: '2xs',
    display: 'flex',
    flexDirection: 'column',
    paddingBlock: '8',
    paddingInline: '12',
    rowGap: '2px !custom',
  })

  export const copied = style({ color: 'content.primary', typography: 'mono.m1' })

  export const label = style({ color: 'content.secondary', typography: 'body.b3' })

  export const stack = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
    width: '17rem !custom',
  })

  export const value = style({
    alignItems: 'center',
    color: 'content.primary',
    columnGap: '4',
    display: 'flex',
    typography: 'mono.m1',
  })
}
```

### Keep the Built-In Confirmation

After a copy, the icon turns into a check for two seconds and screen readers announce Copied. If the clipboard refuses the write, the button shows no confirmation and calls `onCopyError` instead of `onCopy`, so keep the value selectable as text.

**Do:** Let the check icon confirm the copy.

```tsx
/**
 * Do example for "Keep the Built-In Confirmation" on the CopyButton page.
 * Let the check icon confirm the copy.
 * @module
 */
import { CopyButton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <div {...styles.row()}>
        <span {...styles.label()}>Webhook ID</span>
        <span {...styles.value()}>
          wh_51c8e20d
          <CopyButton aria-label="Copy webhook ID" copied value="wh_51c8e20d" />
        </span>
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const row = style({
    alignItems: 'center',
    display: 'flex',
    justifyContent: 'space-between',
    minHeight: '32',
  })

  export const stack = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '16',
    width: '16rem !custom',
  })

  export const value = style({
    alignItems: 'center',
    color: 'content.primary',
    columnGap: '4',
    display: 'flex',
    typography: 'mono.m1',
  })
}
```

**Don't:** Add a [Toast](/docs/components/toast) or text such as Copied to clipboard.

```tsx
/**
 * Don't example for "Keep the Built-In Confirmation" on the CopyButton page.
 * Don't add a Toast or text such as Copied to clipboard.
 * @module
 */
import { CopyButton, style } from '@tempoxyz/ds'
import { CheckCircle } from '@tempoxyz/ds/icons'

// Toasts render in a portal, so this preview draws one in place with the toast's styles.
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <div {...styles.row()}>
        <span {...styles.label()}>Webhook ID</span>
        <span {...styles.value()}>
          wh_51c8e20d
          <CopyButton aria-label="Copy webhook ID" copied value="wh_51c8e20d" />
        </span>
      </div>
      <div {...styles.toast()}>
        <CheckCircle {...styles.icon()} />
        <span {...styles.title()}>Copied to clipboard</span>
      </div>
    </div>
  )
}

namespace styles {
  export const icon = style({ color: 'content.positive', flexShrink: '0 !custom', fontSize: '20' })

  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const row = style({
    alignItems: 'center',
    display: 'flex',
    justifyContent: 'space-between',
    minHeight: '32',
  })

  export const stack = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '16',
    width: '16rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'body.b2Strong' })

  export const toast = style({
    alignItems: 'center',
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    columnGap: '12',
    display: 'flex',
    paddingBlock: '16',
    paddingInline: '20',
  })

  export const value = style({
    alignItems: 'center',
    color: 'content.primary',
    columnGap: '4',
    display: 'flex',
    typography: 'mono.m1',
  })
}
```

### Choose a Variant by Context

* **Text (default):** Inline values in rows, tables, and cards.
* **Secondary (secondary):** A standalone value you mainly copy, such as an invite link.

Keep `small` beside body text. Use `medium` or `large` in touch layouts, or beside a large value or a control of that size.

### Let a Clickable Row Copy

If a whole row copies on press, handle the copy in the row and pass `copied` to the button. The button shows the confirmation without a second copy. [Snippet](/docs/components/snippet) and [SecretValue](/docs/components/secret-value) work this way.

**Do:** Pass `copied` so the button confirms the row's copy.

```tsx
/**
 * Do example for "Let a Clickable Row Copy" on the CopyButton page.
 * Pass `copied` so the button confirms the row's copy.
 * @module
 */
import { CopyButton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <span {...styles.label()}>Invite link</span>
      <span {...styles.value()}>
        tempo.xyz/invite/7kq2
        <CopyButton aria-label="Copy invite link" copied value="https://tempo.xyz/invite/7kq2" />
      </span>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  // The pressed row draws its hover background, since the preview is inert.
  export const row = style({
    alignItems: 'center',
    backgroundColor: 'container.regular',
    borderRadius: 'xs',
    boxSizing: 'border-box',
    display: 'flex',
    justifyContent: 'space-between',
    minHeight: '40',
    paddingInline: '12',
    width: '17rem !custom',
  })

  export const value = style({
    alignItems: 'center',
    color: 'content.primary',
    columnGap: '4',
    display: 'flex',
    typography: 'mono.m1',
  })
}
```

**Don't:** Leave the button unconfirmed after the row copies.

```tsx
/**
 * Don't example for "Let a Clickable Row Copy" on the CopyButton page.
 * Don't leave the button unconfirmed after the row copies.
 * @module
 */
import { CopyButton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <span {...styles.label()}>Invite link</span>
      <span {...styles.value()}>
        tempo.xyz/invite/7kq2
        <CopyButton aria-label="Copy invite link" value="https://tempo.xyz/invite/7kq2" />
      </span>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  // The pressed row draws its hover background, since the preview is inert.
  export const row = style({
    alignItems: 'center',
    backgroundColor: 'container.regular',
    borderRadius: 'xs',
    boxSizing: 'border-box',
    display: 'flex',
    justifyContent: 'space-between',
    minHeight: '40',
    paddingInline: '12',
    width: '17rem !custom',
  })

  export const value = style({
    alignItems: 'center',
    color: 'content.primary',
    columnGap: '4',
    display: 'flex',
    typography: 'mono.m1',
  })
}
```

## Accessibility

A copy button renders an icon-only [Button](/docs/components/button) with a visually hidden status message. It follows the [WAI-ARIA Authoring Practices button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/).

### Semantics

* **Button (button):** A native button. Enter and Space copy, and it joins the tab order.
* **Name (aria-label):** Defaults to "Copy" and the value. Shows on hover, not on focus or touch.
* **Copied State (2s):** After a copy, the name changes to "Copied", then returns.
* **Status Region (status):** A polite live region holds the confirmation text.
* **Disabled (disabled):** Removes the button from the tab order unless you set `focusableWhenDisabled`.
* **Clipboard Fallback (execCommand):** Copies where the Clipboard API is unavailable, such as insecure contexts and some iframes.

### Keyboard

* **Move Focus to the Button (Tab):** Moves focus to the button.
* **Copy the Value (Enter or Space):** Copies the value.

### Your Responsibilities

* **Name What It Copies (aria-label):** Name the value, such as "Copy address". A raw address reads poorly.
* **Announce Parent Failures (copied):** If a parent copies on its own click, announce failures from that parent.
* **Recover From Failures (onCopyError):** If the clipboard refuses the write, say so and keep the value selectable.

## Related

[Hex](/docs/components/hex)

Use for addresses and hashes with copying built in.

[Snippet](/docs/components/snippet)

Use for commands and code.

[SecretValue](/docs/components/secret-value)

Use for API keys and secrets.

[Button](/docs/components/button)

Use for other icon-only actions.

[Blockchain Values](/docs/patterns/blockchain-values)

Covers showing addresses, hashes, and amounts.
