# Customization ⚙️

## Message Customization

All of the UI widgets are designed to provide helpful messages and status updates to users during the scanning process. To enhance user experience, you can customize these messages to display application-specific text instead of the default message.

#### Default Message Example Image

<div align="center"><figure><img src="https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2FCEvaCleIvlpavvlWU9pg%2Fimage.png?alt=media&#x26;token=09afc5d9-f2be-4af5-92a5-228932d59294" alt=""><figcaption></figcaption></figure></div>

This example image shows the default message displayed on the screen during the card scanning process. You can customize these messages using the available options.

### Available Customization Options

<table><thead><tr><th width="184.33333333333331">State</th><th>Key</th><th>Default Message</th></tr></thead><tbody><tr><td><strong>Auto Start</strong></td><td>autoCaptureTitle</td><td><p>Hold Card in Frame</p><p>It Will Scan Automatically</p></td></tr><tr><td><strong>Manual</strong> <strong>Start</strong></td><td>manualCaptureTitle</td><td>Use camera button to scan card</td></tr><tr><td><strong>Processing</strong></td><td>processingTitle</td><td>Keep Card Still While Scanning</td></tr><tr><td><strong>Manual Processing</strong></td><td>manualProcessingTitle</td><td>Reading card details, one moment...</td></tr><tr><td><strong>Frontside Completed</strong></td><td>frontsideCompletedTitle</td><td><p>Front side scan is complete</p><p>Rotate card to scan back</p></td></tr><tr><td><strong>Completed</strong></td><td>completedTitle</td><td>Card Scanned Successfully</td></tr><tr><td><strong>Retry</strong></td><td>retryTitle</td><td>Scanning Failed - Please Try Again</td></tr><tr><td><strong>Error</strong></td><td>errorTitle</td><td>Setup Failure - Please Reload the Page</td></tr><tr><td><strong>CameraError</strong></td><td>cameraErrorTitle</td><td>Unable to Setup Camera for Capture</td></tr><tr><td><strong>Eligibility Processing</strong></td><td>eligibilityProcessingTitle</td><td>Checking eligibility</td></tr><tr><td><strong>Post Processing</strong></td><td>postProcessingTitle</td><td>Validating Insurance Card...</td></tr><tr><td><strong>Eligibility Error</strong></td><td>eligibilityErrorTitle</td><td>Eligibility Setup Failure</td></tr></tbody></table>

#### Example

Here's an example of how to customize the default message displayed when initiating the scanning process:

{% tabs %}
{% tab title="React" %}

```jsx
const messages = { 
    autoCaptureTitle: "Place card on a well-lit, non-reflective surface to start scanning", 
}

return (
    <CardScanView 
        sessionToken={token}
        onSuccess={cardScanSuccess}
        onCancel={cardScanCancel}
        messages={messages}
    />
);
```

{% endtab %}

{% tab title="React Native" %}

```jsx
const messages = { 
    autoCaptureTitle: "Place card on a well-lit, non-reflective surface to start scanning", 
}

return (
    <CardScanView 
        sessionToken={token}
        onSuccess={cardScanSuccess}
        onCancel={cardScanCancel}
        messages={messages}
    />
);
```

{% endtab %}

{% tab title="Flutter" %}
{% code overflow="wrap" %}

```dart
const messages = CardScanMessages(
  autoCaptureTitle: 'Place card on a well-lit, non-reflective surface to start scanning',
);

CardScanner(
  properties: CardScanConfig(
    sessionToken: sessionToken,
    onSuccess: cardScanSuccess,
    messages: messages,
  ),
);
```

{% endcode %}
{% endtab %}

{% tab title="iOS" %}

```swift
let messages = CardScanMessages(
    autoCaptureTitle: "Place card on a well-lit, non-reflective surface to start scanning"
)

let config = CardScanConfig(
    sessionToken: token,
    onSuccess: onSuccess,
    messages: messages
)

let cardScanViewController = CardScanViewController()
cardScanViewController.config = config
```

