# useCopy

Copy text and report what actually happened. "copied" only after the clipboard write resolves; a refused write reports "failed" (Candor's honest copy control: no success signal without a settled outcome).

- Registry name: `use-copy` (`@candor/use-copy`)
- Tier: Free (MIT). No licence key needed.
- Docs: https://candor.themethodic.com/docs/use-copy

## Install

```bash
npx candor-ui add use-copy
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/use-copy`.

## Example

```tsx
"use client"

import { Check, Copy } from "lucide-react"
import { Button } from "@/components/ui/button"
import { useCopy } from "@/lib/use-copy"

export default function Example() {
  const { state, copy } = useCopy()
  return (
    <Button variant="outline" size="sm" onClick={() => copy("req_01JC8Z4M2V7Q")}>
      {state === "copied" ? <Check /> : <Copy />} {state === "copied" ? "Copied" : state === "failed" ? "Couldn’t copy" : "Copy the request id"}
    </Button>
  )
}
```

## Functions

### useCopy

```ts
useCopy(resetAfter = 1600)
```

Copy text and report what actually happened. "copied" only after the clipboard write resolves; a refused write reports "failed" (Candor's honest copy control: no success signal without a settled outcome).

## Types

### CopyState

```ts
"idle" | "copying" | "copied" | "failed"
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.