---
title: Fliplet.Barcode
description: Scan QR codes and 1D/2D barcodes from the camera on web and native (attachScanner / scan) and generate barcode images, via the fliplet-barcode package.
type: api-reference
tags: [js-api, barcode]
v3_relevant: false
deprecated: false
exclude_from_v3_catalog: true
---
# `Fliplet.Barcode`

Scan QR codes and other 1D/2D barcodes from the device camera, and generate barcode images on screen, via the `fliplet-barcode` package.

The package offers two ways to scan: `attachScanner()` embeds a scanner in a container in your own UI and works on web and native, while `scan()` opens a ready-made full-screen scanner on native. Use `show()` or `encode()` to generate barcode images. Building a scanning screen in a V3 app? See the [V3 barcode scanning guide](./v3/barcode.md).

## Install

Add the `fliplet-barcode` dependency to your screen or app resources.

## Fliplet.Barcode.attachScanner()

(Returns a controller object)

`attachScanner()` is a low-level scanner with **no built-in UI**: you provide a container element (placed and styled inside your own screen or modal) and `attachScanner()` drives the camera and decoder into it. It works the same on **web and native**.

### Usage

```js
// 1. Put a container in your own UI: <div id="reader"></div>
var scanner = Fliplet.Barcode.attachScanner(document.getElementById('reader'), {
  onScan: function (result) {
    // result.text   — the decoded value
    // result.format — e.g. 'QR_CODE', 'CODE_128'
    scanner.stop(); // one-shot: stop after the first scan (or keep scanning)
  },
  onError: function (error) {
    // camera permission denied, no camera, or library failed to load
  }
});

// when the user leaves the screen or closes your scanner UI:
scanner.stop();
```

A typical "tap a button to scan" screen shows your own button, reveals the `#reader` container when tapped, calls `attachScanner()`, and displays `result.text` on screen from inside `onScan`.

* **element** (HTMLElement | String) The container to render the camera into (an element or its `id`). You own its placement and styling — `attachScanner()` neither creates nor removes it.
* **options** (Object)
  * **onScan** (Function) Called on every successful decode with `{ text, format }`. Call `scanner.stop()` inside it for one-shot scanning.
  * **onError** (Function) Called on a fatal start error (camera permission denied, no camera, or library load failure).
  * **fps** (Number) Decode attempts per second. Default `10`.
  * **qrbox** (Object | Function) Scan-box size (html5-qrcode `qrbox`). Defaults to a centred square at 70% of the smaller edge.
* **Returns** a controller `{ stop() }`. `stop()` ends the camera, tears down the decoder (your element is left in the DOM), and returns a `Promise`.

**Permissions**: on web the browser prompts for camera access when scanning starts and requires a secure context (HTTPS). On native the OS prompts on first use.

## Fliplet.Barcode.scan()

(Returns `Promise`)

Open a ready-made full-screen scanner and resolve with the result. This is a convenience shortcut for a quick, standalone scan where you do not need the scanner embedded in your own screen.

