Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Actions

CopyButton

A button that copies text to the clipboard and confirms the result visually and to assistive technology.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add copy-button

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import CopyButton from './components/ui/copy-button/CopyButton.vue'

const messages = { copy: 'Copy link', copied: 'Link copied', failed: 'Could not copy link' }
</script>

<template>
  <CopyButton value="https://example.com/invite/7Xk2" :messages="messages" />
</template>

Pass the text in value and the translated names in messages. Without a default slot it is an icon-only button; add text to show a label.

When to use it

Share links

Put an icon-only copy action next to a URL, invite code, or API key.

Code snippets

Add a labelled copy action to a code block or command.

More examples

Labelled copy

Add a default slot when the action needs visible text. The text keeps the accessible name stable; the result is still announced politely.

Labelled copy
<script setup lang="ts">
import CopyButton from './components/ui/copy-button/CopyButton.vue'

const messages = {
  copy: 'Copy command',
  copied: 'Command copied',
  failed: 'Could not copy command',
}
</script>

<template>
  <div class="flex items-center gap-3">
    <code class="rounded-ui bg-muted px-3 py-2 text-sm">npx weini add button</code>
    <CopyButton value="npx weini add button" :messages="messages" variant="secondary">
      Copy
    </CopyButton>
  </div>
</template>

Handle the result

Listen for copy and error to track usage or show a fallback for manual selection.

Handle the result
<script setup lang="ts">
import { ref } from 'vue'
import CopyButton from './components/ui/copy-button/CopyButton.vue'

const messages = {
  copy: 'Copy API key',
  copied: 'API key copied',
  failed: 'Could not copy API key',
}
const status = ref('')
</script>

<template>
  <div class="grid gap-2">
    <div class="flex items-center gap-2">
      <code class="rounded-ui bg-muted px-3 py-2 text-sm">wk_live_51Hq0dExample</code>
      <CopyButton
        value="wk_live_51Hq0dExample"
        :messages="messages"
        variant="ghost"
        size="sm"
        @copy="status = 'Copied to the clipboard.'"
        @error="status = 'Select the key and copy it manually.'"
      />
    </div>
    <p class="text-sm text-muted-foreground">{{ status }}</p>
  </div>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

CopyButton

Complete API for CopyButton
NameType or signatureDefaultWhat it does
valuepropstringRequiredText written to the clipboard.
sizeprop"sm" | "md" | "lg" | undefined"md"Choose the visual size. Medium is the usual default where available.
variantprop"default" | "destructive" | "secondary" | "outline" | "ghost" | undefined"outline"Choose the visual treatment for this component.
resetAfterpropnumber | undefined2000Milliseconds before the copied or failed state returns to idle. 0 keeps it until the next copy.
messagespropCopyButtonMessagesRequiredRequired accessible names and announcements.
errorevent[error: unknown]—Emitted when error happens.
copyevent[value: string]—Emitted when copy happens.
defaultslot(() => unknown) | undefinedOptionalContent shown inside CopyButton.
iconslot((props: { status: CopyStatus; }) => unknown) | undefinedOptionalContent for the icon area of CopyButton.
statusexposedCopyStatus—Access status from a component template ref.
copyexposed() => Promise<void>—Access copy from a component template ref.
resetexposed() => void—Access reset from a component template ref.
Public type definitions
Public types
// packages/frameworks/vue/components/copy-button/types.ts
// ------- IMPORTS -------

import type { CopyButtonMessages } from '@getweini/vue/primitives/copy-button'

// ------- TYPES -------

export type { CopyButtonMessages }

export interface CopyButtonProps {
  /** Text written to the clipboard. */
  value: string
  size?: 'sm' | 'md' | 'lg'
  variant?: 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive'
  /** Milliseconds before the copied or failed state returns to idle. 0 keeps it until the next copy. */
  resetAfter?: number
  /** Required accessible names and announcements. */
  messages: CopyButtonMessages
}


// packages/frameworks/vue/dist/vue/primitives/copy-button/index.d.ts
/** Application-owned copy for the accessible name and the polite announcement. */
export interface CopyButtonMessages {
    /** Name while idle, for example "Copy link". */
    copy: string;
    /** Name and announcement after a successful copy. */
    copied: string;
    /** Name and announcement when the browser refused the copy. */
    failed: string;
}
export type CopyStatus = 'idle' | 'copied' | 'failed';
export interface CopyButtonBehaviorOptions {
    value: () => string;
    resetAfter: () => number;
    messages: () => CopyButtonMessages;
    onCopy: (value: string) => void;
    onError: (error: unknown) => void;
}
/** Copy text with the async clipboard API, then a hidden-textarea fallback. Rejects on failure. */
export declare function copyText(value: string): Promise<void>;
/** Copy state, accessible name, announcement, and reset timer for CopyButton. */
export declare function useCopyButton(options: CopyButtonBehaviorOptions): {
    status: import("vue").Ref<CopyStatus, CopyStatus>;
    label: import("vue").ComputedRef<string>;
    announcement: import("vue").Ref<string, string>;
    copy: () => Promise<void>;
    reset: () => void;
};

Implementation notes

  • Copy uses the async clipboard API first and a hidden textarea fallback, so it works on non-secure pages and in older browsers.
  • The result returns to idle after resetAfter milliseconds; 0 keeps it until the next copy.
  • Replace the glyphs through the #icon slot, which receives the current status.

Accessibility and localization

  • messages is required: copy, copied, and failed are the icon-only accessible names and the polite announcements. Pass translated strings.
  • A text label stays the accessible name so it never changes under the user; the result is announced through a visually hidden status region.
  • The crossfade between icons stops under reduced motion.

Source contract and editing guidance