Package Exports

@devmehq/react-qr-code

Readme

@devmehq/react-qr-code

The most powerful and customizable React component for generating QR codes. Built with TypeScript, offering extensive features including custom shapes, gradients, logos, templates, and more.

Advanced customization examples showcasing various QR code styles

✨ Features

🎨 100+ Customization Options - 12+ eye shapes, 18+ body shapes, 12+ background patterns
🌈 Advanced Gradients - Linear, radial, conic, and mesh gradients
🖼️ Logo Embedding - Add logos/images with smart excavation
📱 QR Templates - WiFi, vCard, SMS, Email, Crypto, and more
🎯 Canvas & SVG - Dual rendering modes with optimal performance
💾 Download & Copy - Built-in export functionality
🎭 Preset Themes - 25+ professionally designed themes
♿ Accessibility - Full ARIA support and keyboard navigation
🚀 Performance - Memoization, lazy loading, and virtualization
📏 TypeScript - Full type safety with strict mode
🔍 QR Validation - Built-in decoder and detectability testing
📦 Tree-Shakable - Optimized bundle size with ESM support

📦 Installation

npm install @devmehq/react-qr-code
# or
yarn add @devmehq/react-qr-code
# or
pnpm add @devmehq/react-qr-code

🎮 Live Demo & Examples

🌐 Online Demos

CodeSandbox Playground - Interactive playground
StackBlitz Demo - Online editor

📂 Local Examples

Clone the repository and run the examples locally:

# Clone the repository
git clone https://github.com/devmehq/react-qr-code.git
cd react-qr-code

# Install dependencies
yarn install

# Build the library
yarn build

# Serve the examples
cd examples
npx http-server -o
# Or use any static server:
# python3 -m http.server 8080
# php -S localhost:8080

Then open your browser to view:

Main Demo - http://localhost:8080/ - Interactive playground with live customization
Advanced Examples - http://localhost:8080/advanced-demo.html - 100+ style variations
Simple Usage - http://localhost:8080/simple-usage.html - Basic implementation examples
API Documentation - http://localhost:8080/api-docs.html - Complete API reference
Detectability Test - http://localhost:8080/qr-test.html - Test QR code scanning

📸 Example Gallery

Basic	Gradient	Circle	Diamond
Rounded	Logo	Interactive Customizer

🚀 Quick Start

import React from 'react'
import { ReactQrCode } from '@devmehq/react-qr-code'

function App() {
  return (
    <ReactQrCode
      value="https://github.com/devmehq/react-qr-code"
      size={256}
      level="H"
    />
  )
}

📖 API Reference

Props

Prop	Type	Default	Description
`value`	`string \| QRDataType`	-	The data to encode
`size`	`number`	`256`	Size of the QR code
`level`	`'L' \| 'M' \| 'Q' \| 'H'`	`'L'`	Error correction level
`bgColor`	`string`	`'#ffffff'`	Background color
`fgColor`	`string`	`'#000000'`	Foreground color
`renderAs`	`'svg' \| 'canvas'`	`'svg'`	Render mode
`marginSize`	`number`	`0`	Margin around QR code
`qrStyle`	`QRCodeStyle`	-	Advanced styling options
`imageSettings`	`ImageSettings`	-	Logo/image configuration
`style`	`CSSProperties`	-	React style object
`className`	`string`	-	CSS class name
`title`	`string`	-	SVG title element
`enableDownload`	`boolean`	`false`	Enable click to download
`downloadOptions`	`DownloadOptions`	-	Download configuration
`animated`	`boolean`	`false`	Enable animations
`lazy`	`boolean`	`false`	Enable lazy loading
`onLoad`	`() => void`	-	Called when QR code loads
`onError`	`(error: Error) => void`	-	Error handler

🎨 Advanced Examples

Using the Advanced Component

import { AdvancedQRCode } from '@devmehq/react-qr-code'

function App() {
  return (
    <AdvancedQRCode
      value="https://github.com/devmehq/react-qr-code"
      size={256}
      theme="gradient"
      eyeShape="rounded"
      bodyShape="circle"
      eyeColor="#4F46E5"
      bodyColor="#7C3AED"
      backgroundColor="#F3F4F6"
      enableDownload={true}
    />
  )
}

Available Preset Themes

<AdvancedQRCode
  value="https://example.com"
  theme="ocean" // or: minimal, gradient, neon, sunset, forest, cyberpunk, etc.
