Skip to content

QR Code

Jump to bottom
Radoslav Karaivanov edited this page Aug 5, 2026 · 1 revision

QR Code component specification

Owned by

Team name: TBD

Developer name: Radoslav Karaivanov

Designer name: TBD

Requires approval from:

TBD

Signed off by:

TBD

Revision history

# Author Date Description
1 Radoslav Karaivanov 2026-08-05 Initial draft

Overview

The igc-qr-code component renders a scannable QR (Quick Response) code as an inline SVG, generated entirely on the client from a string value. It implements the QR code model (data encoding, error correction, and matrix/module placement) internally, with no dependency on external QR-generation libraries or network requests.

The component supports optional visual customization - module (dot) and finder-pattern corner shapes, colors via CSS custom properties, and an optional center logo/image that is safely masked out of the code while respecting the chosen error correction level - making it suitable for scenarios such as:

  • Payment and ticketing: encoding URLs, IDs, or payment references for scanning with a mobile device
  • Marketing collateral: branded QR codes with a logo linking to a website or campaign
  • Authentication flows: encoding one-time setup URLs or tokens (e.g., Wi-Fi credentials, TOTP secrets)
  • Contact sharing: encoding vCard or contact information for quick import
  • Physical/digital bridging: linking printed materials or products to digital content

Key Features

  • Automatic encoding: Automatically selects the most compact QR encoding mode (numeric, alphanumeric, or byte) and the smallest QR version that fits the provided value, unless an explicit version is supplied
  • Configurable error correction: Choose between L, M, Q, and H error correction levels, trading data capacity for resilience against damage or obstruction
  • Center logo support: Optionally overlay a logo image at the center of the code; the component automatically masks the underlying modules and, when error-level is not explicitly set, escalates to the smallest error correction level that keeps the code scannable at the requested logo size
  • Visual customization: Independently style the data modules (dots) and the finder-pattern corners as square, circle, or rounded
  • Themeable colors: Control background, module, and corner colors via CSS custom properties, with shadow parts exposed for the background, dots, and each corner element
  • Configurable size and margin: Control the rendered pixel size and the quiet-zone margin (expressed in QR modules) independently
  • Safe by default: Validates logo source URLs, rejecting unsafe schemes (e.g. javascript:, vbscript:) and non-image data: URIs
  • Accessible: Renders an SVG <title> for screen readers, derived from value or an explicit aria-label, and passes accessibility audits out of the box

Acceptance criteria

  • The component must render an SVG QR code representation whenever a non-empty value is set, and render nothing when value is unset.
  • The component must automatically choose an encoding mode and QR version capable of encoding the provided value, unless a specific version is set, in which case an error should not be thrown for valid inputs that fit within that version's capacity.
  • The error-level property must control the error correction level used to generate the QR matrix, affecting both resilience and the resulting QR code size/density.
  • The size and margin properties must control the rendered pixel dimensions and quiet zone respectively, without affecting the encoded data.
  • When logo-src is set to a valid, loadable image, the component must render the image centered over the code and mask out the modules beneath it, while keeping the code scannable at the resolved error correction level.
  • The component must reject unsafe logo-src values (e.g. javascript:, vbscript:, non-image data: URIs) and must gracefully recover if a previously failed logo image is replaced with a valid one.
  • The dot-style and square-style properties must independently control the rendered shape of the data modules and the finder-pattern corners.
  • Colors must be fully customizable via the documented CSS custom properties, and must not automatically invert based on light/dark theme selection.
  • The element must be integrated and themeable with the theming mechanism of the library.
  • The element must be WAI-ARIA compliant and pass accessibility audits.
  • The component must handle edge cases gracefully (empty/undefined value, broken logo images, degenerate logo sizes, unsafe URLs).

User stories

End-user stories

As an end-user, I expect to be able to:

  • see a QR code rendered on the page that I can scan with a mobile device's camera or a QR scanning app.
  • see a QR code that still scans correctly even when a logo is present at its center.
  • have the QR code's purpose be announced by my screen reader (e.g. "QR code: <value>" or a custom label) if I cannot see the visual code.

Developer stories

As a developer, I expect to be able to:

  • set the value to be encoded as a QR code, without having to manage any QR-generation logic myself.
  • control the error correction level to balance data capacity against resilience to damage/obstruction.
  • optionally pin a specific QR version when I need a predictable code size/density.
  • control the rendered pixel size and the quiet-zone margin.
  • add a center logo image via logo-src, and control how much of the code it may cover via logo-size, and its surrounding whitespace via logo-margin.
  • rely on the component to automatically pick a safe error correction level for the requested logo size when I have not explicitly set one.
  • style the data modules and finder-pattern corners independently via dot-style and square-style.
  • theme the QR code's colors via CSS custom properties, and target its internal elements via shadow parts for advanced styling.
  • provide a custom aria-label to control what is announced to assistive technology.

