Copy - National Design System

A clipboard utility that turns any button into a one-click copy control with checkmark feedback, visible label swap, and screen reader announcement

Literal Value

Set data-copy on a .nds-copy to copy the exact string. Use this for phone numbers, emails, tokens, codes, or any value already known at render time.

Contact Information
Phone
9200343222
Email
help@company.sa
API Token
sk-prod-9f3a8c2e

Copy From Target

Set data-copy-target to a CSS selector. The button copies the target element's text content at click time, which is useful when the value is rendered dynamically or sits inside a styled wrapper.

Reference ID Block

Application reference

REF-2026-04-19-7A3F

Code Block

Place a .nds-copy inside an nds-code wrapper and the button copies the nested code automatically. No data-copy needed.

Implicit Code Resolution
npm install @nds/core --save

Label and Message

Add data-label to swap the visible button text during the success window, and data-message to set the screen reader announcement. Both restore automatically after 2 seconds.

Visible Label Swap

Built-in Features

Auto-initialization

Every .nds-copy on the page is wired up automatically. No setup, no per-button event listeners to manage.

Three-Tier Text Resolution

The button copies its data-copy literal, the text of its data-copy-target selector, or the nested <code> when placed inside an .nds-code block.

Visible Success Feedback

The icon flips to a checkmark and the optional data-label text swaps in for two seconds, then everything restores.

Screen Reader Announcement

A shared aria-live region announces data-message on every successful copy so assistive tech users get the same confirmation as sighted users.

Insecure-Context Fallback

When the modern Clipboard API is unavailable (HTTP, older browsers, sandboxed iframes), the utility falls back to a temporary textarea + execCommand so copy still works in development.

Programmatic Control

Call NDS.Copy.writeText, NDS.Copy.flash, or NDS.Copy.copyFrom from your own JS to integrate copy into custom flows.

Usage Guidelines

Best Practices

  • Use literal copy (data-copy) for values you already know at render time: phone numbers, emails, reference IDs, API tokens, emergency numbers
  • Use copy from target (data-copy-target) when the value lives inside another element you have already styled, so you don't have to duplicate the string into an attribute
  • Place a copy button inside an nds-code wrapper for any code snippet developers may want to run locally. The button copies the raw code automatically
  • Always set a meaningful aria-label that names what is being copied ("Copy phone number", "Copy reference ID"). Generic labels like "Copy" leave screen reader users without context
  • Use data-label when the button has visible text and the text swap reinforces the action ("Copy link" → "Link copied!"). Skip it for icon-only buttons where the checkmark already conveys success
  • Use data-message to spell out what was copied for assistive tech ("Page link copied to clipboard" reads better than "Copied"). It defaults to data-label, then to "Copied", so omit it only when the button label already makes the action unambiguous
  • For copy buttons inside a Dropmenu item, add data-no-auto-close so the dropmenu stays open during the two second flash, otherwise the user never sees the success feedback
  • Do not stack a copy button next to every list item if the list is long. The control becomes visual noise. Surface copy on the items that are actually useful to copy (codes, identifiers, contact info)
  • For dynamic values that change after page load, prefer data-copy-target over data-copy. The target's text content is read at click time, so the latest value is copied

Data Attributes

AttributeDescription
data-copyLiteral string the button copies. Highest priority in the resolver.
data-copy-targetCSS selector. The button copies the target element's textContent, trimmed. Used only when data-copy is absent.
data-labelText that replaces the button's .nds-label during the success flash. Restored automatically after the flash window.
data-messageMessage announced through the shared aria-live region. Falls back to data-label, then to "Copied".

JavaScript API

The NDS.Copy API powers every .nds-copy on the page and is also callable directly from your own scripts when you need to compose copy into a larger flow (for example, copying a dynamically computed URL after a network request).

// ── Write text to the clipboard ────────────────────── // Returns a Promise that resolves to true on success. // Tries navigator.clipboard first, falls back to a // temporary textarea + execCommand for HTTP / older browsers. const ok = await NDS.Copy.writeText('hello world'); // ── Trigger the success flash on a button ──────────── // Sets data-status="success", swaps the icon to a // checkmark, swaps .nds-label to data-label, and // announces data-message via aria-live. Restores // after `duration` ms (default 2000). NDS.Copy.flash(buttonEl, { duration: 2000, // Flash window in ms onRestore: () => closePopover() // Optional callback after restore }); // ── One-shot: resolve text + write + flash ─────────── // Reads data-copy / data-copy-target / nested code, writes // it, and flashes the button on success. await NDS.Copy.copyFrom(buttonEl); // ── Bind a custom selector ─────────────────────────── // Safe to call repeatedly; each call replaces the // previous listener for that selector via AbortController. NDS.Copy.bind('.my-custom-copy-btn', { duration: 1500 }); // ── Re-initialize after dynamic HTML ───────────────── // Auto-binds '.nds-copy' for the page. The NDS loader // calls this once on initial load. NDS.Copy.init();
Was this page useful?
60% of users said Yes from 2843 Feedbacks