{"slug":"qr-code","title":"QR Code","description":"Using the QR code machine in your project.","contentType":"component","framework":"react","content":"QR (Quick Response) Code is used to provide information or link which can be\naccessed by scanning the code with an app or a smartphone.\n\n> **Good to know**: The QR code encoding logic is built on top of the\n> [`uqr`](https://github.com/unjs/uqr) library.\n\n## Resources\n\n\n[Latest version: v1.31.0](https://www.npmjs.com/package/@zag-js/qr-code)\n[Logic Visualizer](https://zag-visualizer.vercel.app/qr-code)\n[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/qr-code)\n\n\n\n**Features**\n\n- Renders an SVG element (good for SSR)\n- Customize the size of the QR code in pixels\n- Set the error correction level\n- Customize the background and foreground color\n\n## Installation\n\nTo use the QR code machine in your project, run the following command in your\ncommand line:\n\n```bash\nnpm install @zag-js/qr-code @zag-js/react\n# or\nyarn add @zag-js/qr-code @zag-js/react\n```\n\n## Anatomy\n\nTo set up the QR code correctly, you'll need to understand its anatomy and how\nwe name its parts.\n\n> Each part includes a `data-part` attribute to help identify them in the DOM.\n\n\n\n## Usage\n\nFirst, import the QR code package into your project\n\n```jsx\nimport * as qrCode from \"@zag-js/qr-code\"\n```\n\nThe QR code package exports two key functions:\n\n- `machine` — The state machine logic for the QR code widget.\n- `connect` — The function that translates the machine's state to JSX attributes\n  and event handlers.\n\nNext, import the required hooks and functions for your framework and use the QR\ncode machine in your project 🔥\n\n```jsx\nimport * as qrCode from \"@zag-js/qr-code\"\nimport { useMachine, normalizeProps } from \"@zag-js/react\"\nimport { useId } from \"react\"\n\nexport function QRCode() {\n  const service = useMachine(qrCode.machine, {\n    id: useId(),\n    value: \"https://github.com/chakra-ui\",\n  })\n\n  const api = qrCode.connect(service, normalizeProps)\n\n  return (\n    <div {...api.getRootProps()}>\n      <svg {...api.getFrameProps()}>\n        <path {...api.getPatternProps()} />\n      </svg>\n      <div {...api.getOverlayProps()}>\n        <img\n          src=\"https://avatars.githubusercontent.com/u/54212428?s=88&v=4\"\n          alt=\"\"\n        />\n      </div>\n    </div>\n  )\n}\n```\n\n## Setting the QR Code value\n\nTo set the value of the QR code, pass the `value` property to the machine.\n\n```jsx {3}\nconst service = useMachine(qrCode.machine, {\n  // ...\n  value: \"https://example.com\",\n})\n```\n\n### Setting the correction level\n\nError correction allows for the QR code to be blocked or resized while still\nrecognizable. In some cases where the link is too long or the logo overlay\ncovers a significant area, the error correction level can be increased.\n\nThe QR code machine accepts the following error correction levels:\n\n- `L`: Allows recovery of up to 7% data loss (default)\n- `M`: Allows recovery of up to 15% data loss\n- `Q`: Allows recovery of up to 25% data loss\n- `H`: Allows recovery of up to 30% data loss\n\nTo set the error correction level, pass the `encoding.ecc` or\n`encoding.boostEcc` context property.\n\n```jsx {3}\nconst service = useMachine(qrCode.machine, {\n  value: \"...\",\n  encoding: { ecc: \"H\" },\n})\n```\n\n> The alternative is to enlarge the QRCode by increasing the size of the `svg`\n> element.\n\n### Adding an overlay logo\n\nTo add a logo overlay to the QR code, render the image part. The logo will be\nautomatically centered within the QR code.\n\n```jsx {3}\n<div {...api.getRootProps()}>\n  <svg {...api.getFrameProps()}>{/** ... */}</svg>\n  <div {...api.getOverlayProps()}>\n    <img src=\"...\" alt=\"\" />\n  </div>\n</div>\n```\n\n### Changing the color\n\nTo change the color of the QR code, set the `fill` attribute on the `path` part.\n\n```css\n[data-scope=\"qr-code\"][data-part=\"pattern\"] {\n  fill: green;\n}\n```\n\nTo change the background color of the QR code, set the `background-color`\n\n```css\n[data-scope=\"qr-code\"][data-part=\"frame\"] {\n  background-color: white;\n}\n```\n\n### Exporting the QR code\n\nTo export the QR code as an image, you can use the `api.getDataURL` method.\n\n```ts\napi.getDataURL({ type: \"image/png\" }).then((url) => {\n  // do something with the URL (like download it)\n})\n```\n\n## Styling guide\n\nEarlier, we mentioned that each QR code part has a `data-part` attribute added\nto them to select and style them in the DOM.\n\n```css\n[data-scope=\"qr-code\"][data-part=\"root\"] {\n  /* Styles for the root part */\n}\n\n[data-scope=\"qr-code\"][data-part=\"frame\"] {\n  /* Styles for the svg part */\n}\n\n[data-scope=\"qr-code\"][data-part=\"pattern\"] {\n  /* Styles for the path */\n}\n\n[data-scope=\"qr-code\"][data-part=\"overlay\"] {\n  /* Styles for the logo */\n}\n```\n\n## Methods and Properties\n\n### Machine Context\n\nThe QR code machine exposes the following context properties:\n\n**`value`**\nType: `string`\nDescription: The controlled value to encode.\n\n**`defaultValue`**\nType: `string`\nDescription: The initial value to encode when rendered.\nUse when you don't need to control the value of the qr code.\n\n**`ids`**\nType: `Partial<{ root: string; frame: string; }>`\nDescription: The element ids.\n\n**`encoding`**\nType: `QrCodeGenerateOptions`\nDescription: The qr code encoding options.\n\n**`onValueChange`**\nType: `(details: ValueChangeDetails) => void`\nDescription: Callback fired when the value changes.\n\n**`pixelSize`**\nType: `number`\nDescription: The pixel size of the qr code.\n\n**`dir`**\nType: `\"ltr\" | \"rtl\"`\nDescription: The document's text/writing direction.\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 QR code `api` exposes the following methods:\n\n**`value`**\nType: `string`\nDescription: The value to encode.\n\n**`setValue`**\nType: `(value: string) => void`\nDescription: Set the value to encode.\n\n**`getDataUrl`**\nType: `(type: DataUrlType, quality?: number) => Promise<string>`\nDescription: Returns the data URL of the qr code.","package":"@zag-js/qr-code","editUrl":"https://github.com/chakra-ui/zag/edit/main/website/data/components/qr-code.mdx"}