Functionality

End-user experience

The igc-qr-code component presents users with a static, scannable QR code:

Visual Structure

  • A square SVG graphic containing the QR code's finder-pattern corners (three square markers in the top-left, top-right, and bottom-left) and the data modules that encode the value.
  • An optional logo image centered within the code, with the underlying modules masked out so the logo does not interfere with scanning.
  • A quiet-zone margin surrounding the code, as required for reliable scanning by QR readers.

There is no direct end-user interaction with the component; its content is driven entirely by properties set by the hosting application. When the encoded value or any visual property changes, the rendered SVG updates immediately to reflect the new state.

Accessibility Experience

  • Screen readers announce the presence and purpose of the QR code via an SVG <title> element, using either the value or a developer-supplied aria-label.

Developer experience

The igc-qr-code component is designed for ease of integration with a declarative API and sensible defaults, requiring only a value to render a working QR code.

Basic initialization

The simplest QR code requires only a value:

<igc-qr-code value="https://www.infragistics.com"></igc-qr-code>

By default, this creates a 128×128px QR code with a 4-module margin, M error correction, and square modules/corners.

Configuring size, margin, and error correction

<igc-qr-code
  value="https://www.infragistics.com"
  size="256"
  margin="2"
  error-level="H"
></igc-qr-code>

Pinning a specific QR version

<!-- Forces a fixed-size QR code regardless of value length, as long as it fits -->
<igc-qr-code value="12345" version="4"></igc-qr-code>

Adding a center logo

<igc-qr-code
  value="https://www.infragistics.com"
  logo-src="/assets/logo.png"
  logo-size="0.5"
  logo-margin="4"
></igc-qr-code>

When error-level is not explicitly set, the component automatically escalates to the smallest error correction level that keeps the code scannable at the requested logo-size.

Customizing module and corner shapes

<igc-qr-code
  value="https://www.infragistics.com"
  dot-style="rounded"
  square-style="circle"
></igc-qr-code>

Theming colors

<igc-qr-code
  value="https://www.infragistics.com"
  style="
    --ig-qr-code-background: #e8f4ff;
    --ig-qr-code-dark-color: #0066cc;
    --ig-qr-code-corner-square-color: #003366;
  "
></igc-qr-code>

Programmatic control

const qrCode = document.querySelector('igc-qr-code');

// Update the encoded value at runtime
qrCode.value = 'https://www.infragistics.com/products';

// Adjust visual properties
qrCode.dotStyle = 'rounded';
qrCode.size = 320;

// Provide a custom accessible label
qrCode.ariaLabel = 'Scan to visit our product page';

Localization

The QR code component does not contain any visible text content that requires localization. Developers can provide a localized aria-label attribute to control the accessible name announced to assistive technology.

Keyboard interactions

Not applicable. The igc-qr-code component is a non-interactive, presentational element and does not participate in the tab order or respond to keyboard input.

API

Properties and attributes

Name Attribute Type Default value Description
value value string undefined The value to be encoded in the QR code.
version version number undefined The QR version (1-40) to generate. When not set, the smallest version that fits value is chosen automatically.
errorLevel error-level 'L' | 'M' | 'Q' | 'H' 'M' The error correction level used when generating the QR code.
size size number 128 The rendered width/height of the QR code, in pixels.
margin margin number 4 The quiet-zone margin around the QR code, expressed in QR modules.
logoSrc logo-src string undefined The source URL of an optional logo image rendered at the center of the QR code.
logoSize logo-size number 0.4 The size of the logo, as a ratio (0-1) of the maximum area that can safely be obscured while remaining scannable.
logoMargin logo-margin number undefined The margin around the logo, in pixels.
dotStyle dot-style 'square' | 'circle' | 'rounded' 'square' The shape of the data modules (dots) and the inner finder-pattern corner dot.
squareStyle square-style 'square' | 'circle' | 'rounded' 'square' The shape of the outer finder-pattern corner squares.

Methods

None.

Events

None. The component is a static, presentational element and does not dispatch custom events.

Slots

None. The component does not accept slotted content; the QR code is rendered entirely as an internal SVG based on the configured properties.

CSS Custom Properties

Name Description Default
--ig-qr-code-background The background color of the QR code. white
--ig-qr-code-dark-color The color of the data modules, and the corner square/dot colors unless overridden. black
--ig-qr-code-corner-square-color The color of the outer finder-pattern corner squares. Defaults to --ig-qr-code-dark-color. -
--ig-qr-code-corner-dot-color The color of the inner finder-pattern corner dots. Defaults to --ig-qr-code-dark-color. -

CSS Shadow parts

Name Description
background The background rect of the QR code.
dots The data modules (dots) of the QR code.
corner-square The outer corner (finder-pattern) squares of the QR code.
corner-dot The inner corner (finder-pattern) dots of the QR code.

Test scenarios

