Skip to content

OrigamClipboard ​

A headless-ish wrapper that adds the "copy to clipboard" behaviour around any trigger — a button, an icon, a span — and exposes an auto-resetting copied flag so consumers don't have to wire the timeout. The copy pipeline uses navigator.clipboard.writeText and falls back to a hidden-textarea + document.execCommand('copy') for non-HTTPS contexts and pre-permissions Safari / WebView builds.

vue
<template>
    <!-- Built-in trigger: an <origam-btn> whose icon swaps on success -->
    <origam-clipboard :value="userEmail" />

    <!-- Custom trigger via scoped slot -->
    <origam-clipboard :value="apiKey">
        <template #default="{ copy, copied }">
            <origam-btn @click="copy">
                {{ copied ? 'Copied!' : 'Copy API key' }}
            </origam-btn>
        </template>
    </origam-clipboard>
</template>

When no slot is provided the component renders a single <origam-btn> (icon mdi:mdi-content-copy, configurable via the icon prop). On success the button swaps to copiedIcon (mdi:mdi-check) and the feedback text appears in a tooltip, not inside the button.

Changed. The trigger used to be a raw <button> carrying the feedback text inline, which widened it mid-interaction and placed a transient aria-live region inside a control. The icon was a module-level constant no consumer — and no theme — could reach.

There is no separate pill, no mode prop, no double rendering. If you only want a different label/marker inside that same built-in button, pass a #feedback scoped slot (see below). If you need a richer feedback (toast, inline status, custom animation) — or a different trigger altogether — pass a #default scoped slot and render whatever you want from { copy, copied, error }.

Props ​

PropTypeDefaultNotes
valuestringrequiredText written to the clipboard on copy().
feedbackDurationnumber2000Duration (ms) the copied flag stays true after a successful write.
iconTIcon'mdi:mdi-content-copy'Icon of the built-in trigger at rest. Reachable by a theme.
copiedIconTIcon'mdi:mdi-check'Icon swapped in while copied is true.
feedbackTextstringorigam.clipboard.copiedText shown in the tooltip while copied is true. Falls back to the DS locale key.
successTextstringundefinedAlias for feedbackText. Takes precedence when both are passed.
disabledbooleanfalseDisables the trigger; copy() short-circuits.
tagstring'span'Root element tag.
fontSizeTFontSizeundefinedFont size token for the built-in trigger surface (xs · sm · md · lg · xl · …). Sets --origam-clipboard__feedback---font-size. Has no effect when the #default slot is used.
fontWeightTFontWeightundefinedFont weight token for the built-in trigger surface (regular · medium · semibold · bold · extrabold · black). Sets --origam-clipboard__feedback---font-weight.

Emits ​

EmitPayloadWhen
copy(value: string)After a successful write (modern API or execCommand fallback).
error(err: Error)After both paths failed (permissions denied, blocked context, …).

Slots ​

SlotBindingsNotes
default{ copy, copied, error }Custom trigger. Replaces the built-in icon button entirely.
feedback{ copied: boolean }Custom marker rendered inside the built-in trigger while copied is true, replacing feedbackText. Only applies when #default is NOT overridden — a custom trigger has no button to render it in.

default scoped bindings ​

BindingTypeNotes
copy() => Promise<boolean>Triggers the pipeline. Resolves true on success.
copiedbooleanTrue for feedbackDuration ms after a successful copy.
errorError | nullSet when the last attempt failed; null after a fresh successful attempt.

feedback example ​

vue
<template>
    <!-- Built-in icon + button chrome, custom marker instead of "Copied!" -->
    <origam-clipboard :value="apiKey">
        <template #feedback="{ copied }">
            <span>{{ copied ? '✓ Done' : '' }}</span>
        </template>
    </origam-clipboard>
</template>

useClipboard composable ​

When you don't need any chrome, use the composable directly:

ts
import { useClipboard } from '@origam/composables'

const { copy, copied, error, isSupported } = useClipboard({ feedbackDuration: 2000 })

async function onCopy () {
    await copy('text to copy')
    // copied.value === true for 2000 ms, then auto-resets to false
}
ReturnTypeNotes
copy(text: string) => Promise<boolean>True on success, false on failure. Never throws.
copiedRef<boolean>Self-resetting after feedbackDuration ms.
errorRef<Error | null>Cleared at the start of each new copy attempt.
isSupportedRef<boolean>True when navigator.clipboard.writeText is available. False in SSR / blocked contexts.

The composable auto-clears its pending timer on scope dispose (onScopeDispose) — no manual cleanup needed when used inside a setup() or an effectScope().

Fallback (execCommand) ​

The legacy document.execCommand('copy') path is used only when the modern API is missing or rejects. It works in non-HTTPS contexts (localhost included) and pre-permissions Safari. It will not work in:

  • Sandboxed iframes without the allow-same-origin token.
  • Background scripts / extension service workers (no document).
  • Server-side rendering — the composable short-circuits via a typeof document === 'undefined' guard and returns false.

For production deployments on HTTPS with a modern browser, the modern API is always preferred; the fallback exists for development / embedded scenarios.

Accessibility ​

  • The default trigger is a native <button> — keyboard / focus / disabled semantics come for free.
  • ⛔ There is no live region. The confirmation text is rendered inside an <origam-tooltip> — not in a label next to the icon — and neither OrigamClipboard nor OrigamTooltip sets aria-live anywhere. The transient live region that used to sit inside the control was removed on purpose along with the raw <button> trigger (see Changed at the top of this page).
  • The state change is surfaced through the trigger's aria-label instead, which flips between origam.clipboard.copy_aria_label and origam.clipboard.copied_aria_label ("Copy to clipboard" / "Value copied to clipboard" in the shipped English messages). A screen reader on the focused button announces the new label; the swap is what assistive tech picks up, since the visual feedback lives in a tooltip.
  • If your flow needs a guaranteed announcement even when focus has moved away, render your own live region from the #default scoped slot, driven by the copied binding.
  • Custom triggers passed through #default keep their own ARIA contract — make sure to add a label (aria-label or visible text) when the trigger is icon-only.
  • OrigamCode — has its own internal copy button.