{% endtab %}

{% tab title="Android" %}

```kotlin
val messages = CardScanMessages(
    autoCaptureTitle = "Place card on a well-lit, non-reflective surface to start scanning"
)

CardScanConfig(
    sessionToken = token,
    onSuccess = { card -> /* handle success */ },
    messages = messages
)
```

{% endtab %}
{% endtabs %}

Replace the text within the quotes to suit your application's requirements.

<figure><img src="https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2FHBwqvnXnjOxCEBrLflZa%2Fimage.png?alt=media&#x26;token=267d2c8b-c2ce-409f-ab52-db2504ddf35a" alt=""><figcaption></figcaption></figure>

This example image shows the scanning process in action, with the customized `autoCaptureTitle` message displayed on the screen.

### Scanning Process

The chart below illustrates the flow of messages displayed to the user during the card scanning process:

<figure><img src="https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2F3RZYogxFpLGVtvIkNUYQ%2Fimage.png?alt=media&#x26;token=f0135421-ebb2-4474-8969-46a83a381bcd" alt=""><figcaption><p>Scanning Process</p></figcaption></figure>

The diagram shows how the user is guided through the scanning process, starting with the initial instructions for holding the card in the frame, progressing through the processing states, and ultimately either succeeding or requiring a retry or displaying an error.

### Text Size, Text Color, and Background Color

To customize the text size, text color, and background color of the content, you can pass the respective text style and color properties to the CardScanView widget:

{% tabs %}
{% tab title="React" %}

```jsx
<CardScanView 
  sessionToken={token}
  messageFontSize="18px"
  messageTextColor="blue"
  messageBackgroundColor="lightgray"
/>
```

{% endtab %}

{% tab title="React - CSS" %}

```css
/* React Web SDK supports CSS custom properties for message styling */
.cardscan-widget {
  --message-font-size: 18px;
  --message-text-color: blue;
  --message-background-color: lightgray;
  --message-font-family: 'Arial', sans-serif;
  --message-font-weight: 600;
}
```

{% endtab %}

{% tab title="React Native" %}

```jsx
<CardScanView 
  sessionToken={token}
  messageStyle={{
    fontSize: 18,
    color: "blue",
    backgroundColor: "lightgray"
  }}
/>
```

{% endtab %}

{% tab title="Flutter" %}

```dart
CardScanner(
  properties: CardScanConfig(
    sessionToken: sessionToken,
    onSuccess: cardScanSuccess,
    messageStyle: TextStyle(
      fontSize: 18.0,
      color: Colors.blue,
      backgroundColor: Colors.grey,
    ),
    messages: messages,
  ),
);
```

{% endtab %}

{% tab title="iOS" %}

```swift
let messageStyle = MessageStyle(
    fontSize: 18.0,
    textColor: UIColor.blue,
    backgroundColor: UIColor.lightGray
)

let config = CardScanConfig(
    sessionToken: token,
    onSuccess: onSuccess,
    messageStyle: messageStyle
)

let cardScanViewController = CardScanViewController()
cardScanViewController.config = config
```

{% endtab %}

{% tab title="Android" %}

```kotlin
CardScanConfig(
    sessionToken = token,
    messageFontSize = 18.0f,
    messageTextColor = Color.BLUE,
    messageBackgroundColor = Color.LTGRAY
)
```

{% endtab %}
{% endtabs %}

This example changes the text size to 18px, the text color to blue, and the background color to gray.

## UX Customization

This documentation section provides guidelines on how to customize the user experience of the card scanning component, focusing on visual aspects such as the auto/manual toggle switch color, progress bar color, and widget background color. The examples below demonstrate how to adjust these elements to match your application's branding or theme.

### Auto/Manual Toggle Switch Color

The auto/manual toggle switch allows users to switch between automatic and manual scanning modes. You can change its colors to match your application's design.

