> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/react-native/document-smart-capture/image-customization.md).

# Image Customization

Replace the artwork Smart Capture renders: camera chrome, navigation and action icons, status icons, camera help illustrations, and the animated instruction sequences.

{% hint style="warning" %}
In React Native:

* Android: add a drawable with the same resource name in `android/app/src/main/res/drawable/`. `imageCustomization` on `CerttaSmartCaptureConfiguration` is ignored.
* iOS: pass URI strings in TypeScript (`imageCustomization` on `open()`). Resolve bundled assets with `Image.resolveAssetSource(require(...)).uri`.
  {% endhint %}

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

### Overview

Every icon and illustration in the Smart Capture flow is a normal Android drawable with a fixed resource ID. To replace one, declare a drawable with the same name in the React Native Android app module:

`android/app/src/main/res/drawable/`\
or a qualifier variant such as `android/app/src/main/res/drawable-night/`.

Your app’s resource wins at build time. No runtime API — `imageCustomization` on the TypeScript config does nothing on Android.

Resource IDs are internal to the current native SDK version and may change between releases. Re-check this list after upgrading.

Sizes: match the size listed for each drawable. Vectors keep their size in dp, and `.webp` images should keep the aspect ratio (export at the same). Shapes have no fixed size: they stretch to fit their view.

The resource type must match (a drawable overrides a drawable). The file extension does not: you can override an XML vector with a `.webp`/`.png` as long as the name is the same.

### API

| Mechanism                  | Where                                | Description                                           |
| -------------------------- | ------------------------------------ | ----------------------------------------------------- |
| Drawable resource override | `android/app/src/main/res/drawable/` | File (or XML) whose resource name matches the SDK ID. |

When you don’t declare a given name, the SDK uses its own artwork.

android/app/src/main/res/drawable/certta\_sc\_arrow\_left.pngandroid/app/src/main/res/drawable/certta\_sc\_ic\_help.xml

### Adding your images

1. Place the file under `drawable/` (or `drawable-night/`, `drawable-hdpi/`, …).
2. Use the exact resource name from the tables below (no `ic_` prefix unless the SDK already has one).
3. Rebuild the app. Your drawable replaces the SDK default automatically.

Partial overrides are supported: replace only the slots you care about.

### Resolution order

For each drawable:

1. Your app’s drawable with that resource ID (including the best matching qualifier).
2. The SDK’s bundled drawable.

Dark mode: use `drawable-night/` if you need a different graphic. Android resolves appearance from resource qualifiers, not from TypeScript.

### Buttons and controls

| Resource ID                         | Format          | Size             | Used for                                |
| ----------------------------------- | --------------- | ---------------- | --------------------------------------- |
| `certta_sc_camera_button_enabled`   | Vector          | 71×71 dp         | Shutter — enabled                       |
| `certta_sc_camera_button_disabled`  | Vector          | 71×71 dp         | Shutter — disabled                      |
| `certta_sc_camera_button_pressed`   | Vector          | 71×71 dp         | Shutter — pressed                       |
| `certta_sc_camera_button_selector`  | State list      | 71×71 dp         | Combines the three shutter states       |
| `certta_sc_button_close_enabled`    | Vector          | 40×40 dp         | Close (“X”) — enabled                   |
| `certta_sc_button_closed_pressed`   | Vector          | 36×36 dp         | Close — pressed (intentionally smaller) |
| `certta_sc_close_button_selector`   | State list      | 40×40 / 36×36 dp | Combines the close button states        |
| `certta_sc_close_icon`              | Vector          | 12×12 dp         | Close (“X”) glyph                       |
| `certta_sc_arrow_left`              | Vector          | 32×32 dp         | Back navigation                         |
| `certta_sc_eye`                     | Vector          | 44×44 dp         | “View file” on Upload                   |
| `certta_sc_trash`                   | Vector          | 48×48 dp         | Delete an uploaded file                 |
| `certta_sc_ic_help`                 | Vector          | 48×48 dp         | Help (“?”) on camera and permission     |
| `certta_sc_ic_checkmark_small`      | Vector          | 17×17 dp         | Small checkmark                         |
| `certta_sc_ic_loading_spin`         | Vector          | 90×90 dp         | Static spinner                          |
| `certta_sc_loading_animated_vector` | Animated vector | 90×90 dp         | Animated spinner                        |
| `certta_sc_dot_selector`            | State list      | 12×12 dp         | Page indicator on instructions          |

