Choose a version:

Scanner API
APIs

The Scanner API enables an extension to access scanner data and available scanning sources supported by the device.

Supporting targets

Anchor to scannerapiScannerApi

Anchor to scannerDataSubscribable scannerDataSubscribable RemoteSubscribable<> required: Creates a subscription to scan events Provides an initial value and a callback to subscribe to value changes. Currently supports only one subscription. You can utilize makeStatefulSubscribable on a RemoteSubscribable to implement multiple subscriptions. Using makeStatefulSubscribable or the corresponding hooks counts as a subscription.
Anchor to scannerSourcesSubscribable scannerSourcesSubscribable RemoteSubscribable<[]> required: Creates a subscription to the scanning sources available on the POS device. Provides an initial value and a callback to subscribe to value changes. Currently supports only one subscription. You can utilize makeStatefulSubscribable on a RemoteSubscribable to implement multiple subscriptions. Using makeStatefulSubscribable or the corresponding hooks counts as a subscription.

ScannerSubscriptionResult

data
The string data from the last scanner event received.
```
string
```
source
The scanning source from which the scan event came.
```
ScannerSource
```

export interface ScannerSubscriptionResult {
  /** The string data from the last scanner event received. */
  data?: string;
  /** The scanning source from which the scan event came. */
  source?: ScannerSource;
}

ScannerSource

The scanner source the POS device supports.

'camera' | 'external' | 'embedded'

Was this section helpful?

Anchor to examplesExamples

Examples of receiving updates from the Scanner API

Anchor to example-receiving-updates-on-available-scanner-sourcesReceiving updates on available scanner sources

Was this section helpful?

Subscribe to scan event updates

import React from 'react';

import {

Navigator,

Screen,

Stack,

Text,

useScannerDataSubscription,

reactExtension,

} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridModal = () => {

const {data, source} = useScannerDataSubscription();

return (

<Text>{`Scanned data: ${data || ''} with ${source || ''}`}</Text>

</Stack>

</Screen>

</Navigator>

);

};

export default reactExtension('pos.home.modal.render', () => (

));

Examples

Subscribe to scan event updates

React

import React from 'react';
import {
  Navigator,
  Screen,
  Stack,
  Text,
  useScannerDataSubscription,
  reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridModal = () => {
  const {data, source} = useScannerDataSubscription();

  return (
    <Navigator>
      <Screen name="Home" title="Home">
        <Stack direction="horizontal">
          <Text>{`Scanned data: ${data || ''} with ${source || ''}`}</Text>
        </Stack>
      </Screen>
    </Navigator>
  );
};

export default reactExtension('pos.home.modal.render', () => (
  <SmartGridModal />
));

TS

import {
  Navigator,
  Screen,
  Stack,
  Text,
  extension,
} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.modal.render', (root, api) => {
  const dataText = root.createComponent('Text', null, 'Scanned data: ');

  const sourceText = root.createComponent(
    'Text',
    null,
    'Scanned data source: ',
  );

  const stack1 = root.createComponent(Stack, {
    direction: 'horizontal',
  });

  const screen = root.createComponent(Screen, {
    title: 'Home',
    name: 'Home',
  });

  const navigator = root.createComponent(Navigator);

  stack1.append(dataText);
  stack1.append(sourceText);
  screen.append(stack1);
  navigator.append(screen);
  root.append(navigator);

  api.scanner.scannerDataSubscribable.subscribe((data, source) => {
    dataText.replaceChildren(`Scanned data: ${data || ''}`);
    sourceText.updateProps(`Scanned data source: ${source || ''}`);
  });
});

Receiving updates on available scanner sources

React

import React from 'react';
import {
  Navigator,
  Screen,
  Stack,
  Text,
  useScannerSourcesSubscription,
  reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridModal = () => {
  const scannerSources = useScannerSourcesSubscription();

  return (
    <Navigator>
      <Screen name="Home" title="Home">
        <Stack direction="horizontal">
          <Text>{`Available scanner sources: ${scannerSources}`}</Text>
        </Stack>
      </Screen>
    </Navigator>
  );
};

export default reactExtension('pos.home.modal.render', () => (
  <SmartGridModal />
));

TS

import {
  Navigator,
  Screen,
  Stack,
  Text,
  extension,
} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.modal.render', (root, api) => {
  const scannerSourcesText = root.createComponent(
    'Text',
    null,
    'Available scanner sources: ',
  );

  const stack1 = root.createComponent(Stack, {
    direction: 'horizontal',
  });

  const screen = root.createComponent(Screen, {
    title: 'Home',
    name: 'Home',
  });

  const navigator = root.createComponent(Navigator);

  stack1.append(scannerSourcesText);
  screen.append(stack1);
  navigator.append(screen);
  root.append(navigator);

  api.scanner.scannerSourcesSubscribable.subscribe((sources) => {
    scannerSourcesText.replaceChildren(`Available scanner sources: ${sources}`);
  });
});

Anchor to example-use-casesUse cases

Anchor to example-hardware-scanner-exampleHardware scanner example

In this example, assuming a physical scanner is connected to the POS, any scans performed when ui extensions are in use will automatically add the product to the cart if the data exists on the shop.

Anchor to example-conditional-scanner-source-rendering-exampleConditional scanner source rendering example

