Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

QRCode

The QRCode component displays a scannable QR code representing data such as URLs or text. Use QRCode to let customers quickly access information by scanning with a smartphone or other device.

QR codes support optional logo overlays for branding and can scale to fill their parent container. Always provide an alternative way for customers to access the encoded content.

Support
Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the QRCode component.

Anchor to accessibilityLabel
accessibilityLabel
string
Default: 'QR code' (translated to the user’s locale)

A label that describes the purpose or contents of the QR code. When set, it will be announced to users using assistive technologies and will provide them with more context.

Anchor to border
border
'base' | 'none'
Default: 'base'

The border style around the QR code.

  • base: A standard border that visually frames the QR code.
  • none: No border is rendered.
Anchor to content
content
string

The data to encode in the QR code. Accepts any string, such as a URL, email address, or plain text. Specific string formats can trigger actions on the user’s device when scanned, like opening geolocation coordinates on a map, launching an app, preparing an email, or composing a text message.

Anchor to id
id
string

A unique identifier for the component. Use this to target the component in scripts or stylesheets, or to distinguish it from other instances of the same component.

string

The URL of an image to display in the center of the QR code. Use this for branding or to indicate what scanning the QR code will do. By default, no image is displayed.

Anchor to onError
onError
() => void

A callback that fires when the conversion of content to a QR code fails. When an error occurs, the QR code and its child elements are not displayed. Use this to show a fallback or error state.

Anchor to size
size
'auto' | 'fill'
Default: 'auto'

The displayed size of the QR code.

  • auto: The QR code is displayed at its default size.
  • fill: The QR code takes up 100% of the available inline size and maintains a 1:1 aspect ratio.

Anchor to ExamplesExamples

Anchor to Display a QR codeDisplay a QR code

Render a scannable QR code from a URL. This example encodes a link that customers can scan with their smartphone to visit the destination.

Display a QR code

A scannable QR code linking to a URL.

Display a QR code

import {
reactExtension,
Link,
QRCode,
TextBlock,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return (
<>
<QRCode content="https://shopify.com" />

<TextBlock>
Scan to visit{' '}
<Link to="https://shopify.com">
Shopify.com
</Link>
</TextBlock>
</>
);
}
import {
extension,
Link,
QRCode,
TextBlock,
} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const qrCode = root.createComponent(QRCode, {
content: 'https://shopify.com',
});

const textBlock = root.createComponent(TextBlock, null, [
'Scan to visit ',
root.createComponent(Link, {to: 'https://shopify.com'}, 'Shopify.com'),
]);

root.appendChild(qrCode);
root.appendChild(textBlock);
});

Anchor to Add a logo overlayAdd a logo overlay

Include a branded logo in the center of the QR code for recognition and trust. This example uses the logo property to overlay an image on the code.

Add a logo overlay

import {
reactExtension,
Link,
QRCode,
TextBlock,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
return (
<>
<QRCode
content="https://shopify.com"
logo="https://cdn.shopify.com/YOUR_IMAGE_HERE"
/>

<TextBlock>
Scan to visit{' '}
<Link to="https://shopify.com">
Shopify.com
</Link>
</TextBlock>
</>
);
}
import {
extension,
QRCode,
TextBlock,
Link,
} from '@shopify/ui-extensions/checkout';

export default extension(
'purchase.checkout.block.render',
(root) => {
const qrCode = root.createComponent(QRCode, {
content: 'https://shopify.com',
logo: 'https://cdn.shopify.com/YOUR_IMAGE_HERE',
});

const textBlock = root.createComponent(
TextBlock,
null,
[
'Scan to visit ',
root.createComponent(
Link,
{to: 'https://shopify.com'},
'Shopify.com',
),
],
);

root.appendChild(qrCode);
root.appendChild(textBlock);
},
);

Anchor to Fill a containerFill a container

Scale the QR code to fill its parent container. This example sets size="fill" so the code expands to match the available width.

Fill a container

import {
reactExtension,
QRCode,
View,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
return (
<View maxInlineSize={300}>
<QRCode
content="https://shopify.com"
size="fill"
/>
</View>
);
}
import {
extension,
View,
QRCode,
} from '@shopify/ui-extensions/checkout';

export default extension(
'purchase.checkout.block.render',
(root) => {
const view = root.createComponent(View, {
maxInlineSize: 300,
});

const qrCode = root.createComponent(QRCode, {
content: 'https://shopify.com',
size: 'fill',
});

view.appendChild(qrCode);
root.appendChild(view);
},
);

Anchor to Provide a text alternativeProvide a text alternative

Pair the QR code with a clipboard button so all customers can access the content. This example adds a copy button below the code for customers who can't scan.

Provide a text alternative

import {
reactExtension,
BlockStack,
Button,
ClipboardItem,
QRCode,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
const bitcoinAddress =
'14qViLJfdGaP4EeHnDyJbEGQysnCpwk3gd';

return (
<BlockStack maxInlineSize={200}>
<QRCode
size="fill"
content={`bitcoin:${bitcoinAddress}`}
/>
<Button activateTarget="bitcoin-address">
Copy Bitcoin address
</Button>
<ClipboardItem
text={bitcoinAddress}
id="bitcoin-address"
/>
</BlockStack>
);
}
import {
extension,
BlockStack,
Button,
ClipboardItem,
QRCode,
} from '@shopify/ui-extensions/checkout';

export default extension(
'purchase.checkout.block.render',
(root) => {
const bitcoinAddress =
'14qViLJfdGaP4EeHnDyJbEGQysnCpwk3gd';
const qrCodeContent = `bitcoin:${bitcoinAddress}`;

const qrCode = root.createComponent(QRCode, {
content: qrCodeContent,
size: 'fill',
});

const clipboardItem = root.createComponent(
ClipboardItem,
{
text: bitcoinAddress,
id: 'bitcoin-address',
},
);

const button = root.createComponent(
Button,
{
activateTarget: 'bitcoin-address',
},
'Copy Bitcoin address',
);

const blockStack = root.createComponent(
BlockStack,
{
maxInlineSize: 200,
},
);

blockStack.appendChild(qrCode);
blockStack.appendChild(button);
blockStack.appendChild(clipboardItem);

root.appendChild(blockStack);
},
);

Anchor to Best practicesBest practices

  • Always test that the QR code scans correctly: Verify the code scans from a smartphone before publishing. Test at different sizes and screen brightness levels.
  • Use a square logo when customers expect one: Adding a logo increases brand trust and sets expectations for the action when scanning.
  • Add a text description of what the QR code does: Include a brief label or heading near the QR code so customers know what they'll get after scanning.
  • Provide an alternative way to access the content: Not all customers can scan QR codes. For URLs, add a Link nearby. For data, add a Button to copy to clipboard.

Anchor to LimitationsLimitations

  • The QR code renders at a fixed square aspect ratio. Non-square containers cause the code to scale proportionally rather than stretch.
  • Logo overlays reduce the scannable area of the QR code. Large logos might make the code harder to scan, especially at smaller sizes.
  • The component encodes data as a standard QR code. Other barcode formats (for example, Code 128 or EAN-13) aren't supported.
Was this page helpful?