**Note**: `scan()` is only supported in native apps. For scanning that also works on the web, use [`attachScanner()`](#fliplet-barcode-attachscanner).

### Usage

```js
Fliplet.Barcode.scan(options).then(function (result) {
  // result.text
  // result.format
  // result.cancelled
}).catch(function (error) {
  // scan failed
});
```

* **options** (Object) A map of optional configurations for the scanner. See [**PhoneGap Plugin BarcodeScanner** documentation](https://github.com/phonegap/phonegap-plugin-barcodescanner) for a full list of supported options. The default options used by Fliplet is listed below.

```js
options = {
  preferFrontCamera: false, // iOS and Android
  showFlipCameraButton: true, // iOS and Android
  showTorchButton: true, // iOS and Android
  torchOn: false, // Android, launch with the torch switched on (if available)
  saveHistory: true, // Android, save scan history (default false)
  prompt: 'Place a barcode inside the scan area', // Android
};
```

## Fliplet.Barcode.show()

(Returns **`Promise`**)

Encode text into QR code or barcode and show it on the screen.

**Note**: A QR code is generated by default unless an alternative format is provided (see below).

### Usage

```js
Fliplet.Barcode.show(text).then(function (data) {
  // data (String) Encoded Base64 string
}).catch(function (error) {
  // encoding failed
});
```

* **text** (String) String to be encoded into a QR code and displayed

```js
Fliplet.Barcode.show(text, options).then(function (data) {
  // data (String) Encoded Base64 string
}).catch(function (error) {
  // encoding failed
});
```

* **text** (String) String to be encoded into a QR code or barcode and displayed
* **options** (Object) A map of options for the encoding
  * **format** (String) Format to encode the provided text with. See below for a list of supported formats:
    * `qr` (**Default**)
    * `barcode` - This will encode the provided text in `code128` format. See below for a specific list of supported formats [as supported by JsBarcode](https://github.com/lindell/JsBarcode/wiki#barcodes).
    * `code39`, `code128`, `code128A`, `code128B`, `code128C`, `ean13`, `ean8`, `ean5`, `ean2`, `upc`, `upce`, `itf14`, `itf`, `msi`, `msi10`, `msi11`, `msi1010`, `msi1110`, `pharmacode`, `codabar`, `genericbarcode`
  * **color** (String) Foreground color for the barcode. This can be a color keyword (e.g. `green`) or hexcode (e.g. `#00ff00`). **Default** `#000000`
  * **background** (String) Background color for the barcode. This can be a color keyword (e.g. `green`) or hexcode (e.g. `#00ff00`). **Default** `#ffffff`
  * **title** (String) Optional title to show to the user
  * **message** (String) Optional message to show to the user
  * **height** (Number) **Barcode only** - Height of barcode image. **Default** `150`
  * **lineWidth** (Number) **Barcode only** - Width of a single bar. The higher this number, the wider the result image. **Default** `2`

**Note** If a barcode is generated instead of a QR code, adjust `height` and `lineWidth` according to the text length. Fliplet recommends using QR codes unless a barcode is required because QR codes are always generated in a 1:1 aspect ratio.

## Fliplet.Barcode.encode()

(Returns **`Promise`**)

Encode text into QR code or barcode and return it as a Base64 image.

**Note**: A QR code is generated by default unless an alternative format is provided (see below).

### Usage

```js
Fliplet.Barcode.encode(text).then(function (data) {
  // data (String) Encoded Base64 string
}).catch(function (error) {
  // encoding failed
});
```

* **text** (String) String to be encoded into a QR code

```js
Fliplet.Barcode.encode(text, options).then(function (data) {
  // data (String) Encoded Base64 string
}).catch(function (error) {
  // encoding failed
});
```

* **text** (String) String to be encoded into a QR code or barcode
* **options** (Object) A map of options for the encoding
  * **format** (String) Format to encode the provided text with. See below for a list of supported formats:
    * `qr` (**Default**)
    * `barcode` - This will encode the provided text in `code128` format. See below for a specific list of supported formats [as supported by JsBarcode](https://github.com/lindell/JsBarcode/wiki#barcodes).
    * `code39`, `code128`, `code128A`, `code128B`, `code128C`, `ean13`, `ean8`, `ean5`, `ean2`, `upc`, `upce`, `itf14`, `itf`, `msi`, `msi10`, `msi11`, `msi1010`, `msi1110`, `pharmacode`, `codabar`, `genericbarcode`
  * **color** (String) Foreground color for the barcode. This can be a color keyword (e.g. `green`) or hexcode (e.g. `#00ff00`). **Default** `#000000`
  * **background** (String) Background color for the barcode. This can be a color keyword (e.g. `green`) or hexcode (e.g. `#00ff00`). **Default** `#ffffff`
  * **width** (Number) **QR code only** - Width of QR code image. **Default** `600`.
    * **Note**: For barcodes, the result width depends on the length of text encoded and the width of a single bar as configured via `lineWidth` (see below).
  * **height** (Number) Height of QR code or barcode image. **Default** `600` for QR code, `150` for barcode
  * **lineWidth** (Number) **Barcode only** - Width of a single bar. The higher this number, the wider the result image. **Default** `2`

**Note** If a barcode is generated instead of a QR code, adjust `height` and `lineWidth` according to the text length. Fliplet recommends using QR codes unless a barcode is required because QR codes are always generated in a 1:1 aspect ratio.

---

[Back to Fliplet.UI](./fliplet-ui)
{: .buttons}