API Reference Guide

Complete API reference for QRCode.js library

Basic QR Code Creation with QRCode.js

import { QRCodeJs, Options } from '@qr-platform/qr-code.js';

// Create a basic QR code
const qrCode = new QRCodeJs({
  data: 'https://example.com',
} as Options);

// Render the QR code to a container
qrCode.append(document.getElementById('qr-container'));

QRCode.js Options Table

OptionTypeDefaultDescription
datastring-Specifies the text, URL, or other data to encode into the QR code. Required option
shape'square' | 'circle''square'The overall shape of the QR code's boundary. See ShapeType enum.
marginnumber0The quiet zone (empty space) around the QR code in pixels.
isResponsivebooleanfalseWhen true, the QR code SVG resizes dynamically to fill the width or height of the parent container, with no internal size dimensions applied.
scalenumber (0 to 1.5)1Scales the QR code size relative to its container or border.
offsetnumber0Applies a vertical offset (positive moves down, negative moves up) relative to the center.
verticalOffsetnumber0Applies an absolute vertical offset in pixels.
horizontalOffsetnumber0Applies an absolute horizontal offset in pixels.
qrOptionsobject{...}Options related to the underlying QR code generation algorithm.
qrOptions.typeNumbernumber (0-40)0Specifies the QR code version (size/capacity). 0 means automatic detection.
qrOptions.modeMode enumAuto-detectedThe encoding mode (e.g., Byte, Numeric, Kanji). Usually auto-detected.
qrOptions.errorCorrectionLevel'L' | 'M' | 'Q' | 'H''Q'The error correction level, determining redundancy. See ErrorCorrectionLevel enum.
dotsOptionsobject{...}Options for styling the dots in the QR code.
dotsOptions.typeDotType enum'square'The shape of the dots. See DotType enum.
dotsOptions.colorstring'#000000'The color of the dots. Accepts any valid CSS color string (e.g., '#FF0000', 'red', 'rgba(255, 0, 0, 0.5)').
dotsOptions.sizenumber10The size of the dots in pixels.
dotsOptions.gradientGradient objectundefinedApply a gradient fill to the dots. See Gradient options for configuration details.
type'linear' | 'radial'-Specifies the type of gradient: 'linear' for a linear gradient or 'radial' for a radial gradient.
rotationnumber-The rotation angle in radians for the gradient. Only applicable when type is 'linear'.
colorStopsArray<{ offset: number, color: string }>-An array of color stops that define the gradient. Each stop must have an offset (a number between 0 and 1) and a color (a valid CSS color string). At least two color stops are recommended to create a visible gradient.
cornersSquareOptionsobject{...}Options for styling the corner squares. Overrides dotsOptions.
cornersSquareOptions.typeCornerSquareType enumInheritsThe shape of the corner squares. See CornerSquareType enum for options (e.g., square, rounded).
cornersSquareOptions.colorstringInheritsThe color of the corner squares.
cornersSquareOptions.gradientGradient objectundefinedApply a gradient fill to the corner squares.
cornersDotOptionsobject{...}Options for styling the corner dots. Overrides cornersSquareOptions.
backgroundOptionsobject | false{...}Options for styling the background. Set to false to disable.
backgroundOptions.colorstring'#FFFFFF'The background color.
backgroundOptions.roundnumber | string0Rounds the corners of the background (0-1 or percentage).
backgroundOptions.gradientGradient objectundefinedApply a gradient fill to the background. See Gradient options for configuration details.
imagestring | Buffer | BlobundefinedURL, Buffer, or Blob of an image to embed in the QR code. Can be set globally via QRCodeJs.setImage() or per-instance via QRCodeJs.useImage() or direct options.
imageOptionsobject{...}Options for the embedded image.
imageOptions.modeImageMode enum'center'How the image is embedded. See ImageMode enum.
imageOptions.imageSizenumber0.4Relative size of the image (0-1).
imageOptions.marginnumber0Margin around the image in dot units.
imageOptions.crossOriginstringundefinedCORS setting for the image.
imageOptions.fillobject{...}Fill color or gradient.
imageOptions.fill.colorstring'rgba(255,255,255,1)'Fill color.
imageOptions.fill.gradientGradient objectundefinedApply a gradient fill to the QR code. See Gradient options for configuration details.
borderOptionsBorderOptions objectundefinedOptions for adding decorative borders. Can be configured globally via QRCodeJs.setBorder()/setBorderId() or per-instance via the builder pattern (useBorder()/useBorderId()). See below for sub-options.

