---
Source: https://docs.microblink.com/blinkcard/customize-ui
Title: Customize the scanning UI
Description: Configure the BlinkCard camera UI buttons, onboarding, help tooltips, and instruction text
---
# Customize the scanning UI
The BlinkCard scanning UI is configurable on every platform.
On the web, the UI is configured through two option groups passed to `createBlinkCard`:
- `feedbackUiOptions`: the scanning feedback layer (onboarding, help, timeout modal, instruction text)
- `cameraManagerUiOptions`: the camera controls (torch, close, mirror buttons, and layering)
On Android and iOS, the UI is configured through settings objects passed to the scanning entry point.
## Where the UI is mounted (web)
By default the UI mounts full-screen into `document.body`.
To embed it inside your own layout, pass `targetNode`:
```ts
const blinkCard = await createBlinkCard({
licenseKey: "your-license-key",
targetNode: document.getElementById("scanner-container") ?? undefined,
});
```
When you provide a `targetNode`, the UI fills that element instead of the whole screen, so it sits within your page's branding.
## Onboarding and help
Toggle the onboarding guide shown before scanning starts and the help button shown during scanning.
On the web, these live in `feedbackUiOptions`, passed to `createBlinkCard`.
```ts
const blinkCard = await createBlinkCard({
licenseKey: "your-license-key",
feedbackUiOptions: {
showOnboardingGuide: false,
showHelpButton: false,
showTimeoutModal: true,
helpTooltipShowDelay: 5000,
helpTooltipHideDelay: 5000,
},
});
```
- `showOnboardingGuide`: show the onboarding guide before scanning starts (default `true`)
- `showHelpButton`: show the help button (default `true`)
- `helpTooltipShowDelay`: milliseconds before the help tooltip appears automatically, or `null` to never auto-show (default `5000`)
- `helpTooltipHideDelay`: milliseconds before the help tooltip auto-hides, or `null` to never auto-hide (default `5000`)
- `showTimeoutModal`: show the modal when scanning times out (default `true`)
On Android, the onboarding dialog and help button are part of `UiSettings`, passed to `BlinkCardCameraScanningScreen` via its `uiSettings` parameter.
```kotlin
BlinkCardCameraScanningScreen(
blinkCardSdk = blinkCardSdk,
uiSettings = UiSettings(
showOnboardingDialog = false,
showHelpButton = false,
),
onScanningSuccess = { result -> /* handle result */ },
onScanningCanceled = { /* handle cancel */ },
)
```
- `showOnboardingDialog`: show an onboarding dialog at the beginning of the scanning session (default `true`)
- `showHelpButton`: show the help button and enable help screens during scanning (default `true`)
On iOS, these are part of `ScanningUXSettings`, passed to `BlinkCardUXModel(analyzer:uxSettings:)`.
```swift
let uxSettings = ScanningUXSettings(
showIntroductionAlert: false,
showHelpButton: false
)
let blinkCardUXModel = BlinkCardUXModel(analyzer: analyzer, uxSettings: uxSettings)
```
- `showIntroductionAlert`: show the alert displayed when scanning starts (default `true`)
- `showHelpButton`: show the help button that raises an onboarding sheet (default `true`)
## Camera controls
On the web, the camera controls live in `cameraManagerUiOptions`.
```ts
const blinkCard = await createBlinkCard({
licenseKey: "your-license-key",
cameraManagerUiOptions: {
showTorchButton: true,
showCloseButton: true,
showMirrorCameraButton: false,
showCameraErrorModal: true,
},
});
```
- `showTorchButton`: show the torch (flashlight) toggle when the device supports it (default `true`)
- `showCloseButton`: show the close button (default `true`)
- `showMirrorCameraButton`: show the mirror-camera button (default `false`)
- `showCameraErrorModal`: show a modal on camera errors such as denied permission (default `true`)
- `zIndex`: the stacking order when the UI renders as a full-screen overlay (only applies when no `targetNode` is set)
On Android, the scanning UX behavior is configured through `BlinkCardUxSettings`, passed to `BlinkCardCameraScanningScreen` via its `uxSettings` parameter.
```kotlin
BlinkCardCameraScanningScreen(
blinkCardSdk = blinkCardSdk,
uxSettings = BlinkCardUxSettings(
stepTimeoutDuration = 15000.milliseconds,
allowHapticFeedback = true,
),
onScanningSuccess = { result -> /* handle result */ },
onScanningCanceled = { /* handle cancel */ },
)
```
- `stepTimeoutDuration`: duration of the scanning session before a timeout is triggered; resets when scanning is paused, such as on dialogs or a side change (default 15 seconds)
- `allowHapticFeedback`: whether haptic feedback is played during scanning (default `true`)
Visual aspects of the camera UI, such as the color scheme, typography, and help-button colors, are configured through `UiSettings`.
See the [BlinkCard Android repository](https://github.com/microblink/blinkcard-android) for the full set of theming options.
On iOS, camera behavior is configured through `ScanningUXSettings`.
```swift
let uxSettings = ScanningUXSettings(
preferredCameraPosition: .back,
allowHapticFeedback: true
)
let blinkCardUXModel = BlinkCardUXModel(analyzer: analyzer, uxSettings: uxSettings)
```
- `preferredCameraPosition`: the preferred camera position to use when capturing the document, `.back` or `.front` (default `.back`)
- `allowHapticFeedback`: whether haptic feedback is played for scanning-related events, such as detection updates or toggling the flashlight (default `true`)
## Customize the instruction text
On the web, both option groups accept `localizationStrings` to override the on-screen messages.
Pass only the keys you want to change; the rest fall back to the built-in copy.
```ts
const blinkCard = await createBlinkCard({
licenseKey: "your-license-key",
feedbackUiOptions: {
localizationStrings: {
flip_card: "Turn the card over",
},
},
});
```
To translate the whole UI into another language, override the full set of strings.
The SDK ships with several built-in locales; see [Supported languages](./supported-languages.md).
## Related articles
- [Scan a card via camera](./scan-camera.md)
- [Supported languages](./supported-languages.md)
Last updated on Aug 11, 2026