Appearance
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 transientaria-liveregion 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
| Prop | Type | Default | Notes |
|---|---|---|---|
value | string | required | Text written to the clipboard on copy(). |
feedbackDuration | number | 2000 | Duration (ms) the copied flag stays true after a successful write. |
icon | TIcon | 'mdi:mdi-content-copy' | Icon of the built-in trigger at rest. Reachable by a theme. |
copiedIcon | TIcon | 'mdi:mdi-check' | Icon swapped in while copied is true. |
feedbackText | string | origam.clipboard.copied | Text shown in the tooltip while copied is true. Falls back to the DS locale key. |
successText | string | undefined | Alias for feedbackText. Takes precedence when both are passed. |
disabled | boolean | false | Disables the trigger; copy() short-circuits. |
tag | string | 'span' | Root element tag. |
fontSize | TFontSize | undefined | Font 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. |
fontWeight | TFontWeight | undefined | Font weight token for the built-in trigger surface (regular · medium · semibold · bold · extrabold · black). Sets --origam-clipboard__feedback---font-weight. |
Emits
| Emit | Payload | When |
|---|---|---|
copy | (value: string) | After a successful write (modern API or execCommand fallback). |
error | (err: Error) | After both paths failed (permissions denied, blocked context, …). |
Slots
| Slot | Bindings | Notes |
|---|---|---|
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
| Binding | Type | Notes |
|---|---|---|
copy | () => Promise<boolean> | Triggers the pipeline. Resolves true on success. |
copied | boolean | True for feedbackDuration ms after a successful copy. |
error | Error | null | Set 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
}| Return | Type | Notes |
|---|---|---|
copy | (text: string) => Promise<boolean> | True on success, false on failure. Never throws. |
copied | Ref<boolean> | Self-resetting after feedbackDuration ms. |
error | Ref<Error | null> | Cleared at the start of each new copy attempt. |
isSupported | Ref<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-origintoken. - 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 neitherOrigamClipboardnorOrigamTooltipsetsaria-liveanywhere. 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-labelinstead, which flips betweenorigam.clipboard.copy_aria_labelandorigam.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
#defaultscoped slot, driven by thecopiedbinding. - Custom triggers passed through
#defaultkeep their own ARIA contract — make sure to add a label (aria-labelor visible text) when the trigger is icon-only.
Related
OrigamCode— has its own internal copy button.