Gradient options

Note: If both color and gradient are specified, the gradient property takes precedence, allowing you to create dynamic linear or radial gradient effects.

OptionTypeDefaultDescription
cornersDotOptions.typeCornerDotType enumInheritsSpecifies the shape of the corner dots. Refer to the CornerDotType enum for available options (e.g., square, rounded).
cornersDotOptions.colorstringInheritsDefines the solid color of the corner dots. Accepts any valid CSS color string (e.g., '#FF0000', 'red', 'rgba(255, 0, 0, 0.5)').
cornersDotOptions.gradientGradient objectundefinedApplies a gradient fill to the corner dots, overriding the color property if both are set. See Gradient Sub-options for configuration details.

Additional Notes

  • The data option is the only required option for generating a QR code.

QRCode.js Methods Table

MethodParametersDescription
appendcontainer: HTMLElement, options?: { clearContainer?: boolean }Appends the QR code to a container element. Returns QRCodeJs | undefined.
serializeinverted?: booleanConverts the QR code to an SVG string. Returns Promise<string | undefined>.
downloaddownloadOptions?: { name?: string; extension: 'svg' | 'png' | 'jpeg' | 'webp' }, canvasOptions?: CanvasOptionsDownloads the QR code as a file. Returns Promise<void>.
updateoptions?: RecursivePartial<Options>Updates the QR code with new options. Returns void.
setTemplatetemplateNameOrOptions: string | RecursivePartial<Options>Sets a global default template (by name or options object) for subsequent instances. Returns void.
setTemplateIdtemplateId: stringSets a global default template by its ID. Returns void.
setStylestyleNameOrOptions: string | StyleOptionsSets a global default style (by name or options object) for subsequent instances. Returns void.
setStyleIdstyleId: stringSets a global default style by its ID. Returns void.
setTexttextNameOrOptions: string | TextOptions | null, overrideOpts?: MethodOverrideOptionsSets a global default text configuration for border text. With { override: true }, the text will take precedence over any instance-specific border text. Returns void.
setTextIdtextId: string | null, overrideOpts?: MethodOverrideOptionsSets a global default text configuration by its ID. With { override: true }, the text will take precedence over any instance-specific border text. Returns void.
setBorderborderNameOrOptions: string | RecursivePartial<BorderOptions>Sets a global default border configuration (by name or options object) for subsequent instances. Returns void.
setBorderIdborderId: stringSets a global default border configuration by its ID. Returns void.
setImageimageUrl: string | DataURL | null, overrideOpts?: MethodOverrideOptionsSets a global default image URL for subsequent instances. With { override: true }, the image will take precedence over any instance-specific images. Returns typeof QRCodeJs.
setDatadata: string | null, overrideOpts?: MethodOverrideOptions(Static) Sets a global default data string for subsequent QRCodeJs instances. If overrideOpts.override is true, this data will take precedence over data set by other means (e.g., in constructor options or through useData without override). Returns typeof QRCodeJs.
setOptionsoptions: RecursivePartial<Options> | null, overrideOpts?: MethodOverrideOptions(Static) Sets global default options for subsequent QRCodeJs instances. These are merged deeply with other defaults and instance-specific options. If overrideOpts.override is true, these options take higher precedence over options set by other means for the properties they cover. Returns typeof QRCodeJs.
setSettingssettings: SettingsOptions | null(Static) Sets multiple global defaults at once using a comprehensive SettingsOptions object. This acts as a macro, internally calling other static setters (like setTemplate, setStyle, setData, setImage, setOptions, etc.) based on the properties provided in the settings object. It will override/reset any previously set static configurations for the aspects it covers. Passing null clears all static configurations. Returns typeof QRCodeJs.
useTemplatetemplateNameOrOptions: string | RecursivePartial<Options>Initiates a builder pattern pre-configured with a template (by name or options object). Returns QRCodeBuilder.
useTemplateIdtemplateId: stringInitiates a builder pattern pre-configured with a template by its ID. Returns QRCodeBuilder.
useStylestyleNameOrOptions: string | StyleOptionsInitiates a builder pattern pre-configured with a style (by name or options object). Returns QRCodeBuilder.
useStyleIdstyleId: stringInitiates a builder pattern pre-configured with a style by its ID. Returns QRCodeBuilder.
useTexttextNameOrOptions: string | TextOptions, overrideOpts?: MethodOverrideOptionsInitiates a builder pattern pre-configured with text for border sides. With { override: true }, the text will take precedence over any text set in final options. Returns QRCodeBuilder.
useTextIdtextId: string, overrideOpts?: MethodOverrideOptionsInitiates a builder pattern pre-configured with text by its ID. With { override: true }, the text will take precedence over any text set in final options. Returns QRCodeBuilder.
useBorderborderNameOrOptions: string | BorderOptionsInitiates a builder pattern pre-configured with a border configuration (by name or options object). Returns QRCodeBuilder.
useBorderIdborderId: stringInitiates a builder pattern pre-configured with a border configuration by its ID. Returns QRCodeBuilder.
useImageimageUrl: string | DataURL, overrideOpts?: MethodOverrideOptionsInitiates a builder pattern pre-configured with an image URL. If overrideOpts.override is true, this image will take precedence over any image set in the final .options() call or by other non-overriding builder methods. Returns QRCodeBuilder.
useDatadata: string, overrideOpts?: MethodOverrideOptionsApplies a data string to the current builder configuration. If overrideOpts.override is true, this data will take precedence over data provided in the final .options() call or by other non-overriding builder methods. Returns QRCodeBuilder.
useOptionsoptions: RecursivePartial<Options>, overrideOpts?: MethodOverrideOptionsApplies a partial options object to the current builder configuration. If overrideOpts.override is true, these options take higher precedence over options provided in the final .options() call or by other non-overriding builder methods for the properties they cover. Returns QRCodeBuilder.
useSettingssettings: SettingsOptionsApplies a comprehensive SettingsOptions object as a new baseline for the builder chain. This will reset any configurations previously applied to that builder instance via methods like useTemplate(), useStyle(), useData(), useOptions(), etc. Subsequent builder methods will modify this new baseline. Returns QRCodeBuilder.
useIdid: stringAssigns an identifier to the QR code instance within the builder chain. Returns QRCodeBuilder.
useNamename: stringAssigns a name to the QR code instance within the builder chain. Returns QRCodeBuilder.
useDescriptiondescription: stringAssigns a description to the QR code instance within the builder chain. Returns QRCodeBuilder.
useMetadatametadata: Record<string, any>Attaches custom metadata to the QR code instance within the builder chain. Returns QRCodeBuilder.
validateScanningvalidatorId?: string, debug?: booleanValidates that the QR code is scannable. Returns Promise<ScanValidatorResponse>.
getTemplatesReturns helper functions for looking up predefined templates, styles, text, and borders.
validateImageDataimageData: ImageDataLike(Node.js Static) Validate scannability from raw image data. Returns Promise<ScanValidatorResponse>.
validateSvgsvgSource: string(Node.js Static) Validate scannability from SVG string. Returns Promise<ScanValidatorResponse>.
setIdid: stringSets an identifier for the QR code instance. Returns this.
getId-Gets the identifier for the QR code instance. Returns string | undefined.
setNamename: stringSets a name for the QR code instance. Returns this.
getName-Gets the name for the QR code instance. Returns string | undefined.
setDescriptiondescription: stringSets a description for the QR code instance. Returns this.
getDescription-Gets the description for the QR code instance. Returns string | undefined.
setMetadatametadata: Record<string, any>Sets custom metadata for the QR code instance. Returns this.
getMetadata-Gets the custom metadata for the QR code instance. Returns Record<string, any> | undefined.
getSettings-Gets the current settings and options for the QR code instance. Returns SettingsOptions | undefined.

