useClipboard@astryxdesign/core v0.7.17 · useClipboard

Usage

Copy-to-clipboard behavior: the clipboard write, a transient isCopied flag with its own reset timer, and an optional polite screen-reader announcement. Extracted so every copy affordance is a thin control over one implementation instead of re-deriving the timer and announcement. Rapid re-copies restart the reset timer so the confirmation always lasts the full duration, and the timer is cleaned up on unmount. It also copies inside a sandboxed frame that refuses the async Clipboard API, with the browser copy command, inside the reader’s click or key press. CodeBlock and Timestamp build their built-in copy buttons on it; reach for it directly when building a copy affordance that is not a plain icon button (a menu item, a labeled text button, a copy-on-click value chip).

ts
import {useClipboard} from '@astryxdesign/core/hooks'

Best practices

GuidancePractices
Do

Drive the copied confirmation (copy → check icon, label swap) off the returned isCopied flag rather than tracking your own state.

Do

Pass a localized announce message so the copy is spoken by screen readers; swapping the button aria-label alone is not reliably announced.

Do

For the common compact icon copy button, render a ghost IconButton with a "Copy" tooltip and wire onClick to copy(); the tooltip stays "Copy" and the icon flip is the confirmation.

Don't

Track a separate copied useState alongside the hook; isCopied already reflects the copied window and resets itself.

Parameters

ParamTypeDescription
options

Configuration object.

options.announce
string

Message announced to a polite live region on a successful copy. A swapped aria-label alone is not reliably announced, so pass the localized confirmation (e.g. "Copied") to have it spoken. Omit to skip the announcement.

options.resetAfterMs
number (default: 2000)

Milliseconds isCopied stays true after a successful copy before reverting.

Returns

FieldTypeDescription
copy(text: string) => Promise<boolean>

Writes text to the clipboard. On success flips isCopied to true, announces the configured message, restarts the reset timer, and resolves true. Where the frame refuses the async Clipboard API (a sandboxed viewer or an embed whose permissions policy does not allow clipboard-write), the text is copied with the browser copy command instead, inside the reader’s click or key press; it resolves true only when the browser copied the text. A failed write is a silent no-op that leaves the copied state unchanged and resolves false.

isCopiedboolean

True for resetAfterMs after the most recent successful copy, then reverts. Drive the copied confirmation (e.g. a copy → check icon flip) off this.

Examples

Common configurations, variations, and states.
useClipboard — Share Link
Open in Playground

A share card that copies its invite link with useClipboard: the Copy button reads "Copied" while isCopied is true, a screen reader hears "Link copied", and a second press restarts the reset timer.

Use with shadcn

Already using the shadcn registry workflow? Install the real Astryx package and a local public re-export. Component implementation source stays in Astryx.

This install URL expires with the draft preview.
bash
npx shadcn@4.19.0 add https://astryx-64vrqe5a4-fbopensource.vercel.app/shadcn/hooks/use-clipboard.json