![](https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2Fuk2TDgDqPkt22fjUxKW2%2Fimage.png?alt=media\&token=50f186a3-ff9a-4373-a275-705a5fefd10e) ![](https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2FDcIcpkfVsAxqlqnMtgau%2Fimage.png?alt=media\&token=80714795-c977-400d-9fcb-86a555c0caff)

To change the colors of the auto/manual toggle switch, use the following props:

* `autoSwitchActiveColor` - sets the color of the active switch
* `autoSwitchInactiveColor` - sets the color of the inactive switch

Here's an example of how to set the active switch color to blue and the inactive switch color to grey:

{% tabs %}
{% tab title="React" %}

```jsx
<CardScanView 
  sessionToken={token}
  onSuccess={cardScanSuccess}
  onCancel={cardScanCancel}
  autoSwitchActiveColor="blue"
  autoSwitchInactiveColor="grey"
/>
```

{% endtab %}

{% tab title="React - CSS" %}

```css
/* React Web SDK supports CSS customization */
.cardscan-widget {
  --auto-switch-active-color: blue;
  --auto-switch-inactive-color: grey;
}
```

{% endtab %}

{% tab title="React Native" %}

```jsx
<CardScanView 
  sessionToken={token}
  onSuccess={cardScanSuccess}
  onCancel={cardScanCancel}
  autoSwitchActiveColor="blue"
  autoSwitchInactiveColor="grey"
/>
```

{% endtab %}

{% tab title="Flutter" %}

```dart
CardScanner(
  properties: CardScanConfig(
    sessionToken: sessionToken,
    onSuccess: cardScanSuccess,
    autoSwitchActiveColor: Colors.blue,
    autoSwitchInactiveColor: Colors.grey,
  ),
);
```

{% endtab %}

{% tab title="iOS" %}

```swift
let config = CardScanConfig(
    sessionToken: token,
    onSuccess: onSuccess,
    autoSwitchActiveColor: UIColor.blue,
    autoSwitchInactiveColor: UIColor.lightGray
)
```

{% endtab %}

{% tab title="Android" %}

```kotlin
CardScanConfig(
    sessionToken = token,
    autoSwitchActiveColor = Color.BLUE,
    autoSwitchInactiveColor = Color.LTGRAY
)
```

{% endtab %}
{% endtabs %}

### Progress Bar Color

The progress bar provides visual feedback to users during the scanning process, indicating the current progress and scanning state (automatic vs manual).

<figure><img src="https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2FhGQrw8oH09RyfcJKA6g9%2Fimage.png?alt=media&#x26;token=1e12a72e-797d-4325-8237-9b3e8b322792" alt=""><figcaption></figcaption></figure>

To change the color of the progress bar, use the `progressBarColor` prop:

{% tabs %}
{% tab title="React" %}

```jsx
<CardScanView 
  sessionToken={token}
  onSuccess={cardScanSuccess}
  onCancel={cardScanCancel}
  progressBarColor="red"
/>
```

{% endtab %}

{% tab title="React - CSS" %}

```css
/* React Web SDK supports CSS customization */
.cardscan-widget {
  --progress-bar-color: red;
}
```

{% endtab %}

{% tab title="React Native" %}

```jsx
<CardScanView 
  sessionToken={token}
  onSuccess={cardScanSuccess}
  onCancel={cardScanCancel}
  progressBarColor="red"
/>
```

{% endtab %}

{% tab title="Flutter" %}

```dart
CardScanner(
  properties: CardScanConfig(
    sessionToken: sessionToken,
    onSuccess: cardScanSuccess,
    progressBarColor: Colors.red,
  ),
);
```

{% endtab %}

{% tab title="iOS" %}

```swift
let config = CardScanConfig(
    sessionToken: token,
    onSuccess: onSuccess,
    progressBarColor: UIColor.red
)
```

{% endtab %}

{% tab title="Android" %}

```kotlin
CardScanConfig(
    sessionToken = token,
    progressBarColor = Color.RED
)
```

{% endtab %}
{% endtabs %}

In this example, the progress bar color is set to red, replace `red` with the desired color.

