ViewConfig Reference

This reference provides complete documentation for the ViewConfig object, which controls the visual appearance and behavior of the Anyline Web SDK scanning interface.

Overview

The ViewConfig defines all visual aspects of the scanning experience:

  • Cutout area: The scanning region where the SDK processes frames

  • Visual feedback: Real-time animations and indicators during scanning

  • UI guidance: Dynamic and static user instructions

  • Overlay styling: Background overlay appearance

ViewConfig Structure

interface ViewConfig {
  // Global overlay styling
  outerColor?: string;                        // 6-digit hex RGB without # (e.g., '000000')
  outerAlpha?: number;                        // Overlay opacity 0-1

  // Cutout stroke animation style
  feedbackAnimationStyle?: 'blink' | 'path';  // Default: 'blink'

  // Legacy/global feedback fields (see notes below)
  feedbackStyle?: string;
  animation?: string;

  // Cutout definitions (required when no preset is used)
  cutouts?: ICutout[];                        // Array of scanning areas

  // User guidance
  uiFeedback?: {
    dynamic?: UiFeedbackConfig;
    static?: {
      instructionText: string;
    };
  };
}

If you use a preset, cutouts are provided by the preset. When no preset is used, at least one cutoutConfig must be defined in viewConfig.cutouts.

Global Overlay Properties

outerColor

Hex color code for the overlay surrounding the cutout area (6-digit RGB, without '#' prefix). Transparency is controlled by outerAlpha.

viewConfig: {
  outerColor: '000000'   // Black overlay
}

Common choices include 'FFFFFF' for a light overlay or '1A1A1A' for a dark gray shade. Remember to omit the # prefix.

outerAlpha

Opacity of the overlay from 0 (transparent) to 1 (opaque).

viewConfig: {
  outerAlpha: 0.5   // 50% transparent
}

Increase the value towards 1 for a more opaque overlay, or lower it towards 0 to expose more of the camera feed.

feedbackAnimationStyle

Controls how the cutout border animates during scanning. This affects the stroke/outline of the scanning area itself.

This is different from scanFeedback.animation, which controls the visual feedback indicator shown when content is detected within the cutout. See Scan Feedback Configuration for details.

 
viewConfig: {
  feedbackAnimationStyle: 'blink'  // or 'path'
}

Options:

  • 'blink' (default): The cutout border blinks to indicate active scanning

  • 'path': An animated path travels along the cutout border outline

feedbackStyle

This field is accepted but is not applied to cutouts by the current Web SDK renderer. Use per-cutout scanFeedback.style instead.

animation

This field is accepted but is not applied to cutouts by the current Web SDK renderer. Use per-cutout scanFeedback.animation instead.

Cutout Configuration

The cutout defines the scanning area. If defined, the cutouts array must contain at least one cutout configuration. Otherwise, we provide default cutout configurations for each preset.

ICutout Structure

interface ICutout {
  cutoutConfig: {
    // Position
    alignment?: 'top' | 'top_half' | 'center' | 'bottom_half' | 'bottom';
    offset?: { x: number; y: number };

    // Size
    width?: number;
    height?: number;
    ratioFromSize?: { width: number; height: number };
    maxWidthPercent?: string;
    maxHeightPercent?: string;

    // Visual styling
    style?: 'rect' | 'contour_rect';
    strokeColor?: string;
    inactiveStrokeColor?: string;
    strokeWidth?: number;
    cornerRadius?: number;
    feedbackStrokeColor?: string;

    // Animation
    animation?: string;
    delay?: number;

    // Reserved (not applied to the overlay in the Web SDK)
    outerColor?: string;
    outerAlpha?: number;

    // Cropping
    cropOffset?: { x: number; y: number };
    cropPadding?: { x: number; y: number };
  };

  scanFeedback?: {
    // Visual feedback during scanning
    style?:
      | 'rect'
      | 'contour_rect'
      | 'contour_point'
      | 'contour_underline';
    animation?:
      | 'none'
      | 'blink'
      | 'pulse'
      | 'kitt'
      | 'traverse_multi'
      | 'traverse_single'
      | 'resize'
      | 'resize_point'
      | 'resize_underline';
    animationDuration?: number;
    timeout?: number;

    // Styling
    strokeWidth?: number;
    strokeColor?: string;
    fillColor?: string;
    cornerRadius?: number;
  };
}

Cutout Position

alignment

Vertical alignment of the cutout within the viewport.

cutoutConfig: {
  alignment: 'center'  // Options: 'top', 'top_half', 'center', 'bottom_half', 'bottom'
}

Options:

  • 'top': Positioned at the top of the viewport

  • 'top_half' (default): Positioned in the upper half of the viewport

  • 'center': Centered vertically in the viewport

  • 'bottom_half': Positioned in the lower half of the viewport

  • 'bottom': Positioned at the bottom of the viewport

offset

Fine-tune cutout position with pixel offsets from the alignment point.

cutoutConfig: {
  alignment: 'center',
  offset: { x: 0, y: -50 }  // Move 50px up from center
}

Properties:

  • x: Horizontal offset in pixels (positive = right, negative = left)

  • y: Vertical offset in pixels (positive = down, negative = up)

Cutout Size

width and height

Absolute dimensions in pixels.

cutoutConfig: {
  width: 1000,   // 1000px wide
  height: 600    // 600px tall
}

ratioFromSize

Define aspect ratio for responsive sizing.

cutoutConfig: {
  ratioFromSize: {
    width: 16,   // 16:9 aspect ratio
    height: 9
  }
}

Use ratioFromSize with maxWidthPercent and maxHeightPercent for responsive cutouts that adapt to different screen sizes.

maxWidthPercent and maxHeightPercent

Maximum dimensions as percentage of viewport.