### Backgrounds and containers

These shapes stretch to fill their view. Change shape, radius or stroke instead of matching a size. Some borders follow color resources (see Color Customization).

| Resource ID                                  | Format | Size                 | Used for                                                                      |
| -------------------------------------------- | ------ | -------------------- | ----------------------------------------------------------------------------- |
| `certta_sc_primary_button_background`        | Shape  | Adapts               | Primary (filled) button                                                       |
| `certta_sc_secondary_button_background`      | Shape  | Adapts (1 dp stroke) | Secondary (outline) button. Border follows `certta_sc_accent`                 |
| `certta_sc_attach_button_background`         | Shape  | Adapts (2 dp dashed) | “Attach document” on Upload. Border follows `certta_sc_accent`                |
| `certta_sc_preview_retake_button_background` | Shape  | Adapts (1 dp stroke) | “Take another picture” on Preview. Border follows `certta_sc_secondary_color` |
| `certta_sc_bottom_sheet_background`          | Shape  | Adapts               | Bottom sheet. Fill follows `certta_sc_dialog_background_color`                |
| `certta_sc_bottom_sheet_drag_handle`         | Shape  | Adapts               | Drag handle on bottom sheets                                                  |
| `certta_sc_camera_error_background_drawable` | Shape  | Adapts (1 dp stroke) | In-camera error banners. Fill/border follow warning colors                    |
| `certta_sc_instructions_hint_background`     | Shape  | Adapts               | Instruction hint chips                                                        |
| `certta_sc_validation_type_card_background`  | Shape  | Adapts (2 dp stroke) | Validation method cards. Border follows `certta_sc_dialog_border_color`       |

### Screen-specific icons and illustrations

| Resource ID                        | Format        | Size       | Used for                                                 |
| ---------------------------------- | ------------- | ---------- | -------------------------------------------------------- |
| `certta_sc_camera_denied_icon`     | Raster (webp) | 312×84 px  | Camera permission denied                                 |
| `certta_sc_dd_success_icon`        | Vector        | 100×103 dp | Success screen checkmark                                 |
| `certta_sc_alert_triangle_icon`    | Vector        | 19×17 dp   | Warning in alerts. Fill follows `certta_sc_warning_icon` |
| `certta_sc_camera_hint_drawable`   | Shape         | Adapts     | Overlay hint during capture                              |
| `certta_sc_doc_front`              | Vector        | 164×112 dp | “Turn the document over” — front                         |
| `certta_sc_doc_back`               | Vector        | 164×112 dp | “Turn the document over” — back                          |
| `certta_sc_validation_type_camera` | Vector        | 24×24 dp   | “Take photo” card                                        |
| `certta_sc_validation_type_upload` | Vector        | 24×24 dp   | “Attach document” card                                   |

### Help tips (camera help bottom sheet)

| Resource ID                             | Format        | Size     | Used for                    |
| --------------------------------------- | ------------- | -------- | --------------------------- |
| `certta_sc_camera_help_hint_drawable_1` | Vector        | 48×70 dp | Tip 1 — “Frame the edges”   |
| `certta_sc_camera_help_hint_drawable_2` | Raster (webp) | 48×69 px | Tip 2 — “Avoid reflections” |
| `certta_sc_camera_help_hint_drawable_3` | Vector        | 48×70 dp | Tip 3 — “Legible data”      |

### Instructions carousel

All images share the same canvas size (124×168 px, raster webp). The images of one tip cross-fade in a loop, so overriding one of them changes part of that animation rather than a single still picture.