### Widget Background Color

The widget background color can be customized to seamlessly integrate the component with your application's design.

<figure><img src="https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2FCnOvN3zn3cMwXxqLpfCg%2Fimage.png?alt=media&#x26;token=acdd2578-a5ee-4f7b-9658-dfd82bfb39c5" alt=""><figcaption></figcaption></figure>

\
To change the background color of the UI widget, use the `widgetBackgroundColor` prop:

{% tabs %}
{% tab title="React" %}

```jsx
<CardScanView 
  sessionToken={token}
  onSuccess={cardScanSuccess}
  onCancel={cardScanCancel}
  widgetBackgroundColor="#f0f0f0"
/>
```

{% endtab %}

{% tab title="React - CSS" %}

```css
/* React Web SDK supports CSS customization */
.cardscan-widget {
  --widget-background-color: #f0f0f0;
}
```

{% endtab %}

{% tab title="React Native" %}

```jsx
<CardScanView 
  sessionToken={token}
  onSuccess={cardScanSuccess}
  onCancel={cardScanCancel}
  widgetBackgroundColor="#f0f0f0"
/>
```

{% endtab %}

{% tab title="Flutter" %}

```dart
CardScanner(
  properties: CardScanConfig(
    sessionToken: sessionToken,
    onSuccess: cardScanSuccess,
    widgetBackgroundColor: Color(0xFFF0F0F0),
  ),
);
```

{% endtab %}

{% tab title="iOS" %}

```swift
let config = CardScanConfig(
    sessionToken: token,
    onSuccess: onSuccess,
    widgetBackgroundColor: UIColor(hex: "#f0f0f0")
)
```

{% endtab %}

{% tab title="Android" %}

```kotlin
CardScanConfig(
    sessionToken = token,
    widgetBackgroundColor = Color.parseColor("#f0f0f0")
)
```

{% endtab %}
{% endtabs %}

Replace `Color(0xFFF0F0F0)` with the desired background color.

By customizing these visual aspects, you can provide a consistent user experience that aligns with your application's overall design and branding.

### Success Indicator

After successful scanning and processing of the insurance card, the UI widget will display a checkmark icon in the center of the bounding box.

The indicator can be replaced by passing a `ReactNode` into the `successIndicator` prop.

**Note:** Currently only supported by the React UI Widget

<figure><img src="https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2FrgqTIkb66jhHOLAvFMtH%2Fimage.png?alt=media&#x26;token=dba9615f-e7d6-4881-92ef-60338996d018" alt=""><figcaption><p>Successful Scan UI</p></figcaption></figure>

Here's an example of how to create a custom success indicator using an SVG checkmark icon and a message:

```jsx
import { ReactComponent as CheckmarkIcon } from './checkmark-icon.svg';

<CardScanView
  sessionToken={token}
  onSuccess={cardScanSuccess}
  onCancel={cardScanCancel}
  successIndicator={<CheckmarkIcon />}
/>
```

### Error Indicator

If a system error occurs during card processing the react widget will display an error icon in the center of the bounding box.

The indicator can be replaced by passing a `ReactNode` into the `errorIndicator` prop.

**Note:** Currently only supported by the React UI Widget

![](https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2F4UebL8KkOebek4Neqz3q%2Fimage.png?alt=media\&token=caf5ea2a-1cf0-4ce6-b96e-7521c6677d8f)

Here's an example of how to create a custom error indicator using an SVG error icon and a message:

```jsx
import { ReactComponent as ErrorIcon } from './error-icon.svg';

<CardScanView
  sessionToken={token}
  onSuccess={cardScanSuccess}
  onCancel={cardScanCancel}
  content={customizedContent}
  errorIndicator={<ErrorIcon />}
/>

```

### Close Button

The close button is displayed in the top right-hand corner of the react widget. When touched or clicked it will stop the camera stream, clean up the component, and then call the `onCancel` handler.

**Note:** Currently only supported by the React UI Widget

