Skip to main content

CopyButton

Copy a value to the clipboard and show a short copied state.

Props
Slots

Anatomy#

CopyButton [component; slot=root]
├── icon [slot]
└── label [slot]

Usage#

Use CopyButton to copy a string or ClipboardItem to the clipboard from a single control. It writes through navigator.clipboard and falls back to document.execCommand('copy') when the Clipboard API is missing or the write fails. After a copy it holds a copied or failed state for resetDelay, then returns to idle.

import { CopyButton } from 'moraine'

export function Example() {
  return <CopyButton value="https://moraine.subf.dev" />
}

Value#

value accepts a string, a ClipboardItem, a ClipboardItem[], a promise of either, or a function that returns one. A function runs on every click, and a promise is awaited first. If either fails, the copy fails and onCopyError receives the error. The execCommand fallback copies text only.

<CopyButton value={async () => (await fetch('/api/share-link')).text()}>Copy share link</CopyButton>

With text and icons#

Pass children to render a labeled button. Without children, CopyButton renders a square icon-only button at the matching icon size. iconPosition places the icon before (leading, default) or after (trailing) the label. Children can also be a function that receives the copy state, including isCopied, isError, and status.

<CopyButton value="npm i moraine">Copy Install Command</CopyButton>

Accessible name#

The button’s aria-label is Copy to clipboard, and Copied to clipboard while copied. Override the wording through the provider messages, or set aria-label to name what is copied. After a failed copy the button sets aria-invalid until resetDelay elapses.

Variant, tone, and size#

variant (solid, soft, outline, ghost), tone, and size work as on Button, but CopyButton defaults to the ghost variant and neutral tone. Inside a ButtonGroup, it inherits the group’s size, tone, and variant (except link).

Feedback duration and icons#

resetDelay sets how long the copied or failed state holds, in milliseconds; it defaults to 2000. Set icon for the idle glyph and copiedIcon for the copied glyph. Pass icon={false} to hide the icon. Use onCopySuccess, onCopyError, and onStatusChange to react to the result.

<CopyButton
  value="https://example.com"
  resetDelay={3000}
  icon="i-lucide:clipboard"
  copiedIcon="i-lucide:check-check"
/>

Headless hook: createCopy#

createCopy from moraine/utils runs the same copy logic without a button. It returns copy and reset, plus the isCopied, isError, status, error, and isSupported accessors.

import { createCopy } from 'moraine/utils'

const copy = createCopy({
  resetDelay: 2500,
  onCopySuccess: (value) => console.log('Copied:', value),
})

// Trigger programmatically:
copy.copy('Hello world')

Examples#

Copy a command from a read-only field#

Pair a read-only Input with an icon-only CopyButton so the user can read and copy the command.

import { CopyButton, Input } from 'moraine'

export function CopyButtonUsage() {
  const code = 'pnpm add moraine'

  return (
    <div class="flex gap-2 max-w-sm w-full items-center">
      <Input value={code} readOnly class="font-mono" />
      <CopyButton value={code} />
    </div>
  )
}

Swap icons and hold the copied state longer#

Set icon and copiedIcon for the two states, and raise resetDelay to keep the confirmation visible.

import { CopyButton, Input } from 'moraine'

export function CustomIcons() {
  const token = 'ghp_exampleTokenValue1234567890'

  return (
    <div class="flex gap-2 max-w-sm w-full items-center">
      <Input value={token} readOnly type="password" class="font-mono" />
      <CopyButton
        value={token}
        icon="i-lucide:clipboard"
        copiedIcon="i-lucide:check-check"
        resetDelay={3000}
        aria-label="Copy personal access token"
      />
    </div>
  )
}

Change the label while copied#

Pass a function child to read state.isCopied and show different label text after a copy. Set iconPosition="trailing" to move the icon after the label.

import { CopyButton } from 'moraine'

export function WithLabel() {
  const curlCommand = 'curl -s https://moraine.subf.dev/install.sh | bash'

  return (
    <div class="flex flex-wrap gap-3 items-center justify-center">
      <CopyButton value={curlCommand} variant="soft" size="sm">
        {(state) => (state.isCopied ? 'Copied to clipboard!' : 'Copy curl command')}
      </CopyButton>

      <CopyButton value={curlCommand} variant="outline" size="sm" iconPosition="trailing">
        Copy snippet
      </CopyButton>
    </div>
  )
}

API Reference#

Attributes#

Attributes
data-copied
Slot: copy-buttoncopy-button-icon
Description: Present while the copied state is active.
data-disabled
Slot: copy-button
Description: Present when the component, slot, or item is disabled.

Props#

Props for the CopyButton component. Renders a <button> element by default.

Prop