borderOptions Options

Sub-optionTypeDefaultDescription
hasBorderbooleanfalseMaster switch to enable/disable borders.
thicknessnumber50Thickness of the main border in pixels.
colorstring'#000000'Color of the main border.
radiusstring'0%'Corner rounding of the border (e.g., '10%', '20px').
noBorderThicknessnumberthickness / 4Thickness for border sides with disabled decorations.
backgroundstringundefinedBackground color for the border area.
innerobject{}Options for scaling/offsetting the inner content area.
inner.radiusstring'0%'Corner rounding of the inner border.
inner.scalenumber (0 to 1.5)1Scale factor for the inner content.
inner.horizontalOffsetnumber0Horizontal offset of the inner content.
inner.verticalOffsetnumber0Vertical offset of the inner content.
borderOuterobject{}Options for an additional outer border.
borderOuter.colorstring'#000000'Color of the outer border.
borderOuter.thicknessnumber10Thickness of the outer border.
borderInnerobject{}Options for an additional inner border.
borderInner.colorstring'#000000'Color of the inner border.
borderInner.thicknessnumber5Thickness of the inner border.
decorationsobject{}Add text or images to specific sides of the border.
decorations.topDecorationOptions object{}Decoration options for the top side. See DecorationOptions for details.
decorations.rightDecorationOptions object{}Decoration options for the right side. See DecorationOptions for details.
decorations.bottomDecorationOptions object{}Decoration options for the bottom side. See DecorationOptions for details.
decorations.leftDecorationOptions object{}Decoration options for the left side. See DecorationOptions for details.