![](https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2FbhdGBljUnzKeCY9SuLLu%2Fimage.png?alt=media\&token=a9a74618-bdea-44ed-9885-0493d158fea6)

The close button can be replaced by passing a `ReactNode` into the `closeButton` prop.

```jsx
const customCloseButton = () => {
    return (
      <button type="button"  className="btn btn-secondary">Close</button>
    )
  };
  
<CardScanView 
  sessionToken={token}
  onSuccess={cardScanSuccess}
  onCancel={cardScanCancel}
  closeButton={customCloseButton()}
/>
```

## React Web SDK - Complete CSS Customization

The React web SDK (`@cardscan.ai/insurance-cardscan-react`) supports comprehensive CSS customization through CSS custom properties (CSS variables). You can override any of these variables to match your application's design system.

### Complete CSS Variables Reference

```css
/* Main widget container */
.cardscan-widget {
  /* Message styling */
  --message-font-size: 16px;
  --message-text-color: #333333;
  --message-background-color: rgba(255, 255, 255, 0.9);
  --message-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
  --message-font-weight: 500;
  --message-border-radius: 8px;
  --message-padding: 12px 16px;
  
  /* Auto/Manual toggle switch */
  --auto-switch-active-color: #007bff;
  --auto-switch-inactive-color: #6c757d;
  --auto-switch-background-color: #ffffff;
  --auto-switch-border-color: #dee2e6;
  --auto-switch-border-radius: 20px;
  
  /* Progress bar */
  --progress-bar-color: #28a745;
  --progress-bar-background-color: #e9ecef;
  --progress-bar-height: 4px;
  --progress-bar-border-radius: 2px;
  
  /* Widget background and layout */
  --widget-background-color: #000000;
  --widget-border-radius: 12px;
  --widget-padding: 20px;
  --widget-min-height: 400px;
  
  /* Camera preview */
  --camera-preview-border-color: #ffffff;
  --camera-preview-border-width: 2px;
  --camera-preview-border-radius: 8px;
  
  /* Buttons */
  --button-primary-background: #007bff;
  --button-primary-color: #ffffff;
  --button-primary-border-radius: 6px;
  --button-primary-padding: 10px 20px;
  --button-primary-font-weight: 600;
  
  --button-secondary-background: #6c757d;
  --button-secondary-color: #ffffff;
  --button-secondary-border-radius: 6px;
  
  /* Success/Error indicators */
  --success-indicator-color: #28a745;
  --success-indicator-size: 48px;
  --error-indicator-color: #dc3545;
  --error-indicator-size: 48px;
  
  /* Loading spinner */
  --loading-spinner-color: #007bff;
  --loading-spinner-size: 32px;
  
  /* Close button */
  --close-button-color: #ffffff;
  --close-button-background: rgba(0, 0, 0, 0.5);
  --close-button-size: 32px;
  --close-button-border-radius: 50%;
}
```

### Usage Examples

#### Matching Your Brand Colors

```css
.cardscan-widget {
  --auto-switch-active-color: #ff6b35;  /* Your brand primary */
  --progress-bar-color: #ff6b35;
  --button-primary-background: #ff6b35;
  --success-indicator-color: #00c851;   /* Your success color */
}
```

#### Dark Theme Support

```css
.cardscan-widget.dark-theme {
  --widget-background-color: #1a1a1a;
  --message-text-color: #ffffff;
  --message-background-color: rgba(0, 0, 0, 0.7);
  --camera-preview-border-color: #666666;
  --auto-switch-active-color: #4dabf7;
}
```

#### Minimal/Clean Style

```css
.cardscan-widget.minimal {
  --widget-padding: 10px;
  --widget-border-radius: 0;
  --message-background-color: transparent;
  --camera-preview-border-width: 1px;
  --button-primary-border-radius: 0;
}
```

{% hint style="info" %}
**Are we missing something?** Please let us know and we would be happy to add it. Contact [support](mailto:support@cardscan.ai).
{% endhint %}