Rendering and Initialization

  1. Default rendering
    • Component renders nothing when value is not set
    • Component renders an SVG element once value is set
    • SVG width/height attributes match the size property
    • SVG contains a background rect and at least one data path
    • SVG contains three finder-pattern corner groups
  2. Value changes
    • Setting value renders the corresponding QR code
    • Changing value re-renders the SVG content
    • Clearing value (setting to undefined) removes the SVG
  3. Default property values
    • size defaults to 128
    • margin defaults to 4
    • errorLevel defaults to 'M'
    • dotStyle defaults to 'square'
    • squareStyle defaults to 'square'
    • value defaults to undefined

Encoding and Error Correction

  1. Automatic version/encoding selection
    • The component selects the smallest QR version able to encode the given value when version is not set
    • Setting version explicitly forces that QR version, provided the value fits
  2. Error correction level
    • A higher errorLevel produces a larger/denser QR code for the same value
    • Attribute error-level correctly reflects into the errorLevel property
    • Attribute version correctly reflects into the version property (as a number)

Visual Customization

  1. Size and margin
    • Setting size updates the SVG width/height attributes
    • Changing size dynamically updates SVG dimensions
    • Setting margin adjusts the quiet-zone area without altering encoded data
  2. Dot and corner styles
    • dot-style of square, circle, and rounded each render a valid data path
    • square-style of square, circle, and rounded each render three corner groups
    • Attribute variants correctly reflect into dotStyle/squareStyle properties

Theming

  1. Shadow parts and CSS custom properties
    • background, dots, corner-square, and corner-dot parts are exposed and queryable
    • Default colors match the schema (white background, black modules/corners)
    • --ig-qr-code-background and --ig-qr-code-dark-color override the rendered colors
    • --ig-qr-code-dark-color cascades to corner-square/corner-dot colors when those are not explicitly set
    • An explicit --ig-qr-code-corner-dot-color wins over the dark-color cascade for the corner dot only
    • Colors do not automatically invert when the global theme switches to a dark variant

Logo Support

  1. Logo rendering
    • No <image>/<mask>/<defs> are rendered when logoSrc is not set
    • A valid logoSrc renders an <image> and a <mask>, applied to the group containing dots and finder patterns
    • The <image> element is rendered outside the masked group
    • The mask id remains stable across re-renders triggered by unrelated property changes
    • Clearing logoSrc removes the <image>/<mask>/<defs>
  2. Logo URL validation
    • Unsafe schemes (javascript:, vbscript:, case-insensitive) are rejected; no image is rendered
    • Non-image data: URIs (e.g. data:text/html,..., data:application/javascript,...) are rejected
    • data:image/... URIs are accepted
    • Regular https:// URLs are accepted
    • Replacing a valid logoSrc with an unsafe one removes the previously rendered <image>/<mask>
  3. Logo load errors
    • A broken/undecodable image results in no <image>/<mask> being rendered
    • The component recovers and renders the logo once logoSrc is changed to a valid image
  4. Logo sizing and margin
    • logoSize controls the rendered logo's area relative to the safe area for the resolved error correction level
    • A higher errorLevel allows for a larger rendered logo at the same logoSize
    • logoMargin reduces the visible logo dimensions relative to the cleared mask area
    • No <image> is rendered when the resolved logo box collapses to zero (e.g. logo-size="0")
  5. Automatic error correction escalation
    • When errorLevel is not explicitly set and a logo is present, the component automatically selects the smallest error correction level that accommodates the requested logoSize

Attribute Reflection

  1. Property/attribute synchronization
    • dot-style, square-style, error-level, version, logo-src, logo-size, and logo-margin attributes correctly initialize their corresponding properties

Accessibility

  1. ARIA and screen reader support
    • The component passes the accessibility audit when a value is set
    • The rendered SVG has role="img"
    • The SVG contains a <title> element for screen readers
    • The <title> content defaults to QR code: <value> when no aria-label is set
    • The <title> content uses the aria-label value when one is provided

Edge Cases

  1. Invalid/degenerate configurations
    • An empty or undefined value renders no SVG
    • Extremely small logoSize/logoMargin combinations that collapse the logo box are handled gracefully (no image rendered, no errors thrown)
    • Rapid successive property changes (value, size, logoSrc) do not leave the SVG in an inconsistent state

Accessibility

ARIA roles and properties

  • The rendered <svg> element must have role="img".
  • The rendered <svg> must contain a <title> element describing the QR code's purpose, derived from ariaLabel when set, or defaulting to QR code: <value>.

Keyboard support

Not applicable. The component renders a non-interactive, static graphic and does not receive focus.

Right to Left support

The QR code's visual structure (finder patterns and data modules) is a fixed, standardized layout defined by the QR specification and must not be mirrored in Right-to-Left contexts. No additional RTL-specific configuration is required or supported.

Clone this wiki locally