Note: Each DecorationOptions object can include properties such as disabled, enableText, offset, curveAdjustment, curveDisabled, curveRadius, type ('text' or 'image'), value, and style for text styling.

DecorationOptions Options

OptionTypeDefaultDescription
disabledbooleanfalseWhether the decoration for this side is disabled.
enableTextbooleanfalseWhether to enable text on this side of the border.
offsetnumber0Positioning offset for the decoration.
curveAdjustmentnumber0Adjustment for the text curve.
curveDisabledbooleanfalseWhether to disable curved text.
curveRadiusstring'50%'Radius of the text curve (e.g., '50%', '100px').
type'text' | 'image''text'The type of decoration to use ('text' or 'image').
valuestring''The text content or image URL for the decoration.
styleobject{}Style options for text decorations.
style.fontFacestring'Helvetica'The font face for the text.
style.fontSizenumber28The font size for the text in pixels.
style.fontColorstring'#ffffff'The color of the text.
style.letterSpacingnumber0The letter spacing for the text in pixels.
style.textTransform'uppercase' | 'lowercase' | 'capitalize'uppercaseThe text transformation style.
style.fontWeight'normal' | 'bold''bold'The font weight for the text.

Enums

These enums provide predefined values for certain properties, ensuring type safety.

ShapeType
enum ShapeType {
  square = 'square',
  circle = 'circle'
}

Mode
enum Mode {
  numeric = 'numeric',
  alphanumeric = 'alphanumeric',
  byte = 'byte',
  kanji = 'kanji',
  unicode = 'unicode'
}

ErrorCorrectionLevel
enum ErrorCorrectionLevel {
  L = 'L', // 7% error recovery
  M = 'M', // 15% error recovery
  Q = 'Q', // 25% error recovery
  H = 'H'  // 30% error recovery
}

