{"slug":"clipboard","title":"Clipboard","description":"Using the clipboard machine in your project.","contentType":"component","framework":"react","content":"The clipboard machine lets users quickly copy content to the clipboard.\n\n## Resources\n\n\n[Latest version: v1.39.1](https://www.npmjs.com/package/@zag-js/clipboard)\n[Logic Visualizer](https://zag-visualizer.vercel.app/clipboard)\n[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/clipboard)\n\n\n\n## Installation\n\nInstall the clipboard package:\n\n```bash\nnpm install @zag-js/clipboard @zag-js/react\n# or\nyarn add @zag-js/clipboard @zag-js/react\n```\n\n## Anatomy\n\nCheck the clipboard anatomy and part names.\n\n> Each part includes a `data-part` attribute to help identify them in the DOM.\n\n\n\n## Usage\n\nImport the clipboard package:\n\n```tsx\nimport * as clipboard from \"@zag-js/clipboard\"\n```\n\nThe clipboard package exports two key functions:\n\n- `machine` - State machine logic.\n- `connect` - Maps machine state to JSX props and event handlers.\n\n> Pass a unique `id` to `useMachine` so generated element ids stay predictable.\n\nThen use the framework integration helpers:\n\n```tsx\nimport * as clipboard from \"@zag-js/clipboard\"\nimport { useMachine, normalizeProps } from \"@zag-js/react\"\nimport { ClipboardCheck, ClipboardCopyIcon } from \"lucide-react\"\nimport { useId } from \"react\"\n\nfunction Clipboard() {\n  const service = useMachine(clipboard.machine, {\n    id: useId(),\n    value: \"https://github.com/chakra-ui/zag\",\n  })\n\n  const api = clipboard.connect(service, normalizeProps)\n\n  return (\n    <div {...api.getRootProps()}>\n      <label {...api.getLabelProps()}>Copy this link</label>\n      <div {...api.getControlProps()}>\n        <input {...api.getInputProps()} />\n        <button {...api.getTriggerProps()}>\n          {api.copied ? <ClipboardCheck /> : <ClipboardCopyIcon />}\n        </button>\n      </div>\n    </div>\n  )\n}\n```\n\n### Setting the clipboard value\n\nSet `value` to control what gets copied.\n\n```tsx {2}\nconst service = useMachine(clipboard.machine, {\n  value: \"Hello, world!\",\n})\n```\n\n### Setting an initial value\n\nUse `defaultValue` for uncontrolled initial value.\n\n```tsx\nconst service = useMachine(clipboard.machine, {\n  defaultValue: \"Hello, world!\",\n})\n```\n\n### Listening for value changes\n\nUse `onValueChange` to react when the clipboard value changes.\n\n```tsx\nconst service = useMachine(clipboard.machine, {\n  onValueChange(details) {\n    console.log(\"Value changed to\", details.value)\n  },\n})\n```\n\n### Listening to copy events\n\nWhen the value is copied, `onStatusChange` is fired.\n\n```tsx {2}\nconst service = useMachine(clipboard.machine, {\n  onStatusChange: (details) => {\n    console.log(\"Copy status changed to\", details.copied)\n  },\n})\n```\n\n### Checking if the value is copied\n\nUse `api.copied` to check if the value was copied.\n\n```tsx {2}\nconst api = clipboard.connect(service)\n\nif (api.copied) {\n  console.log(\"Value is copied to the clipboard\")\n}\n```\n\n### Changing the timeout\n\nBy default, the copied feedback resets after `3000ms`. Set `timeout` to change\nthis delay.\n\n```tsx {2}\nconst service = useMachine(clipboard.machine, {\n  timeout: 5000,\n})\n```\n\n## Styling guide\n\nEach part includes a `data-part` attribute you can target in CSS.\n\n```css\n[data-scope=\"clipboard\"][data-part=\"root\"] {\n  /* styles for the root part */\n}\n```\n\n## Methods and Properties\n\n### Machine Context\n\nThe clipboard machine exposes the following context properties:\n\n**`translations`**\nType: `IntlTranslations`\nDescription: Specifies the localized strings that identifies the accessibility elements and their states\n\n**`ids`**\nType: `Partial<{ root: string; input: string; label: string; }>`\nDescription: The ids of the elements in the clipboard. Useful for composition.\n\n**`value`**\nType: `string`\nDescription: The controlled value of the clipboard\n\n**`defaultValue`**\nType: `string`\nDescription: The initial value to be copied to the clipboard when rendered.\nUse when you don't need to control the value of the clipboard.\n\n**`onValueChange`**\nType: `(details: ValueChangeDetails) => void`\nDescription: The function to be called when the value changes\n\n**`onStatusChange`**\nType: `(details: CopyStatusDetails) => void`\nDescription: The function to be called when the value is copied to the clipboard\n\n**`timeout`**\nType: `number`\nDescription: The timeout for the copy operation\n\n**`id`**\nType: `string`\nDescription: The unique identifier of the machine.\n\n**`getRootNode`**\nType: `() => ShadowRoot | Node | Document`\nDescription: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.\n\n### Machine API\n\nThe clipboard `api` exposes the following methods:\n\n**`copied`**\nType: `boolean`\nDescription: Whether the value has been copied to the clipboard\n\n**`value`**\nType: `string`\nDescription: The value to be copied to the clipboard\n\n**`setValue`**\nType: `(value: string) => void`\nDescription: Set the value to be copied to the clipboard\n\n**`copy`**\nType: `VoidFunction`\nDescription: Copy the value to the clipboard\n\n### Data Attributes\n\n**`Root`**\n\n**`data-scope`**: clipboard\n**`data-part`**: root\n**`data-copied`**: Present when copied state is true\n\n**`Label`**\n\n**`data-scope`**: clipboard\n**`data-part`**: label\n**`data-copied`**: Present when copied state is true\n\n**`Control`**\n\n**`data-scope`**: clipboard\n**`data-part`**: control\n**`data-copied`**: Present when copied state is true\n\n**`Input`**\n\n**`data-scope`**: clipboard\n**`data-part`**: input\n**`data-copied`**: Present when copied state is true\n**`data-readonly`**: Present when read-only\n\n**`Trigger`**\n\n**`data-scope`**: clipboard\n**`data-part`**: trigger\n**`data-copied`**: Present when copied state is true","package":"@zag-js/clipboard","editUrl":"https://github.com/chakra-ui/zag/edit/main/website/data/components/clipboard.mdx"}