# scan-barcode

## Overview

`scan-barcode` launches the barcode scanner which opens a camera view with which app users can scan codes.

{% hint style="info" %}
**Version and device compatibility**

* `scan-barcode` is supported in all versions of the JourneyApps Container and Runtime.
* It is supported on Android and iOS devices.
* It received several visual and functional updates in version **4.80.0** of the JourneyApps Runtime.
  {% endhint %}

{% hint style="info" %}
**Programmatically trigger the barcode scanner**

The barcode scanner can be triggered programmatically using `journey.hardware.scanBarcode()`. See more details [here](https://docs.journeyapps.com/reference/build/js-ts-apis/journey/journey.hardware).
{% endhint %}

### Basic Example

{% code title="main.view\.xml" %}

```xml
<var name="product_barcode" type="text" />

<scan-barcode bind="product_barcode" label="Scan the Product's Barcode" />
```

{% endcode %}

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-0cac8f5aac7c7dd8ecaee199cbec9b3f87824512%2Fscan-barcode-example.png?alt=media)

## Standard Attributes

### `bind`

{% content-ref url="../xml-fields/bind" %}
[bind](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/bind)
{% endcontent-ref %}

### `label`

{% content-ref url="../xml-fields/label" %}
[label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label)
{% endcontent-ref %}

### `required`

{% content-ref url="../xml-fields/required" %}
[required](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/required)
{% endcontent-ref %}

## Advanced Attributes

### `align-content`

{% hint style="info" %}
**Version compatibility**

`align-content` was introduced in version **4.81.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/align-content" %}
[align-content](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-content)
{% endcontent-ref %}

### `align-label`

{% content-ref url="../xml-fields/align-label" %}
[align-label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-label)
{% endcontent-ref %}

### `allow-manual-entry`

**Optional**

**Type**: `boolean`

**Default**: `true`

{% hint style="info" %}
**Version compatibility**

`allow-manual-entry` was introduced in version **4.81.0** of the JourneyApps Runtime.
{% endhint %}

On unsupported devices, a text input dialog will display for users to manually enter the data. This dialog can be skipped by setting `allow-manual-entry` to `false`.

### `color`

**Optional**

**Type**: `string`- can be a named color or #HEX value

**Default**: `primary`