cutoutConfig: {
  ratioFromSize: { width: 16, height: 9 },
  maxWidthPercent: '80%',   // Max 80% of viewport width
  maxHeightPercent: '50%'   // Max 50% of viewport height
}

Responsive sizing strategy:

  1. width and height are capped by maxWidthPercent and maxHeightPercent

  2. If ratioFromSize is set, the longer dimension is reduced to preserve the ratio

// Example: Responsive barcode scanner
cutoutConfig: {
  alignment: 'center',
  ratioFromSize: { width: 16, height: 9 },
  width: 1000,              // Fallback absolute width
  maxWidthPercent: '90%',   // Max 90% of screen width
  maxHeightPercent: '60%'   // Max 60% of screen height
}

Cutout Visual Styling

style

Cutout border style.

cutoutConfig: {
  style: 'rect'  // or 'contour_rect'
}

Options:

  • 'rect': Standard rectangular border

  • 'contour_rect': Rounded/contoured rectangular border

strokeColor

Color of the cutout border. Accepts 6-digit RGB ('FFFFFF') or 8-digit ARGB ('FF00FF00' for opaque green) hex values without # prefix.

cutoutConfig: {
  strokeColor: '00FF00'  // Green border
}

inactiveStrokeColor

Border color when scanning is inactive or paused.

cutoutConfig: {
  strokeColor: '00FF00',          // Green when active
  inactiveStrokeColor: 'AAAAAA'   // Gray when inactive
}

strokeWidth

Border thickness in pixels.

cutoutConfig: {
  strokeWidth: 3  // Border thickness in pixels
}

cornerRadius

Border corner rounding in pixels.

cutoutConfig: {
  cornerRadius: 5  // Corner rounding in pixels (0 = sharp corners)
}

feedbackStrokeColor

Border color during successful scan feedback.

cutoutConfig: {
  strokeColor: 'FFFFFF',          // White normally
  feedbackStrokeColor: '00FF00'   // Green on success
}

delay

Delay (in seconds) before the cutout stroke animation starts when inactiveStrokeColor is set.

cutoutConfig: {
  delay: 0.5  // Delay in seconds
}

The cutout still renders immediately; this only delays the stroke animation that transitions from inactiveStrokeColor to strokeColor.

Cutout Cropping

Control how the captured image is cropped relative to the cutout.

cropOffset

Shift the crop area relative to the cutout position.

cutoutConfig: {
  cropOffset: { x: 10, y: -5 }  // Shift crop area 10px right, 5px up
}

cropPadding

Add padding around the cutout when cropping the result image.

cutoutConfig: {
  cropPadding: { x: 20, y: 20 }  // Add 20px padding on all sides
}

cropOffset and cropPadding adjust the cutout region used for processing and the positioning of scan feedback overlays; they do not change the visual cutout outline.

Scan Feedback Configuration

Real-time visual feedback during scanning, nested within each cutout.

Basic Configuration

scanFeedback: {
  style: 'rect',                   // Visual style
  animation: 'traverse_multi',     // Animation type
  animationDuration: 300,          // Animation speed (ms)
  timeout: 2000,                   // How long to display (ms)

  strokeWidth: 3,
  strokeColor: '00FF00',           // Feedback color
  fillColor: '3300FF00',           // 20% alpha (ARGB)
  cornerRadius: 5
}

style

Visual style of the scan feedback indicator. Defaults to 'contour_point' when omitted.

scanFeedback: {
  style: 'rect'
}

Options:

  • 'rect': Standard rectangular feedback

  • 'contour_rect': Rounded contour feedback

  • 'contour_point': Single point indicator (default)

  • 'contour_underline': Underline indicator

animation

Animation type for the scan feedback indicator - the visual element shown when content is detected within the cutout. For 'rect' and 'contour_rect' styles, animations are ignored.

This is different from feedbackAnimationStyle, which controls how the cutout border itself animates. See feedbackAnimationStyle for details.

 
scanFeedback: {
  animation: 'traverse_multi'
}

Options:

  • 'none': No animation

  • 'blink': Blink in/out

  • 'pulse': Pulse opacity

  • 'kitt': Back-and-forth sweep

  • 'traverse_multi': Multi-point sweep

  • 'traverse_single': Single-point sweep

  • 'resize': Resize effect (only for 'contour_point'/'contour_underline')

  • 'resize_point': Resize effect for points

  • 'resize_underline': Resize effect for underlines

The traverse_multi animation creates an animated line traversing the scan area during scanning.

animationDuration

Animation speed in milliseconds.

scanFeedback: {
  animation: 'traverse_multi',
  animationDuration: 250  // Fast animation
}

Lower values result in faster animations. Presets typically use 250 ms.

timeout

Duration to display feedback after successful scan (milliseconds).

scanFeedback: {
  timeout: 1500  // Show feedback for 1.5 seconds
}

strokeColor and fillColor accept 6-digit RGB or 8-digit ARGB hex values (AARRGGBB), without a # prefix.

Sensory Feedback

The beepOnResult, vibrateOnResult, and blinkAnimationOnResult properties that exist in our Mobile SDK ScanView configurations are not implemented in the Web SDK.

For limited sensory feedback on successful scans, use the root-level init parameters instead:

const anyline = init({
  hapticFeedback: true,   // Audio + haptic feedback on result
  flashOnResult: true,    // Visual screen blink on result (all platforms)
  // ... other config
});

See hapticFeedback and flashOnResult in the API Reference for details.

UI Feedback Configuration

UI feedback elements enhance the scanning experience by informing the user about environmental conditions detected during scanning. Incorporating visual cues (such as images or text) next to the cutout within the scan view can guide the user on how or what to scan.

For complete documentation on static instructions, dynamic feedback presets, and custom configurations, see UI Feedback.

See Also