/>

25+ Built-in Themes:

minimal, gradient, ocean, sunset, forest
neon, cyberpunk, retrowave, pastel, dark
colorful, monochrome, gold, silver, bronze
rainbow, aurora, cosmic, earth, fire
ice, nature, elegant, playful, professional

Custom Shapes and Colors

<ReactQrCode
  value="https://example.com"
  size={256}
  qrStyle={{
    module: {
      shape: 'circle',
      color: '#4F46E5',
    },
    corner: {
      shape: 'rounded',
      color: '#7C3AED',
    },
    background: {
      color: '#F3F4F6',
    },
  }}
/>

Advanced Gradient Options

<AdvancedQRCode
  value="https://example.com"
  bodyGradient={{
    type: 'linear',
    colors: ['#667EEA', '#764BA2'],
    angle: 45,
  }}
  backgroundGradient={{
    type: 'radial',
    colors: ['#F3F4F6', '#E5E7EB'],
    centerX: 0.5,
    centerY: 0.5,
    radius: 1,
  }}
/>

// Conic gradient
<AdvancedQRCode
  value="https://example.com"
  bodyGradient={{
    type: 'conic',
    colors: ['#ff0000', '#00ff00', '#0000ff', '#ff0000'],
    angle: 0,
  }}
/>

// Mesh gradient (advanced)
<AdvancedQRCode
  value="https://example.com"
  bodyGradient={{
    type: 'mesh',
    colors: [
      ['#ff0000', '#00ff00'],
      ['#0000ff', '#ffff00'],
    ],
  }}
/>

With Logo

<ReactQrCode
  value="https://example.com"
  imageSettings={{
    src: '/logo.png',
    width: 60,
    height: 60,
    excavate: true,
    opacity: 1,
  }}
/>

WiFi QR Code

import { ReactQrCode, QRHelpers } from '@devmehq/react-qr-code'
;<ReactQrCode
  value={QRHelpers.wifi('MyNetwork', 'password123', 'WPA2', false)}
  size={256}
/>

vCard Contact

<ReactQrCode
  value={QRHelpers.vcard({
    firstName: 'John',
    lastName: 'Doe',
    phone: '+1234567890',
    email: 'john@example.com',
    organization: 'ACME Corp',
    url: 'https://example.com',
  })}
/>

Crypto Payment

// Bitcoin
<ReactQrCode
  value={QRHelpers.bitcoin('1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa', 0.001, 'Donation')}
/>

// Ethereum
<ReactQrCode
  value={QRHelpers.ethereum('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8', 0.01)}
/>

Downloadable QR Code

<ReactQrCode
  value="https://example.com"
  enableDownload={true}
  downloadOptions={{
    filename: 'my-qr-code',
    format: 'png',
    quality: 0.95,
    scale: 2,
  }}
/>

With Animation

<ReactQrCode
  value="https://example.com"
  animated={true}
  animationDuration={500}
  animationDelay={100}
/>

Advanced Shape Customization

<AdvancedQRCode
  value="https://example.com"
  // Eye (finder pattern) shapes
  eyeShape="rounded" // square, circle, rounded, leaf, star, diamond, hexagon, octagon, flower, cat
  eyeFrameShape="rounded" // square, circle, rounded, dots, lines, zigzag, waves, cross, mesh, gradient
  // Body (data module) shapes
  bodyShape="circle" // square, circle, rounded, diamond, star, hexagon, octagon, triangle, cross, plus, dots, lines, zigzag, waves, noise, circuit, organic, fluid
  // Background patterns
  backgroundPattern="dots" // none, dots, lines, grid, mesh, circuit, waves, noise, gradient, radial, hexagon, triangle
/>

Using Ref Methods

import { useRef } from 'react'
import { ReactQrCode, QRCodeRef } from '@devmehq/react-qr-code'

function App() {
  const qrRef = useRef<QRCodeRef>(null)

  const handleDownload = async () => {
    await qrRef.current?.download({
      filename: 'qrcode',
      format: 'png',
      quality: 0.95,
    })
  }

  const handleCopy = async () => {
    await qrRef.current?.copy()
  }

  const getDataURL = async () => {
    const dataURL = await qrRef.current?.getDataURL('png', 0.95)
    console.log(dataURL)
  }

  return (
    <>
      <ReactQrCode ref={qrRef} value="https://example.com" />
      <button onClick={handleDownload}>Download</button>
      <button onClick={handleCopy}>Copy to Clipboard</button>
      <button onClick={getDataURL}>Get Data URL</button>
    </>
  )
}