| Resource ID                                            | Used for                                 |
| ------------------------------------------------------ | ---------------------------------------- |
| `certta_sc_capture_instructions_1_1` / `_1_2` / `_1_3` | Capture tip 1 — “Start with any side”    |
| `certta_sc_capture_instructions_2_1` / `_2_2`          | Capture tip 2 — “Keep the edges visible” |
| `certta_sc_capture_instructions_3_1` / `_3_2`          | Capture tip 3 — “Ensure clarity”         |
| `certta_sc_upload_instructions_1_1` / `_1_2`           | Upload tip 1 — “Upload image or PDF”     |
| `certta_sc_upload_instructions_2_1` / `_2_2`           | Upload tip 2 — “Upload one or two files” |

### What cannot be customized

The shape of buttons, cards and sheets (corner radius, stroke width) is fixed unless you override that drawable. Flat colors are on Color Customization. Text is on Text Customization.

If you set a dark `certta_sc_background_color`, several icons keep their dark fills and white button backgrounds stay white — replace those drawables too, or keep the default light backgrounds.
{% endtab %}

{% tab title="iOS" %}

### Overview

`CerttaSmartCaptureImageCustomization` replaces the artwork Smart Capture renders: camera chrome, navigation and action icons, status icons, camera help illustrations, and the animated instruction sequences.

There are 23 slots — 18 single images and 5 animated sequences. Every slot is optional. A slot you leave unset keeps the bundled asset.

### API

| TypeScript                                                  | Where                               |
| ----------------------------------------------------------- | ----------------------------------- |
| `imageCustomization?: CerttaSmartCaptureImageCustomization` | `useCerttaSmartCapture().open(...)` |

Single slots are `string` (URI). Sequence slots are `string[]` (ordered frame URIs).

```typescript
import { Image } from 'react-native';
import {
  CerttaAcceptedDocumentType,
  type CerttaSmartCaptureConfiguration,
} from '@caf.io/react-native-sdk';

const helpIcon = Image.resolveAssetSource(require('./assets/brand_help.png'));
const backArrow = Image.resolveAssetSource(require('./assets/brand_back.png'));

const config: CerttaSmartCaptureConfiguration = {
  acceptedDocuments: [
    CerttaAcceptedDocumentType.IDENTITY_CARD,
    CerttaAcceptedDocumentType.DRIVER_LICENSE,
  ],
  imageCustomization: {
    helpIcon: helpIcon.uri,
    backArrow: backArrow.uri,
  },
};

await open(config);
```

`imageCustomization: {}` is valid and is a visual no-op.

Tokens map by meaning, not by asset name. Branding one warning icon brands every warning surface; the same is true of the close glyph.

`closeButtonEnabled` / `closeButtonDisabled` and `closeIcon` are different slots. The first pair is the full circular graphic behind the round camera button; `closeIcon` is the small X glyph on the help sheet, the delete-file sheet and the upload preview.

### Adding your images

1. Put PNG/WebP (and `@2x` / `@3x` if you use an asset catalog on the native side, or density-aware Metro assets) in the JS bundle.
2. Resolve with `Image.resolveAssetSource(require(...)).uri`.
3. Assign only the slots you want to change.

Remote `https://` URIs are only reliable if the native SDK can load them at open time. Prefer bundled assets.

### Resolution order

For every slot:

1. Your override, when the slot is set.
2. The bundled native asset for that slot.
3. Nothing — the slot renders empty.

An empty array on a sequence slot is treated as unset and falls back to the bundled animation.

### Single images

All 18 slots are optional URI strings. The Size column is the container the image is laid out in.

