{"slug":"qr-code","title":"QR Code","description":"Using the QR code machine in your project.","contentType":"component","framework":"svelte","content":"A QR code encodes information or links that can be scanned with a phone or app.\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.39.1](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\nInstall the QR code package:\n\n```bash\nnpm install @zag-js/qr-code @zag-js/svelte\n# or\nyarn add @zag-js/qr-code @zag-js/svelte\n```\n\n## Anatomy\n\nCheck the QR code 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 QR code package:\n\n```tsx\nimport * as qrCode from \"@zag-js/qr-code\"\n```\n\nThese are the key exports:\n\n- `machine` - State machine logic.\n- `connect` - Maps machine state to JSX props and event handlers.\n\nThen use the framework integration helpers:\n\n```svelte\n<script lang=\"ts\">\n  import * as qrCode from \"@zag-js/qr-code\"\n  import { useMachine, normalizeProps } from \"@zag-js/svelte\"\n\n  const id = $props.id()\n  const service = useMachine(qrCode.machine, {\n    id,\n    value: \"https://github.com/chakra-ui\",\n  })\n  const api = $derived(qrCode.connect(service, normalizeProps))\n</script>\n\n<div {...api.getRootProps()}>\n  <svg {...api.getFrameProps()}>\n    <path {...api.getPatternProps()}></path>\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### Setting the QR code value\n\nSet `value` to control the encoded content.\n\n```tsx {3}\nconst service = useMachine(qrCode.machine, {\n  // ...\n  value: \"https://example.com\",\n})\n```\n\n### Setting an initial value\n\nUse `defaultValue` for an uncontrolled initial value.\n\n```tsx\nconst service = useMachine(qrCode.machine, {\n  defaultValue: \"https://example.com\",\n})\n```\n\n### Listening for value changes\n\nUse `onValueChange` to react when the encoded value changes.\n\n```tsx\nconst service = useMachine(qrCode.machine, {\n  onValueChange(details) {\n    // details => { value: string }\n    console.log(details.value)\n  },\n})\n```\n\n### Setting pixel size\n\nUse `pixelSize` to control QR code density.\n\n```tsx\nconst service = useMachine(qrCode.machine, {\n  value: \"https://example.com\",\n  pixelSize: 8,\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```tsx {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```tsx {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, use `api.getDataUrl`.\n\n```ts\napi.getDataUrl(\"image/png\").then((url) => {\n  // do something with the URL (like download it)\n})\n```\n\nYou can also use `api.getDownloadTriggerProps` to create a download button.\n\n```tsx\n<button\n  {...api.getDownloadTriggerProps({\n    mimeType: \"image/png\",\n    fileName: \"qr-code\",\n  })}\n>\n  Download QR\n</button>\n```\n\n## Styling guide\n\nEach part includes a `data-part` attribute you can target in CSS.\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"}