qr-code.js

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

Option Type Default Description
data string - 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.
width number \| string Auto-calculated QR code width in pixels or CSS units. When isResponsive is false, overrides auto-calculated width. When isResponsive is true, this value is ignored.
height number \| string Auto-calculated QR code height in pixels or CSS units. When isResponsive is false, overrides auto-calculated height. When isResponsive is true, this value is ignored.
margin number 0 The quiet zone (empty space) around the QR code in pixels.
isResponsive boolean false Controls whether the QR code SVG should be responsive to its container. When true, SVG uses 100% width/height, ignoring any specified width/height values. When false, SVG uses specified width/height values or auto-calculated dimensions.
scale number (0 to 1.5) 1 Scales the QR code size relative to its container or border.
offset number 0 Applies a vertical offset (positive moves down, negative moves up) relative to the center.
verticalOffset number 0 Applies an absolute vertical offset in pixels.
horizontalOffset number 0 Applies an absolute horizontal offset in pixels.
qrOptions object {...} Options related to the underlying QR code generation algorithm.
qrOptions.typeNumber number (0-40) 0 Specifies the QR code version (size/capacity). 0 means automatic detection.
qrOptions.mode Mode enum Auto-detected The 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.
dotsOptions object {...} Options for styling the dots in the QR code.
dotsOptions.type DotType enum 'square' The shape of the dots. See DotType enum.
dotsOptions.color string '#000000' The color of the dots. Accepts any valid CSS color string (e.g., '#FF0000', 'red', 'rgba(255, 0, 0, 0.5)').
dotsOptions.size number 10 The size of the dots in pixels.
dotsOptions.gradient Gradient object undefined Apply 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.
rotation number - The rotation angle in radians for the gradient. Only applicable when type is ‘linear’.
colorStops Array<{ 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.
cornersSquareOptions object {...} Options for styling the corner squares. Overrides dotsOptions.
cornersSquareOptions.type CornerSquareType enum Inherits The shape of the corner squares. See CornerSquareType enum for options (e.g., square, rounded).
cornersSquareOptions.color string Inherits The color of the corner squares.
cornersSquareOptions.gradient Gradient object undefined Apply a gradient fill to the corner squares.
cornersDotOptions object {...} Options for styling the corner dots. Overrides cornersSquareOptions.
backgroundOptions object \| false {...} Options for styling the background. Set to false to disable.
backgroundOptions.color string '#FFFFFF' The background color.
backgroundOptions.round number \| string 0 Rounds the corners of the background (0-1 or percentage).
backgroundOptions.gradient Gradient object undefined Apply a gradient fill to the background. See Gradient options for configuration details.
image string \| Buffer \| Blob undefined URL, 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.
imageOptions object {...} Options for the embedded image.
imageOptions.mode ImageMode enum 'center' How the image is embedded. See ImageMode enum.
imageOptions.imageSize number 0.4 Relative size of the image (0-1).
imageOptions.margin number 0 Margin around the image in blocks. Warning: Keep minimal or QR code may disappear.
imageOptions.backgroundColor string undefined Background color of QR code image (logo).
imageOptions.padding number 0 Padding around the image in pixels.
imageOptions.radius string \| number undefined Border radius of the image (e.g., “10px” or 10).
imageOptions.crossOrigin string undefined CORS setting for the image.
borderOptions BorderOptions object undefined Options 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.

Option Type Default Description
cornersDotOptions.type CornerDotType enum Inherits Specifies the shape of the corner dots. Refer to the CornerDotType enum for available options (e.g., square, rounded).
cornersDotOptions.color string Inherits Defines the solid color of the corner dots. Accepts any valid CSS color string (e.g., '#FF0000', 'red', 'rgba(255, 0, 0, 0.5)').
cornersDotOptions.gradient Gradient object undefined Applies a gradient fill to the corner dots, overriding the color property if both are set. See Gradient Sub-options for configuration details.

Additional Notes

QRCode.js Methods Table

Method Parameters Description
append container: HTMLElement, options?: { clearContainer?: boolean } Appends the QR code to a container element. Returns QRCodeJs \| undefined.
serialize inverted?: boolean Converts the QR code to an SVG string. Returns Promise<string \| undefined>.
download downloadOptions?: { name?: string; extension: 'svg' \| 'png' \| 'jpeg' \| 'webp' }, canvasOptions?: CanvasOptions Downloads the QR code as a file. Returns Promise<void>.
update options?: RecursivePartial<Options> Updates the QR code with new options. Returns void.
setTemplate templateNameOrOptions: string \| RecursivePartial<Options> Sets a global default template (by name or options object) for subsequent instances. Returns void.
setTemplateId templateId: string Sets a global default template by its ID. Returns void.
setStyle styleNameOrOptions: string \| StyleOptions Sets a global default style (by name or options object) for subsequent instances. Returns void.
setStyleId styleId: string Sets a global default style by its ID. Returns void.
setText textNameOrOptions: string \| TextOptions \| null, overrideOpts?: MethodOverrideOptions Sets a global default text configuration for border text. With { override: true }, the text will take precedence over any instance-specific border text. Returns void.
setTextId textId: string \| null, overrideOpts?: MethodOverrideOptions Sets a global default text configuration by its ID. With { override: true }, the text will take precedence over any instance-specific border text. Returns void.
setBorder borderNameOrOptions: string \| RecursivePartial<BorderOptions> Sets a global default border configuration (by name or options object) for subsequent instances. Returns void.
setBorderId borderId: string Sets a global default border configuration by its ID. Returns void.
setImage imageUrl: string \| DataURL \| null, overrideOpts?: MethodOverrideOptions Sets a global default image URL for subsequent instances. With { override: true }, the image will take precedence over any instance-specific images. Returns typeof QRCodeJs.
setData data: 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.
setOptions options: 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.
setSettings settings: 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.
useTemplate templateNameOrOptions: string \| RecursivePartial<Options> Initiates a builder pattern pre-configured with a template (by name or options object). Returns QRCodeBuilder.
useTemplateId templateId: string Initiates a builder pattern pre-configured with a template by its ID. Returns QRCodeBuilder.
useStyle styleNameOrOptions: string \| StyleOptions Initiates a builder pattern pre-configured with a style (by name or options object). Returns QRCodeBuilder.
useStyleId styleId: string Initiates a builder pattern pre-configured with a style by its ID. Returns QRCodeBuilder.
useText textNameOrOptions: string \| TextOptions, overrideOpts?: MethodOverrideOptions Initiates 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.
useTextId textId: string, overrideOpts?: MethodOverrideOptions Initiates 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.
useBorder borderNameOrOptions: string \| BorderOptions Initiates a builder pattern pre-configured with a border configuration (by name or options object). Returns QRCodeBuilder.
useBorderId borderId: string Initiates a builder pattern pre-configured with a border configuration by its ID. Returns QRCodeBuilder.
useImage imageUrl: string \| DataURL, overrideOpts?: MethodOverrideOptions Initiates 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.
useData data: string, overrideOpts?: MethodOverrideOptions Applies 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.
useOptions options: RecursivePartial<Options>, overrideOpts?: MethodOverrideOptions Applies 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.
useSettings settings: SettingsOptions Applies 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.
useId id: string Assigns an identifier to the QR code instance within the builder chain. Returns QRCodeBuilder.
useName name: string Assigns a name to the QR code instance within the builder chain. Returns QRCodeBuilder.
useDescription description: string Assigns a description to the QR code instance within the builder chain. Returns QRCodeBuilder.
useMetadata metadata: Record<string, any> Attaches custom metadata to the QR code instance within the builder chain. Returns QRCodeBuilder.
validateScanning validatorId?: string, debug?: boolean Validates that the QR code is scannable. Returns Promise<ScanValidatorResponse>.
getTemplates   Returns helper functions for looking up predefined templates, styles, text, and borders.
validateImageData imageData: ImageDataLike (Node.js Static) Validate scannability from raw image data. Returns Promise<ScanValidatorResponse>.
validateSvg svgSource: string (Node.js Static) Validate scannability from SVG string. Returns Promise<ScanValidatorResponse>.
setId id: string Sets an identifier for the QR code instance. Returns this.
getId - Gets the identifier for the QR code instance. Returns string \| undefined.
setName name: string Sets a name for the QR code instance. Returns this.
getName - Gets the name for the QR code instance. Returns string \| undefined.
setDescription description: string Sets a description for the QR code instance. Returns this.
getDescription - Gets the description for the QR code instance. Returns string \| undefined.
setMetadata metadata: 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-option Type Default Description
hasBorder boolean false Master switch to enable/disable borders.
thickness number 50 Thickness of the main border in pixels.
color string '#000000' Color of the main border.
radius string '0%' Corner rounding of the border (e.g., '10%', '20px').
noBorderThickness number thickness / 4 Thickness for border sides with disabled decorations.
background string undefined Background color for the border area.
inner object {} Options for scaling/offsetting the inner content area.
inner.radius string '0%' Corner rounding of the inner border.
inner.scale number (0 to 1.5) 1 Scale factor for the inner content.
inner.horizontalOffset number 0 Horizontal offset of the inner content.
inner.verticalOffset number 0 Vertical offset of the inner content.
borderOuter object {} Options for an additional outer border.
borderOuter.color string '#000000' Color of the outer border.
borderOuter.thickness number 10 Thickness of the outer border.
borderInner object {} Options for an additional inner border.
borderInner.color string '#000000' Color of the inner border.
borderInner.thickness number 5 Thickness of the inner border.
decorations object {} Add text or images to specific sides of the border.
decorations.top DecorationOptions object {} Decoration options for the top side. See DecorationOptions for details.
decorations.right DecorationOptions object {} Decoration options for the right side. See DecorationOptions for details.
decorations.bottom DecorationOptions object {} Decoration options for the bottom side. See DecorationOptions for details.
decorations.left DecorationOptions 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

Option Type Default Description
disabled boolean false Whether the decoration for this side is disabled.
enableText boolean false Whether to enable text on this side of the border.
offset number 0 Positioning offset for the decoration.
curveAdjustment number 0 Adjustment for the text curve.
curveDisabled boolean false Whether to disable curved text.
curveRadius string '50%' Radius of the text curve (e.g., '50%', '100px').
type 'text' \| 'image' 'text' The type of decoration to use ('text' or 'image').
value string '' The text content or image URL for the decoration.
style object {} Style options for text decorations.
style.fontFace string 'Helvetica' The font face for the text.
style.fontSize number 28 The font size for the text in pixels.
style.fontColor string '#ffffff' The color of the text.
style.letterSpacing number 0 The letter spacing for the text in pixels.
style.textTransform 'uppercase' \| 'lowercase' \| 'capitalize' uppercase The 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();
Method Parameters Description
useTemplate templateNameOrOptions: string \| RecursivePartial<Options> Applies a template’s options to the current configuration. Options from subsequent calls take precedence. Returns this.
useStyle styleNameOrOptions: string \| StyleOptions Applies style options (mapping them to Options) to the current configuration. Returns this.
useText textNameOrOptions: string \| TextOptions, overrideOpts?: MethodOverrideOptions Applies text configuration for border sides. With { override: true}, text will take precedence over any text set in final options. Returns this.
useTextId textId: string, overrideOpts?: MethodOverrideOptions Applies text configuration by its ID. With { override: true}, text will take precedence over any text set in final options. Returns this.
useBorder borderNameOrOptions: string \| BorderOptions Applies border configuration (by name or options object) to the current configuration. Returns this.
useBorderId borderId: string Applies border configuration by its ID to the current configuration. Returns this.
useImage imageUrl: string, overrideOpts?: MethodOverrideOptions Sets 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.
useData data: string, overrideOpts?: MethodOverrideOptions Applies 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.
useOptions options: RecursivePartial<Options>, overrideOpts?: MethodOverrideOptions Applies 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.
useSettings settings: SettingsOptions Applies 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.
useId id: string Assigns an identifier to the QR code instance being built. Returns this.
useName name: string Assigns a name to the QR code instance being built. Returns this.
useDescription description: string Assigns a description to the QR code instance being built. Returns this.
useMetadata metadata: Record<string, any> Attaches custom metadata to the QR code instance being built. Returns this.
options options: 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.
This site is open source. Improve this page.