DotType
enum DotType {
  dot = 'dot',
  square = 'square',
  rounded = 'rounded',
  extraRounded = 'extra-rounded',
  classy = 'classy',
  classyRounded = 'classy-rounded',
  verticalLine = 'vertical-line',
  horizontalLine = 'horizontal-line',
  randomDot = 'random-dot',
  smallSquare = 'small-square',
  tinySquare = 'tiny-square',
  star = 'star',
  plus = 'plus',
  diamond = 'diamond'
}

CornerSquareType
enum CornerSquareType {
  dot = 'dot',
  square = 'square',
  rounded = 'rounded',
  classy = 'classy',
  outpoint = 'outpoint',
  inpoint = 'inpoint'
}

CornerDotType
enum CornerDotType {
  dot = 'dot',
  square = 'square',
  heart = 'heart',
  rounded = 'rounded',
  classy = 'classy',
  outpoint = 'outpoint',
  inpoint = 'inpoint'
}

ImageMode
enum ImageMode {
  center = 'center',
  overlay = 'overlay',
  background = 'background'
}


QRCodeBuilder Class

The QRCodeBuilder provides a fluent interface for configuring and creating QRCodeJs instances, often starting with a template or style.

Usage:

// Start with a template
const qr1 = QRCodeJs.useTemplate('rounded')
  .options({ data: 'Data for rounded template' })
  .build();

// Start with a style
const qr2 = QRCodeJs.useStyle({ dotsOptions: { type: 'dots', color: 'blue' } })
  .options({ data: 'Data for blue dots style' })
  .build();

// Chain template and style
const qr3 = QRCodeJs.useTemplate('basic')
  .useStyle({ backgroundOptions: { color: '#eee' } })
  .options({ data: 'Data with template and style' })
  .build();
MethodParametersDescription
useTemplatetemplateNameOrOptions: string | RecursivePartial<Options>Applies a template's options to the current configuration. Options from subsequent calls take precedence. Returns this.
useStylestyleNameOrOptions: string | StyleOptionsApplies style options (mapping them to Options) to the current configuration. Returns this.
useTexttextNameOrOptions: string | TextOptions, overrideOpts?: MethodOverrideOptionsApplies text configuration for border sides. With { override: true}, text will take precedence over any text set in final options. Returns this.
useTextIdtextId: string, overrideOpts?: MethodOverrideOptionsApplies text configuration by its ID. With { override: true}, text will take precedence over any text set in final options. Returns this.
useBorderborderNameOrOptions: string | BorderOptionsApplies border configuration (by name or options object) to the current configuration. Returns this.
useBorderIdborderId: stringApplies border configuration by its ID to the current configuration. Returns this.
useImageimageUrl: string, overrideOpts?: MethodOverrideOptionsSets the image URL for the current configuration. If overrideOpts.override is true, this image will take precedence over any image set in the final .options() call. Returns this.
useDatadata: string, overrideOpts?: MethodOverrideOptionsApplies a data string to the current builder configuration. If overrideOpts.override is true, this data will take precedence over data provided in the final .options() call. Returns this.
useOptionsoptions: RecursivePartial<Options>, overrideOpts?: MethodOverrideOptionsApplies a partial options object to the current builder configuration. If overrideOpts.override is true, these options take higher precedence over options provided in the final .options() call for the properties they cover. Returns this.
useSettingssettings: SettingsOptionsApplies a comprehensive SettingsOptions object as a new baseline for the builder chain. This will reset any configurations previously applied to that builder instance via other use methods. Subsequent builder methods modify this new baseline. Returns this.
useIdid: stringAssigns an identifier to the QR code instance being built. Returns this.
useNamename: stringAssigns a name to the QR code instance being built. Returns this.
useDescriptiondescription: stringAssigns a description to the QR code instance being built. Returns this.
useMetadatametadata: Record<string, any>Attaches custom metadata to the QR code instance being built. Returns this.
optionsoptions: RecursivePartial<Options>Merges the provided Options into the current configuration and creates and returns the final QRCodeJs instance.
build-Creates and returns the final QRCodeJs instance based on the accumulated configuration.

QR-Platformis All-in-One QR Codes Management Solution.