The hook returns a status string (idle, copied, error) so UI can swap a tooltip or icon without storing a separate boolean. navigator.clipboard.writeText is async and rejects when the document does not have user-activation focus, hence the try/catch. The auto-reset via setTimeout is what turns the button back from a checkmark to the copy icon a moment later. The resolved boolean lets the caller chain side effects without subscribing to the status.

Older Safari versions, embedded webviews, and some corporate browsers do not implement navigator.clipboard. The document.execCommand('copy') path with a hidden <textarea> still works there. The trick is creating an offscreen textarea, selecting its content, calling execCommand, then cleaning up. This API is officially deprecated but remains the only universally available fallback, so most production hooks layer it under the modern path with try / catch.

Sometimes you want the clipboard to carry both a plain-text version and a styled HTML version (so pasting into a rich editor preserves formatting, while pasting into a plain field still works). ClipboardItem plus navigator.clipboard.write accepts a list of items, each a map of MIME types to Blobs. The fallback to writeText(plain) handles browsers that do not yet expose ClipboardItem. Use this for code snippets with syntax highlighting, citations from a documentation page, or markdown that converts to HTML.