(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Visual Codes Scanner

Overview

• The Visual Codes Scanner Component is a form control for capturing QR codes, barcodes, and other visual code formats.
• It uses the device camera to scan codes directly.
• The component provides a manual input option when scanning is not possible.
• It is useful for inventory management, event check-ins, product authentication, and other quick data capture tasks.

Specs

Tokens

Structure

(Configured in Non-Visual Properties)

• dataField – Defines the field name that will be used when submitting form data. For example, setting to "productBarcode" ensures the scanned code is submitted with this field name in the data object.
• controlsRequestType – Specifies how the field data is sent in HTTP requests: 'BODY', 'HEADER', or 'PATH'. For example, setting to "BODY" includes the field in the request body, which is standard for most form submissions.

(Configured in Visual Properties)

• closeDialogOnSuccess – Controls whether the scanning dialog automatically closes after a successful scan. When set to true, the dialog will close immediately after detecting a valid code, improving the user experience by reducing required steps.
• saveInLocalStorage – Determines whether the scanned value is preserved in the user's local storage between sessions. When enabled, the last scanned value will persist if the user reloads the page, providing a better user experience.
• defaultValue – Sets the initial value that will be used when the form is reset. For example, setting to a sample code like "TEST123456" would pre-fill the field with this value when the form is reset.

Styling

(Configured in Visual Properties)

• labelTranslations – Sets the label text displayed on the scanner button with support for multiple languages. For example, {"en-US": "Scan Code", "de-DE": "Code scannen"} ensures proper localization for international users.
• dialogTitleTranslations – Sets the title text displayed at the top of the scanning dialog with support for multiple languages. For example, {"en-US": "Scan QR Code", "de-DE": "QR-Code scannen"} helps users understand what they are scanning.
• alternativeInputLabelTranslations – Sets the label for the manual input field shown in the dialog with support for multiple languages. For example, {"en-US": "Or type code manually", "de-DE": "Oder Code manuell eingeben"} provides an alternative entry method when scanning isn't working.
• confirmButtonLabelTranslations – Sets the text for the confirmation button in the dialog with support for multiple languages. For example, {"en-US": "Confirm", "de-DE": "Bestätigen"} allows users to submit manually entered codes.

Actions & Variants

(Configured in Events)

• events – Configures the events that the component can trigger and respond to:
• ON_INIT – Triggered when the component is initialized. Can be used to perform setup operations like loading initial configuration.
• ON_DESTROY – Triggered when the component is removed from the DOM. Useful for cleanup operations and releasing resources.
• ON_SCAN_START – Triggered when the user activates the scanner. Can be used to log scanning attempts or prepare related data.
• ON_SCAN_SUCCESS – Triggered when a code is successfully scanned. Can be used to perform immediate actions with the scanned value, such as looking up product information.
• ON_SCAN_ERROR – Triggered when an error occurs during scanning. Can be used to handle exceptions and provide appropriate feedback to users.

(Configured in Visual Properties)

• hidden – Controls whether the component is visible in the form. When set to true, the component remains in the form structure but is not displayed, which is useful for conditional rendering based on other field values.
• readonly – Controls whether the scanner field can be activated by users. When set to true, the field displays its value but the scan button is disabled, which is useful for display-only scenarios.

Tests

(Configured in Testing Hooks)

• dataTestId – Sets the testing hook ID for automated testing. For example, setting it to "product-barcode-scanner" allows test scripts to reliably locate this component.

Authorization

(Configured in Authorization)

• authorizationDisable – Specifies a policy set that determines when the component should be disabled. For example, setting to "readOnlyPolicy" will disable the scanner for users who don't have scan permissions according to the specified policy.

Links

• Figma: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=15534-397394&t=ftfrOGkPzlG2GaTo-1

Guidelines

Usage

• Capture QR/bar/visual codes with a clear CTA. Set the button text via labelTranslations (e.g., “Scan code”).
• Provide a manual fallback in the dialog. Configure alternativeInputLabelTranslations and confirmButtonLabelTranslations.
• Control presence within the form. Toggle visibility using hidden.

States & Feedback

• Display-only mode when editing isn’t allowed. Use readonly to show a value and disable scanning.
• Control completion flow after success. Use closeDialogOnSuccess (true for single scan, false for batches).
• Define reset behavior. Use defaultValue to restore a known value on form reset.

Data-Driven / Conditional Behavior

• Persist—or deliberately don’t. Use saveInLocalStorage for repetitive workflows; leave off for sensitive data.

Visibility & Authorization

• Disable by policy. Apply authorizationDisable to keep the control visible but non-interactive when scanning isn’t permitted.
• Show a value while blocking interaction. Combine readonly with authorizationDisable to communicate state and permissions.

Content & Localization

• Localize all visible strings. Provide labelTranslations, dialogTitleTranslations, alternativeInputLabelTranslations, and confirmButtonLabelTranslations.
• Name the target explicitly. In dialogTitleTranslations, specify the code type (e.g., “Scan QR code”).
• Keep CTA concise. Use short verbs in labelTranslations to reduce truncation.

Dos & Don’ts

Accessibility

• Localized labels and titles. Use labelTranslations and dialogTitleTranslations so assistive tech announces clear actions and context.
• Non-interactive display when needed. Use readonly to prevent scanning while presenting values.
• Predictable completion. Use closeDialogOnSuccess to reduce extra steps when a single scan completes.
• Concise, specific copy. Keep all *Translations short and understandable; avoid jargon.
• No color-only meaning. (No color tokens are exposed.) Ensure clarity via labels and dialog titles.
• Permission clarity. Prefer authorizationDisable to signal disabled state; reserve hidden for cases where the control must not be discoverable.