react-smart-copy

Context

Copy buttons appear in almost every product: API keys, IDs, email addresses, invite links, and code samples. They are usually written as a single clipboard call with a "Copied" message, and they are rewritten in every codebase.

That single call hides most of the real behavior. Browsers refuse clipboard writes outside HTTPS, block them when focus moves, support only some formats, and report failures inconsistently. The interface around the call has to explain all of that to the person who pressed the button.

Problem

Typical copy implementations fail in ways users cannot see and teams rarely test. The goal was a library that treats the copy interaction as product behavior with defined states, not as a utility function.

• Failures such as an insecure context or a denied permission often no-op silently.
• A copy takes a few milliseconds, so naive status text flashes "Copying…" for one frame and resizes the button.
• Copy buttons hidden with display: none on hover are unreachable by keyboard.
• Results are rarely announced to screen-reader users.
• Server rendering can mismatch when components read the browser clipboard during render.

Approach

The library is built in layers. A framework-agnostic core holds a copy state machine, payload validation, a browser clipboard adapter, and error classification. The React layer adds hooks and a compound CopyField component on top of that core.

Every state is explicit and observable: idle, copying, copied, and error. Two statuses separate logic from display: the real status changes instantly for tests and logic, while the display status only shows "Copying…" when a copy is slow and then holds it long enough to avoid a blink.

• Copies text, rich HTML with a required plain-text fallback, PNG images, JSON, and several formats at once.
• Pastes text, HTML, and screenshots through usePaste, with keyboard paste that needs no permission prompt.
• CopyGroup coordinates rows so only one shows "Copied" at a time.
• A capture entry point copies an SVG or a piece of UI as a PNG.
• Custom adapters let hosts such as Electron provide their own clipboard.

Accessibility decisions

Accessibility rules are part of the components rather than documentation for consumers to remember. The trigger is always a real button, and its accessible name stays stable while the result is announced separately.

• Triggers are reachable with Tab and activate with Enter or Space.
• Revealed actions stay in the DOM and the tab order; they are hidden with opacity, never display: none.
• Keyboard focus pins the reveal; a mouse click does not.
• The trigger is never disabled while copying, so keyboard focus is not lost.
• The live region is mounted before its first message, so the first announcement is not missed.
• Animations respect prefers-reduced-motion.

Errors, SSR, and footprint

Every failure is a typed, classified error such as unsupported, insecure-context, permission-denied, not-focused, unsupported-format, or too-large, and each one states whether a retry can help. Nothing fails silently.

The React entry ships with "use client" and never touches window during render, so server and first client render match in Next.js. The package has zero runtime dependencies, and the README reports about 3.2 kB for useCopy and 5.4 kB for all copy features, minified and compressed with Brotli.