The main color of the `scan-barcode` button: Background color of a [`solid`](#style) button; border and text color of an [`outline`](#style) button.

{% hint style="info" %}
**Button text color**

When using named colors (i.e. `primary`, `secondary`, `positive`, `negative`, etc) the corresponding named `_text` color will be used as the button's text color.&#x20;

For example, this button:&#x20;

`<button label="My button" color="secondary" on-press="$:doSomething()"/>`

Will use the theme's `secondary_text` named color for the button text.

When using a #HEX value, a high contrasting color will automatically be selected for the button's text color.&#x20;

To override the button's text color, set the [`text-color`](#text-color) attribute.

{% endhint %}

```xml
<scan-barcode label="Scan QR code" color="$:getColor()" />
```

```javascript
function getColor() {
    return "#ffab00";
}
```

### `disabled`

{% content-ref url="../xml-fields/disabled" %}
[disabled](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/disabled)
{% endcontent-ref %}

### `disabled-message`

**Optional**

**Type**: `string` (static text, a [format string](https://docs.journeyapps.com/reference/app-features/xml-format-strings) or the return value of a [JS/TS function](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml))

**Default**: unset

When the `disabled` attribute is set to `true` the component will display the bound state and direct interactions blocked. The component will appear greyed-out. A message will display indicating the message specified.

### `extensions`

**Optional**

**Type**: `EAN_2`, `EAN_5`

Comma-separated list of barcode type extensions.

{% hint style="info" %}
**Platform compatibility**

`extensions` are currently only supported on Android.
{% endhint %}

```xml
<var name="product" type="text"/>

<scan-barcode bind="product" extensions="EAN_2,EAN_5" />
```

### `icon`

**Optional**

**Type**: `string`

**Default**: Barcode Scanner Icon

{% hint style="info" %}
**Version compatibility**

`icon` was introduced in version **4.81.0** of the JourneyApps Runtime.
{% endhint %}

The icon to display on the button, it will be placed on the left of the label by default. The icon can be a [Font Awesome icon](https://docs.journeyapps.com/reference/build/ui-components/icons#font-awesome-icons), an [Ionicons icon](https://docs.journeyapps.com/reference/build/ui-components/icons#ionicons-icons) or an icon or image asset.

### `icon-color`

**Optional**

**Type**: `string`

**Default**: the component's [`text-color`](#text-color)

Specify the color of the button's icon. The `icon-color` attribute can be a named text-color or #HEX value.

{% hint style="info" %}
When using `icon-color` with image assets, a color mask will be applied to the icon will remove any color variation in the image.
{% endhint %}

### `icon-position`

{% content-ref url="../xml-fields/icon-position" %}
[icon-position](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/icon-position)
{% endcontent-ref %}

### `id`

{% content-ref url="../xml-fields/id" %}
[id](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id)
{% endcontent-ref %}

### `label-case`

{% hint style="info" %}
**Version compatibility**

`label-case` was introduced in version **4.81.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/label-case" %}
[label-case](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-case)
{% endcontent-ref %}

### `label-color`

{% content-ref url="../xml-fields/label-color" %}
[label-color](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-color)
{% endcontent-ref %}

### `on-change` and `on-scan`

{% content-ref url="../xml-fields/on-change" %}
[on-change](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/on-change)
{% endcontent-ref %}

{% hint style="info" %}
`on-scan` is functionally similar to `on-change`, however only the current `$value` is being passed as an event parameter.
{% endhint %}

### `prompt`

**Optional**

**Type**: `string`

**Default**: unset

Prompt text to display on the barcode scanning screen. Message will also display on the manual fallback dialog.

### `show-if` and `hide-if`

{% content-ref url="../xml-fields/show-if" %}
[show-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/show-if)
{% endcontent-ref %}

{% content-ref url="../xml-fields/hide-if" %}
[hide-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/hide-if)
{% endcontent-ref %}

### `style`

**Optional**

**Type**: `solid` | `outline`

**Default**: `solid`

The `scan-barcode` button style conveys importance of a button to the user, and can be set to `solid` or `outline`.

```xml
<scan-barcode label="Scan the Product's Barcode" style="outline"  />
```

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-172472d2768b687f4fe2de9eb276aecedb39d7d1%2Fscan-barcode-sstyle.png?alt=media)

### `text-color`

{% hint style="info" %}
**Version compatibility**

`text-color` was introduced in version **4.81.0** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `string` - can be a named color or #HEX value

**Default**: If the button's [`color`](#color) is a named color, its text color defaults to the `_text` counterpart of the named color. If the button's [`color`](#color) is a #HEX value, its text color defaults to a high contrasting color.

Specify the color of the `scan-barcode` button's label.&#x20;

```xml
<scan-barcode label="Scan the Product's Barcode" text-color="#ffff00" />
```

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-c71c424ec1b50fc22794d8bf88ba9271d77e36b0%2Fscan-barcode-text-color.png?alt=media)

### `types`

**Optional**

Comma-separated list of barcode types to attempt to scan.

```xml
<var name="product_code" type="text"/>

<scan-barcode bind="product_code" types="QR_CODE,UPC_A,UPC_E" />
```

{% hint style="info" %}
**`scan-barcode` on RealWear devices**

By default `scan-barcode` will open JourneyApps' built-in barcode scanner on RealWear devices. With container version **22.7.2** or greater, it is possible to launch RealWear's native barcode scanner for certain barcode types (which comes with improved UI and voice control). This can be achieved by limiting the list of `types` to types that are supported by RealWear's barcode scanner. Supported types are:

* `CODE_128`
* `EAN_8`
* `EAN_13`
* `UPC_A`
* `QR_CODE`
* `DATA_MATRIX`
  {% endhint %}

#### Supported Barcode Formats

|                    | Android                                                                                       | iOS                                 |
| ------------------ | --------------------------------------------------------------------------------------------- | ----------------------------------- |
| Product barcodes:  | `UPC_A`, `UPC_E`, `EAN_8`, `EAN_13`, `RSS_14` (all variants), `RSS_EXPANDED` (most variants). | `UPC_A`, `UPC_E`, `EAN_8`, `EAN_13` |
| Other 1D barcodes: | `CODE_39`, `CODE_93`, `CODE_128`, `ITF`, `CODABAR`                                            | `CODE_39`, `CODE_128`               |
| 2D barcodes:       | `QR_CODE`, `DATA_MATRIX`, `AZTEC` (beta quality), `PDF_417`                                   | `QR_CODE`, `DATA_MATRIX`            |

## Component Methods

The following component methods are available when an [`id`](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id) is assigned to the component and `component.scanBarcode({id:'my-id'})` is called from JS/TS:

### `scanBarcode`

Programmatically opens the barcode scanner to allow the user to capture a barcode bound to the `scan-barcode` component.

### `scrollIntoView`

Programmatically scroll until the `scan-barcode` component is visible in the view.