| Slot                   | Screen and state                                                                    | Size                        |
| ---------------------- | ----------------------------------------------------------------------------------- | --------------------------- |
| `cameraButtonEnabled`  | Camera — shutter, normal. Applied as a background image.                            | 70 × 70                     |
| `cameraButtonDisabled` | Camera — shutter, disabled.                                                         | 70 × 70                     |
| `cameraButtonPressed`  | Camera — shutter, highlighted.                                                      | 70 × 70                     |
| `closeButtonEnabled`   | Camera — round close, normal. Background image.                                     | 40 × 40                     |
| `closeButtonDisabled`  | Camera — round close, disabled and highlighted.                                     | 40 × 40                     |
| `closeIcon`            | X glyph on help sheet, delete sheet and upload preview.                             | 28 × 28 / 40 × 40 / 48 × 48 |
| `helpIcon`             | Camera — help button.                                                               | 40 × 40                     |
| `backArrow`            | Back on Instructions, Validation method, Preview, Upload review and Upload failure. | 40–44 pt                    |
| `eyeIcon`              | Upload review — preview on a file slot.                                             | 32 × 32                     |
| `trashIcon`            | Upload review — delete on a file slot.                                              | 32 × 32                     |
| `successIcon`          | Upload review — check on a filled slot.                                             | 20 × 20                     |
| `alertIcon`            | Camera error banner and Upload review warning banner.                               | 24 × 24 / 20 × 20           |
| `failureIcon`          | Upload failure — large status icon.                                                 | 100 × 100                   |
| `validationTypeCamera` | Validation method — “take a photo”.                                                 | 24 × 24                     |
| `validationTypeUpload` | Validation method — “attach a document”.                                            | 24 × 24                     |
| `cameraHelpHint1`      | Camera help — first tip.                                                            | 56 × 56                     |
| `cameraHelpHint2`      | Camera help — second tip.                                                           | 56 × 56                     |
| `cameraHelpHint3`      | Camera help — third tip.                                                            | 56 × 56                     |

### Animated sequences

All 5 slots are `string[]` — an ordered array of frame URIs. They drive the instructions carousel, laid out at a height of 200 pt and at most 70% of the content width.

| Slot                   | Screen                        |
| ---------------------- | ----------------------------- |
| `captureInstructions1` | Instructions — capture page 1 |
| `captureInstructions2` | Instructions — capture page 2 |
| `captureInstructions3` | Instructions — capture page 3 |
| `uploadInstructions1`  | Instructions — upload page 1  |
| `uploadInstructions2`  | Instructions — upload page 2  |

A single image renders static. Two or more crossfade, holding each frame for roughly 0.6 s with a 0.3 s fade.

### Sizing and rendering

Custom single images are never tinted. Overrides are applied as original artwork, so the SDK’s color tokens cannot recolor them. Supply images already in the color you want. Bundled assets keep their existing tinting.

The shutter and camera close buttons stretch to fill. Supply a square graphic with the circular shape already drawn into it.

Other button icons (`helpIcon`, `backArrow`, `eyeIcon`, `trashIcon`, and `closeIcon` on the help and delete sheets) render at their own size — supply them at the size in the table. `closeIcon` on the upload preview is stretched to fill its 48 × 48 button.

Every other slot scales to fit and letterboxes inside its container.

Supply `@2x` and `@3x` (or equivalent Metro densities). The SDK performs no extra DPI handling on the URI you pass.

Dark mode is not resolved per appearance. Whatever URI you pass is used in light and dark. If you need switching, pick the URI in JS from `useColorScheme()` before calling `open()`.

Animations respect Reduce Motion. When the system setting is on, a sequence renders its first frame only.

### Examples

#### Full customization