There might be situations where a developer needs to conditionally render UI elements based on the available scanning sources of the device on which the extension is installed. For example, an extension could be designed for full-screen camera scanning, but a device like POS GO does not have a camera. In such cases, it would be necessary to avoid rendering the camera scanner component and instead create a UI that supports embedded scanning.

Was this section helpful?

Hardware scanner example

import React from 'react';

import {

Navigator,

Screen,

Stack,

Text,

useScannerDataSubscription,

useApi,

reactExtension,

} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridModal = () => {

const api = useApi<'pos.home.modal.render'>();

const {data} = useScannerDataSubscription();

return (

<Text>{`Scanned data: ${data || ''}`}</Text>

</Stack>

</Screen>

</Navigator>

);

};

export default reactExtension('pos.home.modal.render', () => (

));

Examples

Hardware scanner example

Description

In this example, assuming a physical scanner is connected to the POS, any scans performed when ui extensions are in use will automatically add the product to the cart if the data exists on the shop.

React

import React from 'react';
import {
  Navigator,
  Screen,
  Stack,
  Text,
  useScannerDataSubscription,
  useApi,
  reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridModal = () => {
  const api = useApi<'pos.home.modal.render'>();
  const {data} = useScannerDataSubscription();

  return (
    <Navigator>
      <Screen name="Home" title="Home">
        <Stack direction="horizontal">
          <Text>{`Scanned data: ${data || ''}`}</Text>
        </Stack>
      </Screen>
    </Navigator>
  );
};

export default reactExtension('pos.home.modal.render', () => (
  <SmartGridModal />
));

TS

import React from 'react';
import {
  Navigator,
  Screen,
  Stack,
  Text,
  extension,
} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.modal.render', (root, api) => {
  const text = root.createComponent('Text', null, 'Scanned data: ');

  const stack = root.createComponent(Stack, {
    direction: 'horizontal',
  });

  const screen = root.createComponent(Screen, {
    title: 'Home',
    name: 'Home',
  });

  const navigator = root.createComponent(Navigator);

  stack.append(text);
  screen.append(stack);
  navigator.append(screen);
  root.append(navigator);

  api.scanner.scannerDataSubscribable.subscribe((data) => {
    text.replaceChildren(`Scanned data: ${data || ''}`);
  });
});

Conditional scanner source rendering example

Description

There might be situations where a developer needs to conditionally render UI elements based on the available scanning sources of the device on which the extension is installed. For example, an extension could be designed for full-screen camera scanning, but a device like POS GO does not have a camera. In such cases, it would be necessary to avoid rendering the camera scanner component and instead create a UI that supports embedded scanning.

React

import React from 'react';
import {
  CameraScanner,
  Navigator,
  Screen,
  Stack,
  Text,
  useScannerDataSubscription,
  useScannerSourcesSubscription,
  reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridModal = () => {
  const {data, source} = useScannerDataSubscription();
  const availableScanners = useScannerSourcesSubscription();
  const hasCameraScanner = availableScanners.includes('camera');

  return (
    <Navigator>
      <Screen name="Home" title="Home">
        <Stack direction="horizontal">
          {hasCameraScanner ? (
            <CameraScanner />
          ) : (
            <Stack direction="vertical" alignment="space-evenly">
              <Text>{`Scanned data: ${data || ''}`}</Text>
              <Text>{`Scanned data source: ${source || ''}`}</Text>
            </Stack>
          )}
        </Stack>
      </Screen>
    </Navigator>
  );
};

export default reactExtension('pos.home.modal.render', () => (
  <SmartGridModal />
));

TS

import {
  CameraScanner,
  Navigator,
  Screen,
  Stack,
  Text,
  extension,
} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.modal.render', (root, api) => {
  const dataText = root.createComponent('Text', null, 'Scanned data: ');

  const sourceText = root.createComponent(
    'Text',
    null,
    'Scanned data source: ',
  );

  const cameraScanner = root.createComponent(CameraScanner);
  const stack1 = root.createComponent(Stack, {
    direction: 'horizontal',
  });
  const stack2 = root.createComponent(Stack, {
    direction: 'vertical',
    alignment: 'space-evenly',
  });

  const screen = root.createComponent(Screen, {
    title: 'Home',
    name: 'Home',
  });

  const navigator = root.createComponent(Navigator);

  screen.append(stack1);
  navigator.append(screen);
  root.append(navigator);

  api.scanner.scannerDataSubscribable.subscribe((data, source) => {
    dataText.replaceChildren(`Scanned data: ${data || ''}`);
    sourceText.replaceChildren(`Scanned data source: ${source || ''}`);
  });

  api.scanner.scannerSourcesSubscribable.subscribe((sources) => {
    // Clear previous children to avoid duplicate appending
    stack1.children = [];
    stack2.children = [];

    if (sources.include('camera')) {
      stack1.append(cameraScanner);
    } else {
      stack2.append(dataText);
      stack2.append(sourceText);
      stack1.append(stack2);
    }
  });
});

Scanner APIAPIs

Supporting targets

Anchor to scannerapiScannerApi

ScannerSubscriptionResult

ScannerSource

Anchor to examplesExamples

Examples

Subscribe to scan event updates

React

TS

Receiving updates on available scanner sources

React

TS

Anchor to example-use-casesUse cases

Examples

Hardware scanner example

Description

React

TS

Conditional scanner source rendering example

Description

React

TS

Scanner API
APIs