Skip to main content

useClipboard

Copy text to the clipboard and get a temporary copied flag for "Copied!" feedback. Failures are captured as state instead of thrown.

When to use it​

  • "Copy" buttons for code snippets, links, tokens and IDs.
  • Showing confirmation, or an error message, after a copy attempt.

Demo​

Click Copy, then open the Console tab to see the onCopy callback in the second example. The second example never auto-resets: copied clears when you edit the text.

Loading demo…

Signature​

interface UseClipboardOptions {
timeout?: number | null;
onCopy?: (text: string) => void;
onError?: (error: Error) => void;
}

interface UseClipboardReturn {
copy: (text: string) => Promise<boolean>;
copied: boolean;
error: Error | null;
reset: () => void;
}

function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;
OptionTypeDescription
timeoutnumber | nullMilliseconds copied stays true. null disables the reset. Defaults to 2000.
onCopy(text: string) => voidCalled with the text after a successful copy.
onError(error: Error) => voidCalled with the error when a copy fails.

Returns:

PropertyTypeDescription
copy(text: string) => Promise<boolean>Copies the text. Resolves true on success, false on failure. Never rejects.
copiedbooleantrue after a successful copy until timeout elapses or reset.
errorError | nullThe last failure, cleared by the next copy or reset.
reset() => voidClears copied and error and cancels the pending timeout.

Usage notes​

  • Uses navigator.clipboard.writeText, which needs a secure context (HTTPS or localhost). Most browsers also require a user gesture, so call copy from an event handler such as onClick.
  • Safari requires the write to start inside the user-gesture handler. Call copy synchronously from the handler, not after an await.
  • If your app is embedded in a cross-origin iframe, the embedding page must allow it with <iframe allow="clipboard-write">.
  • A Permissions-Policy: clipboard-write=() header on your site blocks writes. Allow it with clipboard-write=(self).
  • If the Clipboard API is missing (old browser, insecure context, server rendering) or the write is rejected (for example permission denied), copy resolves false and error is set. There is no execCommand fallback.
  • Calling copy again restarts the timeout. If several copies overlap, only the latest one updates copied and error.
  • onCopy and onError always use their latest version, so inline callbacks are safe. copy and reset keep a stable identity.
  • The timeout is cleared on unmount and no state is updated afterwards.
  • Safe to call during server rendering: nothing touches navigator until copy runs.

Example​

const { copy, copied, error } = useClipboard({ timeout: 1500 });

return (
<>
<button onClick={() => copy(shareUrl)}>
{copied ? "Copied!" : "Share"}
</button>
{error && <span role="alert">Could not copy</span>}
</>
);

Hook source​

View useClipboard source

use-clipboard.ts
import { useCallback, useEffect, useRef, useState } from "react";

import { useLatest } from "./use-latest";

/** Options for {@link useClipboard}. */
export interface UseClipboardOptions {
/**
* How long, in milliseconds, `copied` stays `true` after a successful copy.
* Pass `null` to keep it `true` until `reset` is called or the next copy.
* Default is `2000`.
*/
timeout?: number | null;
/** Called with the copied text after a successful copy. */
onCopy?: (text: string) => void;
/** Called with the error when a copy fails. */
onError?: (error: Error) => void;
}

/** Value returned by {@link useClipboard}. */
export interface UseClipboardReturn {
/** Copies `text` to the clipboard. Resolves `true` on success and never rejects. */
copy: (text: string) => Promise<boolean>;
/** `true` after a successful copy, until `timeout` elapses or `reset` is called. */
copied: boolean;
/** The error from the last failed copy, or `null`. Cleared by the next copy or `reset`. */
error: Error | null;
/** Clears `copied` and `error` and cancels any pending timeout. */
reset: () => void;
}

const toError = (value: unknown): Error =>
value instanceof Error ? value : new Error(String(value));

/**
* Copies text to the clipboard with the async Clipboard API and exposes a
* temporary `copied` flag, handy for "Copied!" feedback.
*
* `copy` never rejects: it resolves `true` on success and `false` on failure,
* and stores the failure in `error`. Failure covers an unavailable Clipboard
* API (unsupported browser, insecure context, or server rendering) and a
* rejected write (for example a denied permission). A newer `copy` call
* supersedes an older one that is still pending. The timeout is cleared on
* unmount, and no state is updated after unmount.
*
* The Clipboard API requires a secure context (HTTPS or localhost), and most
* browsers only allow writes from a user gesture such as a click.
*
* @param options - Optional {@link UseClipboardOptions | behavior} settings.
* @returns The `copy` function, the `copied` and `error` state, and `reset`.
*
* @example
* ```tsx
* const { copy, copied } = useClipboard();
*
* return (
* <button onClick={() => copy("npm i @altalyst/hookify")}>
* {copied ? "Copied!" : "Copy"}
* </button>
* );
* ```
*
* @example
* ```tsx
* // Custom timeout and callbacks
* const { copy, error } = useClipboard({
* timeout: 1000,
* onCopy: (text) => analytics.track("copy", { length: text.length }),
* onError: (err) => toast.error(err.message),
* });
* ```
*
* For a live, editable example, see the [useClipboard docs page](https://altalyst-solutions.github.io/hookify/hooks/use-clipboard).
*/
export const useClipboard = (
options?: UseClipboardOptions
): UseClipboardReturn => {
const [copied, setCopied] = useState(false);
const [error, setError] = useState<Error | null>(null);

const optionsRef = useLatest(options);
const timerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
const callIdRef = useRef(0);
const mountedRef = useRef(false);

const clearTimer = useCallback(() => {
clearTimeout(timerRef.current);
timerRef.current = undefined;
}, []);

useEffect(() => {
mountedRef.current = true;
return () => {
mountedRef.current = false;
clearTimer();
};
}, [clearTimer]);

const reset = useCallback(() => {
callIdRef.current++;
clearTimer();
setCopied(false);
setError(null);
}, [clearTimer]);

const copy = useCallback(
async (text: string): Promise<boolean> => {
const id = ++callIdRef.current;
clearTimer();

try {
if (typeof navigator === "undefined" || !navigator.clipboard) {
throw new Error("Clipboard API is not available");
}
await navigator.clipboard.writeText(text);
} catch (err) {
const failure = toError(err);
if (mountedRef.current && id === callIdRef.current) {
setCopied(false);
setError(failure);
}
optionsRef.current?.onError?.(failure);
return false;
}

if (mountedRef.current && id === callIdRef.current) {
setError(null);
setCopied(true);
const timeout =
optionsRef.current?.timeout === undefined
? 2000
: optionsRef.current.timeout;
if (timeout !== null) {
timerRef.current = setTimeout(() => {
timerRef.current = undefined;
setCopied(false);
}, timeout);
}
}
optionsRef.current?.onCopy?.(text);
return true;
},
[clearTimer, optionsRef]
);

return { copy, copied, error, reset };
};