Copy

Example

<code>inv_8f2a1c</code>
<button type="button" data-slean="button" data-variant="ghost" data-icon-only
	data-slean-copy="inv_8f2a1c" aria-label="Copy the invoice id"
	data-slean-hint="Copy" data-slean-hint-copied="Copied">
	<span data-slean-part="icon"><svg …></svg></span>
</button>

<button type="button" data-slean="button" data-variant="outline"
	data-slean-copy="yarn add @svelte-lean/primitives">
	<span data-slean-part="icon"><svg …></svg></span>
	Copy the install command
</button>

<script lang="ts">
	// With @svelte-lean/vite the register imports are injected for the data-slean-copy and
	// data-slean-hint attributes, static or dynamic.
	import '@svelte-lean/styles/button.css';
	import '@svelte-lean/styles/hint.css';
	import '@svelte-lean/styles/copy.css';

	let { id }: { id: string } = $props();
</script>

<code>{id}</code>
<button type="button" data-slean="button" data-variant="ghost" data-icon-only
	data-slean-copy={id} aria-label="Copy the invoice id"
	data-slean-hint="Copy" data-slean-hint-copied="Copied">
	<span data-slean-part="icon"><svg …></svg></span>
</button>

Why this implementation exists

A copy button is a click handler, a clipboard call and a moment of feedback. Written per button, it is a function and a timer for every id in a table. The browser owns the clipboard and the button; what it has no attribute for is the value to write and the feedback after it.

The behavior registers one click handler with the shared router for every copy element on the page. The copied state is an attribute on the element, data-slean-copied, removed by the timer of the latest copy; nothing is kept per element (tests/copy.test.ts keeps one click listener for a thousand copy elements).

Usage

Install @svelte-lean/primitives for the behavior and @svelte-lean/styles for the stylesheet. With @svelte-lean/vite the registration is injected for every data-slean-copy attribute in the markup, with a static or a dynamic value; without it, import the register module once.

npm install @svelte-lean/primitives

pnpm add @svelte-lean/primitives

yarn add @svelte-lean/primitives

bun add @svelte-lean/primitives

import '@svelte-lean/primitives/copy/register';

import '@svelte-lean/styles/copy.css';

Put data-slean-copy="<value>" on a <button type="button">: the button makes the copy reachable from the keyboard. Any other element works for the pointer only, and development validation warns about it.

Keep the value visible in the page, not only in the attribute, so it can be selected by hand where the clipboard is unavailable. With data-slean-hint and data-slean-hint-copied (the Hint primitive), a shown hint reads the copied label while the button is marked.

A click on a link, button or field inside a copy element belongs to that control; when copy elements nest, the innermost one copies its own value.

<script lang="ts">
	import type { CopyDetail } from '@svelte-lean/primitives/copy';

	let list: HTMLElement;
	let status = $state('');

	$effect(() => {
		// slean:copy bubbles from the element once the value is on the clipboard. One listener on
		// an ancestor serves every copy element inside it.
		const oncopy = (event: Event) => {
			status = `Copied ${(event as CustomEvent<CopyDetail>).detail.value}`;
		};
		list.addEventListener('slean:copy', oncopy);
		return () => list.removeEventListener('slean:copy', oncopy);
	});
</script>

<ul bind:this={list}>…</ul>
<!-- The behavior adds no ARIA; a live region announces the copy to assistive technology. -->
<p role="status">{status}</p>

Anatomy

Runtime profile

The copy registers one click handler with the shared router. A copy writes one attribute on the element and starts one timer that removes it; a second copy within the duration re-stamps the attribute, so only the latest timer clears it. No layout is read.

Accessibility contract

• The element is a native <button>: focusable, activated by Enter and Space. The behavior never moves focus.
• The behavior adds no ARIA. The success is shown visually (data-slean-copied, the check mark, the copied hint); an application that must announce it listens for slean:copy and writes to a live region.
• A disabled element (disabled, aria-disabled="true") copies nothing.
• An icon-only copy button needs its own accessible name (aria-label); the hint is supplementary.

Keyboard

Platform features

Without JavaScript

Clicking copies nothing. The value stays in the page, where it can be selected and copied by hand.

Server rendering

Render the attributes as they are. Nothing runs on the server or at import.

Before hydration

Before the behavior loads, a click copies nothing. The registration attaches no per-element state, so the first click after hydration copies.

Styling

copy.css sets the pointer cursor (not-allowed when disabled) and, while data-slean-copied is present, hides the svg inside [data-slean-part="icon"] and shows the check mark mask from --slean-icon-check in the success color. The button keeps its own look from button.css. Select on the presence of data-slean-copied; its value is an internal stamp. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: :disabled, [aria-disabled="true"].

Variant attributes: data-slean-copy; data-slean-copied.

Controlled integration

copyValue(element, value?) runs the same copy from code: it writes the value (the element’s data-slean-copy by default), marks the element, redraws its hint and dispatches slean:copy, and resolves to whether the value was written.

import { copyValue } from '@svelte-lean/primitives/copy';

// The same copy from code: marks the element, redraws its hint and dispatches slean:copy.
// Resolves to false when the clipboard is missing or refused.
const copied = await copyValue(button, link.href);

Compatibility notes

The Async Clipboard API is Baseline widely available and works in secure contexts only (https or localhost); Safari and Firefox require a user activation, which the click provides. A missing or refused clipboard sets no mark, dispatches no event and logs nothing. There is no fallback through document.execCommand('copy'), no rich clipboard content and no reading from the clipboard.

Examples

Ids in a list

Each id is the text of its own copy button, so it stays visible and selectable by hand. The status line below the list is application code: one slean:copy listener on the list writes the copied value into a role="status" region, which is how a copy reaches assistive technology.

• Amara Okafor inv_8f2a1c
• Jonas Lindqvist inv_91b40e
• Mei Tanaka inv_a3c7d2

{#each invoices as invoice (invoice.id)}
	<li>
		{invoice.customer}
		<!-- The id is the visible text, so it can be selected by hand without JavaScript. -->
		<button type="button" data-slean="button" data-variant="ghost" data-size="sm"
			data-slean-copy={invoice.id} data-slean-hint="Copy" data-slean-hint-copied="Copied">
			<code>{invoice.id}</code>
		</button>
	</li>
{/each}

Testing

• packages/primitives/tests/copy.test.ts Vitest: the value, the mark and its duration, the copied hint, nested controls, disabled, a refused clipboard, 1000 elements
• apps/playground/tests/primitives/hint.spec.ts Playwright: hint and copy in Chrome, the top layer, keyboard focus, Escape, the flip, axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

• packages/primitives/src/copy/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/copy/contract.ts typed constants: name, tier, base, parts, options, events
• packages/primitives/src/copy/behavior.ts the behavior definition and copyValue()
• packages/primitives/src/copy/register.ts the registration module
• packages/primitives/src/copy/validate.ts development validation messages
• docs/adr/0009-attribute-behaviors.md why an attribute on any element can be the root of a behavior
• packages/styles/css/copy.css the optional stylesheet