Сustom QR generator for Android

Android library for creating QR-codes with logo, custom pixel/eyes shapes, background image. Powered by ZXing.

Playground

Try library features on live app example

I'll be glad, if you leave a positive review for it in Google Play 😊

Library is also available for:

• Version for Compose Multiplatform
• Version for Flutter

Table of contents

• Installation
• Usage
• Customization
• FAQ

Installation

To get a Git project into your build:

Step 1. Add the JitPack repository to your build file

allprojects {
    repositories {
      ...
        maven { url 'https://jitpack.io' }
    }
}

Or for gradle 7+ to settings.gradle file:

dependencyResolutionManagement {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

Step 2. Add the dependency.

dependencies {
    implementation 'com.github.alexzhirkevich:custom-qr-generator:1.6.2'

    // or new v2.0 alpha
    implementation 'com.github.alexzhirkevich:custom-qr-generator:2.0.0-alpha01'
}

Usage

There are 2 types of QR code image - raster (deprecated) image and vector image.

You should use deprecated Raster QR codes only if you need extra customizability or special features like in this example.

Vector code (Drawable)

Step 1. Create QR code data. There are multiple QR types: Plain Text, Url, Wi-Fi, Email, GeoPos, Profile Cards, Phone, etc.

val data = QrData.Url("https://example.com")

Step 2. Define styling options.

1. Using DSL:

val options = createQrVectorOptions {
    
    padding = .125f

    background {
        drawable = ContextCompat
            .getDrawable(context, R.drawable.frame)
    }
    
    logo {
        drawable = ContextCompat
            .getDrawable(context, R.drawable.logo)
        size = .25f
        padding = QrVectorLogoPadding.Natural(.2f)
        shape = QrVectorLogoShape
            .Circle
    }
    colors {
        dark = QrVectorColor
            .Solid(Color(0xff345288))
        ball = QrVectorColor.Solid(
            ContextCompat.getColor(context, R.color.your_color)
        )
        frame = QrVectorColor.LinearGradient(
            colors = listOf(
                0f to android.graphics.Color.RED,
                1f to android.graphics.Color.BLUE,
            ),
            orientation = QrVectorColor.LinearGradient
                .Orientation.LeftDiagonal
        )
    }
    shapes {
        darkPixel = QrVectorPixelShape
            .RoundCorners(.5f)
        ball = QrVectorBallShape
            .RoundCorners(.25f)
        frame = QrVectorFrameShape
            .RoundCorners(.25f)
    }
}

2. Using builder:

val options = QrVectorOptions.Builder()
    .setPadding(.3f)
    .setLogo(
        QrVectorLogo(
            drawable = ContextCompat
                .getDrawable(context, R.drawable.logo),
            size = .25f,
            padding = QrVectorLogoPadding.Natural(.2f),
            shape = QrVectorLogoShape
                .Circle
        )
    )
    .setBackground(
        QrVectorBackground(
            drawable = ContextCompat
                .getDrawable(context, R.drawable.frame),
        )
    )
    .setColors(
        QrVectorColors(
            dark = QrVectorColor
                .Solid(Color(0xff345288)),
            ball = QrVectorColor.Solid(
                ContextCompat.getColor(context, R.color.your_color)
            ),
            frame = QrVectorColor.LinearGradient(
                colors = listOf(
                    0f to android.graphics.Color.RED,
                    1f to android.graphics.Color.BLUE,
                ),
                orientation = QrVectorColor.LinearGradient
                    .Orientation.LeftDiagonal
            )
        )
    )
    .setShapes(
        QrVectorShapes(
            darkPixel = QrVectorPixelShape
                .RoundCorners(.5f),
            ball = QrVectorBallShape
                .RoundCorners(.25f),
            frame = QrVectorFrameShape
                .RoundCorners(.25f),
        )
    )
    .build()

Step 3. Create QR code drawable:

val drawable : Drawable = QrCodeDrawable(data, options)

To interop with Jetpack Compose, you can use this library (recommended) or convert Drawable to Bitmap (not recommended).

Step 4. Press ⭐ if you liked this lib

Raster code (Bitmap)

val data = QrData.Url("https://example.com")

// Color(v : Long) and Long.toColor() functions take 
// 0xAARRGGBB long and convert it to color int.
// Colors from android resources also can be used.
val options = QrOptions.Builder(1024)
    .padding(.3f)
    .background(
        QrBackground(
            drawable = ContextCompat
                .getDrawable(context, R.drawable.frame),
        )
    )
    .logo(
        QrLogo(
            drawable = ContextCompat
                .getDrawable(context, R.drawable.logo),
            size = .25f,
            padding = QrLogoPadding.Accurate(.2f),
            shape = QrLogoShape
                .Circle
        )
    )
    .colors(
        QrColors(
            dark = QrColor
                .Solid(Color(0xff345288)),
            highlighting = QrColor
                .Solid(0xddffffff.toColor()),
        )
    )
    .shapes(
        QrElementsShapes(
            darkPixel = QrPixelShape
                .RoundCorners(),
            ball = QrBallShape
                .RoundCorners(.25f),
            frame = QrFrameShape
                .RoundCorners(.25f),
            highlighting = QrBackgroundShape
                .RoundCorners(.05f)
        )
    )
    .build()

val options = createQrOptions(1024, 1024, .3f) {
    background {
        drawable = ContextCompat
            .getDrawable(context, R.drawable.frame)
    }
    logo {
        drawable = ContextCompat
            .getDrawable(context, R.drawable.logo)
        size = .25f
        padding = QrLogoPadding.Accurate(.2f)
        shape = QrLogoShape
            .Circle
    }
    colors {
        dark = QrColor
            .Solid(0xff345288.toColor())
        highlighting = QrColor
            .Solid(Color(0xddffffff))
    }
    shapes {
        darkPixel = QrPixelShape
            .RoundCorners()
        ball = QrBallShape
            .RoundCorners(.25f)
        frame = QrFrameShape
            .RoundCorners(.25f)
        highlighting = QrBackgroundShape
            .RoundCorners(.05f)
    }
}

val generator = QrCodeGenerator()
  
val bitmap = generator.generateQrCode(data, options)

//todo: don't use GlobalScope
GlobalScope.launch {
    val bitmap = generator.generateQrCodeSuspend(data, options)
}

val threadPolicy = when(Runtime.getRuntime().availableProcessors()){
    in 1..3 -> ThreadPolicy.SingleThread
    in 4..6 -> ThreadPolicy.DoubleThread
    else -> ThreadPolicy.QuadThread
}

val generator = QrCodeGenerator(threadPolicy)

Customization

Vector code (Drawable)

Shapes of QR code elements can be customized using android.graphics.Path.

For example, this is an implementation of circle pixels:

object Circle : QrVectorPixelShape {

    override fun createPath(size: Float, neighbors: Neighbors): Path = Path().apply {
        addCircle(size/2f, size/2f, size/2, Path.Direction.CW)
    }
}

Colors of QR code elements can be customized using android.graphics.Paint.

For example, this is an implementation of sweep gradient:

 class SweepGradient(
        val colors: List<Pair<Float, Int>>
    ) : QrVectorColor {

        override fun createPaint(width: Float, height: Float): Paint =
            Paint().apply {
              shader = android.graphics.SweepGradient(
                  width / 2, height / 2,
                  colors.map { it.second }.toIntArray(),
                  colors.map { it.first }.toFloatArray()
              )
        }
    }
    

Raster code (Bitmap)

Deprecated (click to show). Will be removed in v2.0

You can easily implement your own shapes and coloring for QR Code in 2 ways: using math formulas or by drawing on canvas. Second way is usually slower and uses a lot of memory but provides more freedom.

For example:

1. Using math formulas:

object Circle : QrPixelShape { override fun invoke( i: Int, j: Int, elementSize: Int, neighbors: Neighbors ): Boolean { val center = elementSize/2.0 return sqrt((center-i).pow(2) + (center-j).pow(2)) < center } } val options = createQrOptions(1024, .3f) { shapes { darkPixel = Circle } }

//It is not scannable. Don't create such colorful QR codes object Pride : QrColor { override fun invoke( i: Int, j: Int, width : Int, height : Int ): Int { return when(6f * j/height){ in 0f..1f -> Color.RED in 1f..2f-> Color(0xffffa500) in 2f..3f-> Color.YELLOW in 3f..4f-> Color(0xff00A300) in 4f..5f-> Color.BLUE else -> Color(0xff800080) } } } val options = createQrOptions(1024) { colors { ball = Pride } }

2. By drawing on canvas:

val options : QrOptions = createQrOptions(1024) { shapes { darkPixel = drawShape { canvas, drawPaint, erasePaint -> val cx = canvas.width/2f val cy = canvas.height/2f val radius = minOf(cx,cy) canvas.drawCircle(cx, cy, radius, drawPaint) canvas.drawCircle(cx, cy, radius*2/2.5f, erasePaint) canvas.drawCircle(cx, cy, radius/1.75f, drawPaint) } } }

drawShape is a generic function that can be used only inside a shapes or logo scope and only to create properties of QrElementsShapes or QrLogoShape. Usage with other type-parameters will cause an exception.

‼️ NOTE: Created shape should not be used with other QrOptions with larger size! This can cause shape quality issues.

You can also implement QrCanvasShape and cast it so necessary shape:

object Ring : QrCanvasShape {
   override fun draw(
       canvas: Canvas, drawPaint: Paint, erasePaint: Paint
   ) {
       // ...
   }
}

val ring : QrPixelShape = Ring
    .toShapeModifier(elementSize = 48)
    .asPixelShape()
// or automatically determine size with DSL
val ringPixelOptions : QrOptions = createQrOptions(1024){
    shapes {
        darkPixel = drawShape(Ring::draw)
    }
}

object CanvasColor : QrCanvasColor { override fun draw(canvas: Canvas) = with(canvas) { withRotation(135f, width/2f, height/2f) { drawRect(-width / 2f, -height / 2f, 1.5f * width, height / 2f, Paint().apply { color = Color.BLACK } ) drawRect(-width / 2f, height / 2f, 1.5f * width.toFloat(), 1.5f * height.toFloat(), Paint().apply { color = Color.DKGRAY } ) } } }

Using draw function inside colors scope you can colorize your code elements as you want. It will be converted to a QrColor.

This is QrOptions of the code above:

val options =  createQrOptions(1024, .2f) {
    colors {
        dark = QrColor.RadialGradient(
            startColor = Color.GRAY,
            endColor = Color.BLACK
        )
        ball = draw(CanvasColor::draw)
        frame = draw {
            withRotation(
                180f, width / 2f,
                height / 2f, CanvasColor::draw
            )
        }
        symmetry = true
    }
    shapes {
        darkPixel = QrPixelShape.RoundCorners()
        frame = QrFrameShape.RoundCorners(
            .25f, outer = false, inner = false
        )
    }
}

‼️ NOTE: Created color should not be used with other QrOptions with larger size!

FAQ

I can't scan my code

• Some combinations of shapes are not compatible.
• If you create custom shapes, always test if they corrupt your qr code.
• Choose contrast colors for your code and dont't use too many of them at once.
• If you are using logo, make it smaller or apply next advice.
• Set errorCorrectionLevel explicitly to QrErrorCorrectionLevel.High

I'm trying to encode non-latin symbols and getting a corrupted QR code

See Issue #6

I want a logo/background from a device (file system, gallery)

You just need to resolve Drawable form file system. See this

I want to create shapes for frame or ball with central symmetry

See Issue #13

I want a QR code with 4 eyes

See Issue #19