🧪 Advanced Customization API

The AdvancedQRCode component provides extensive customization:

interface AdvancedQRCodeProps {
  // Basic
  value: string
  size?: number
  level?: 'L' | 'M' | 'Q' | 'H'

  // Themes
  theme?: PresetTheme
  colorBlindMode?:
    | 'none'
    | 'protanopia'
    | 'deuteranopia'
    | 'tritanopia'
    | 'achromatopsia'

  // Shapes
  eyeShape?: EyeShape
  eyeFrameShape?: EyeFrameShape
  bodyShape?: BodyShape

  // Colors
  eyeColor?: string | GradientConfig
  eyeFrameColor?: string | GradientConfig
  bodyColor?: string | GradientConfig
  backgroundColor?: string | GradientConfig

  // Gradients
  eyeGradient?: GradientConfig
  bodyGradient?: GradientConfig
  backgroundGradient?: GradientConfig

  // Patterns
  backgroundPattern?: BackgroundPattern

  // Effects
  animationType?: 'none' | 'fade' | 'scale' | 'rotate' | 'slide' | 'bounce'
  glowEffect?: boolean
  shadowEffect?: boolean

  // Logo
  logo?: string
  logoSize?: number
  logoExcavate?: boolean

  // Actions
  enableDownload?: boolean
  enableCopy?: boolean
  downloadFilename?: string
}

📱 QR Code Templates

The library includes helper functions for common QR code types:

import { QRHelpers } from '@devmehq/react-qr-code'

// WiFi
QRHelpers.wifi(ssid, password, security, hidden)

// vCard Contact
QRHelpers.vcard({
  firstName,
  lastName,
  phone,
  email,
  organization,
  url,
  address,
})

// SMS
QRHelpers.sms(phone, message)

// Email
QRHelpers.email(to, subject, body, cc, bcc)

// Geo Location
QRHelpers.geo(latitude, longitude, altitude)

// Calendar Event
QRHelpers.event({ summary, startDate, endDate, location, description })

// Phone
QRHelpers.phone(number)

// Bitcoin
QRHelpers.bitcoin(address, amount, label, message)

// Ethereum
QRHelpers.ethereum(address, amount, gas)

// URL
QRHelpers.url(url)

// Plain Text
QRHelpers.text(text)

🎯 TypeScript Support

The library is fully typed. Import types as needed:

import type {
  ReactQrCodeProps,
  QRCodeRef,
  ErrorCorrectionLevel,
  ModuleShape,
  ImageSettings,
  QRCodeStyle,
  WiFiData,
  VCardData,
  // ... and more
} from '@devmehq/react-qr-code'

⚡ Performance Tips

Use Memoization: The component uses React.memo and useMemo internally
Lazy Loading: Enable lazy={true} for off-screen QR codes
Debouncing: Use debounceMs for frequently changing values
Canvas for Large QR: Use renderAs="canvas" for better performance with large sizes
Optimize Images: Use optimized images for logos to reduce load time

🌐 Browser Support

Chrome/Edge: Latest 2 versions
Firefox: Latest 2 versions
Safari: Latest 2 versions
Mobile browsers: iOS Safari 12+, Chrome Mobile

📊 Bundle Size

ESM: ~15KB minified + gzipped
Tree-shakable: Import only what you need
Zero dependencies: Only React as peer dependency

🔧 Development & Testing

Running Tests

# Run unit tests
yarn test

# Run with coverage
yarn test:coverage

# Run detectability tests
node test/e2e-svg-detectability.js

Building

# Development build
yarn build

# Production build
yarn build:prod

# Watch mode
yarn build:watch

Type Checking & Linting

# Type check
yarn typecheck

# Lint
yarn lint

# Format code
yarn prettier

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

# Clone the repo
git clone https://github.com/devmehq/react-qr-code.git

# Install dependencies
yarn install

# Run tests
yarn test

# Build
yarn build

# Run in watch mode
yarn build:watch

📄 License

MIT © DEV.ME

🙏 Credits

Built with ❤️ by the DEV.ME team.

🔗 Links

📸 More Examples

Various implementation examples and use cases

Scan to visit our GitHub!