```typescript
import { Image } from 'react-native';
import {
  CerttaAcceptedDocumentType,
  type CerttaSmartCaptureConfiguration,
} from '@caf.io/react-native-sdk';

const uri = (mod: number) => Image.resolveAssetSource(mod).uri;

const frames = (...mods: number[]) => mods.map((m) => Image.resolveAssetSource(m).uri);

const config: CerttaSmartCaptureConfiguration = {
  acceptedDocuments: [
    CerttaAcceptedDocumentType.IDENTITY_CARD,
    CerttaAcceptedDocumentType.DRIVER_LICENSE,
  ],
  imageCustomization: {
    cameraButtonEnabled: uri(require('./assets/brand_shutter.png')),
    cameraButtonDisabled: uri(require('./assets/brand_shutter_disabled.png')),
    cameraButtonPressed: uri(require('./assets/brand_shutter_pressed.png')),
    closeButtonEnabled: uri(require('./assets/brand_close_button.png')),
    closeButtonDisabled: uri(require('./assets/brand_close_button_disabled.png')),
    closeIcon: uri(require('./assets/brand_close_glyph.png')),
    helpIcon: uri(require('./assets/brand_help.png')),
    backArrow: uri(require('./assets/brand_back.png')),
    eyeIcon: uri(require('./assets/brand_preview.png')),
    trashIcon: uri(require('./assets/brand_delete.png')),
    successIcon: uri(require('./assets/brand_success.png')),
    alertIcon: uri(require('./assets/brand_alert.png')),
    failureIcon: uri(require('./assets/brand_failure.png')),
    validationTypeCamera: uri(require('./assets/brand_camera.png')),
    validationTypeUpload: uri(require('./assets/brand_upload.png')),
    cameraHelpHint1: uri(require('./assets/brand_hint_frame.png')),
    cameraHelpHint2: uri(require('./assets/brand_hint_glare.png')),
    cameraHelpHint3: uri(require('./assets/brand_hint_legible.png')),
    captureInstructions1: frames(
      require('./assets/brand_capture_1_1.png'),
      require('./assets/brand_capture_1_2.png'),
      require('./assets/brand_capture_1_3.png'),
    ),
    captureInstructions2: frames(
      require('./assets/brand_capture_2_1.png'),
      require('./assets/brand_capture_2_2.png'),
    ),
    captureInstructions3: frames(
      require('./assets/brand_capture_3_1.png'),
      require('./assets/brand_capture_3_2.png'),
    ),
    uploadInstructions1: frames(
      require('./assets/brand_upload_1_1.png'),
      require('./assets/brand_upload_1_2.png'),
    ),
    uploadInstructions2: frames(
      require('./assets/brand_upload_2_1.png'),
      require('./assets/brand_upload_2_2.png'),
    ),
  },
};

await open(config);
```

Adjust the `uri` / `frames` helpers to match how you type `require()` in your project; the important part is passing `.uri` (and an array of URIs for sequences).

#### Partial customization

```typescript
const config: CerttaSmartCaptureConfiguration = {
  acceptedDocuments: [CerttaAcceptedDocumentType.IDENTITY_CARD],
  imageCustomization: {
    helpIcon: Image.resolveAssetSource(require('./assets/brand_help.png')).uri,
    failureIcon: Image.resolveAssetSource(require('./assets/brand_failure.png')).uri,
  },
};

await open(config);
```

#### Combining with colors

Both fields are independent on the same config. Colors apply on iOS via TypeScript; Android still uses `colors.xml`.

```typescript
const config: CerttaSmartCaptureConfiguration = {
  acceptedDocuments: [CerttaAcceptedDocumentType.IDENTITY_CARD],
  colorCustomization: {
    accent: '#1B5E20',
  },
  imageCustomization: {
    helpIcon: Image.resolveAssetSource(require('./assets/brand_help.png')).uri,
  },
};

await open(config);
```

### Behavior

Only the slots you set are applied — every omitted slot keeps its bundled asset.

Images are scoped to the flow. They are applied when it starts and released when it finishes.

Each session replaces the previous session’s images as a whole, rather than merging with them.

### What cannot be customized

* The in-camera animations — the document flip and the loading-success animation. These drive capture behavior rather than instruction artwork.
* The chevron on a validation-method card.
* The icon on an empty upload slot.
* The close button on the in-camera error banner. `closeIcon` does not cover it.
* The shape of buttons, cards and sheets — corner radius, stroke and border style are fixed. To change a shutter or round close button shape, draw it into the image you supply to that slot.

Text is customized separately — see Text Customization. Colors — see Color Customization.
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/caf-sdk/react-native/document-smart-capture/image-customization.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
