> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/personalizacion.md). # Customization ## Visual asset customization SDK Web animations can be configured with the property `customAnimations` in the ``. With this property, one or more animations of the components offered by SDK Web can be replaced: * SDK Provider * SelphID * Selphi * FileUploader * QRWidget For more information, see the [documentation for the customAnimations property](/docs.facephi-en/sdks/sdk-web/componentes/sdk-provider/propiedades/customanimations.md). **Example:** ```jsx // Configuration example const customAnimations = { sdkProvider: { loading: "/assets/anim/custom-loading.gif", }, selphi: { loading: "/assets/anim/custom-loading.gif", }, selphid: { loading: "/assets/anim/custom-loading.gif", } }; // HTML (...) ``` {% hint style="info" %} **Note**: If you configure an animation through this property and the direct prop (for example: `customAnimations.sdkProvider.loading` and `loadingAnimation`), the value configured in `customAnimations`. {% endhint %} ## Style customization The SDK Provider components and those offered by it, such as Selphi and SelphID, can be customized with the following CSS variables applied to the `facephi-sdk-provider`: **Example**: {% hint style="info" %} The CSS configuration must be set with the correct encapsulation (global, scoped, ...). In component integrations, it is recommended to add the CSS configuration of `facephi-sdk-provider` and its configuration within the component tag `:host`. In addition, a global CSS configuration for the component will also work the same way. {% endhint %} | CSS variable | Description | Default value | Components | | ------------------------------ | ------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------- | | **Color variables** | | | | | `--backgroundColor` | Main background color of the container | `transparent` | File Uploader, Choose Document, QR Widget, Desktop View, Error View, Finish Widget, Loading Ellipsis, Tip Widget | | `--color-state-loading` | Provider loading animation color | `#243760` | Loading Ellipsis | | `--color-background-primary` | Main background color of primary elements (drop zone, dropdowns, content areas) | `#ffffff` | File Uploader, Choose Document, QR Widget | | `--color-background-hover` | Background color on hover for interactive elements | `#cedafc` | File Uploader, Choose Document | | `--color-background-disabled` | Background color of disabled elements | `#eaeef6` | File Uploader, Choose Document, QR Widget | | `--color-text-primary` | Primary text color | `#1d2c4d` | File Uploader, Choose Document, QR Widget, Desktop View, Error View, Finish Widget, Loading Ellipsis, Tip Widget | | `--color-text-secondary` | Secondary text and placeholder color | `#526080` | File Uploader, Choose Document | | `--color-text-disabled` | Text color of disabled elements | `#afb8cc` | File Uploader, Choose Document, QR Widget | | `--color-text-on-primary` | Text color on primary-colored backgrounds | `#ffffff` | File Uploader, Choose Document, QR Widget, Tip Widget | | `--color-border-primary` | Border color of elements | `#ccd4e5` | File Uploader, Choose Document | | `--color-state-error` | Color for error states | `#dd3631` | File Uploader | | `--color-state-success` | Color for success states | `#0f8837` | File Uploader | | `--color-icon-primary` | Primary color for icons | `#243760` | File Uploader, Error View | | `--color-icon-secondary` | Secondary color for icons | `#7d879c` | File Uploader | | `--primaryColor` | Background color of selected elements | `transparent` | Choose Document | | `--secondaryColor` | Primary color of buttons and active elements | `#3167fc` | File Uploader, Choose Document, QR Widget, Tip Widget | | `--tertiaryColor` | Hover and focus color of buttons | `#2b50b6` | File Uploader, Choose Document, QR Widget, Tip Widget | | **Tutorial animation colors** | | | | | `--color-tutorial-computer-bg` | Background color of the computer screen in tutorial animations | `#4c7cfc` | Lottie Widget (Selphi, SelphID tutorials) | | `--color-tutorial-tshirt` | Avatar clothing color in tutorial animations | `#1d2c4d` | Lottie Widget (QR, Selphi, SelphID tutorials) | | `--color-tutorial-avatar-bg` | Avatar background color in tutorial animations | `#d5dae9` | Lottie Widget (QR, Selphi tutorials) | | `--color-tutorial-scan-line` | Scan line color in the QR tutorial animation | `#5fc982` | Lottie Widget (QR tutorial) | | `--color-tutorial-earrings` | Earrings and accessories color in tutorial animations | `#f4a485` | Lottie Widget (QR tutorial) | | `--color-tutorial-check` | Success check color in the Selphi tutorial | `#07a13a` | Lottie Widget (Selphi tutorial) | | `--color-tutorial-progress` | Color of the circular progress bar in the Selphi tutorial | `#5fc982` | Lottie Widget (Selphi tutorial) | | `--color-tutorial-capture` | Capture success color in the mobile tutorial | `#07a13a` | Lottie Widget (mobile SelphID tutorial) | | `--color-tutorial-device-bg` | Background color of the device screen in the SelphID tutorial | `#2b50b6` | Lottie Widget (desktop SelphID tutorial) | | **Typography variables** | | | | | `--wrapper-primary-font` | Main font family of the components | `'Verdana', sans-serif` | File Uploader, Choose Document, QR Widget, Desktop View, Error View, Finish Widget, Loading Ellipsis, Tip Widget | | `--title-font` | Main title font | `"Poppins-Semibold"` | File Uploader, Choose Document, QR Widget, Desktop View, Error View, Finish Widget, Loading Ellipsis, Tip Widget | | `--text-font` | Main text font | `"Poppins-Regular"` | File Uploader, Choose Document, QR Widget, Desktop View, Error View, Finish Widget, Loading Ellipsis, Tip Widget | | `--wrapper-font-family` | Font family of the drag-and-drop component | `'Verdana', sans-serif` | File Uploader (drag-drop) | | `--wrapper-text-font-size` | Text font size | `1em` | File Uploader | | `--secondary-font-weight` | Font weight of secondary titles | `600` | File Uploader | | `--primary-font-weight` | Main text font weight | `400` | File Uploader | | **Design variables** | | | | | `--wrapper-border-radius` | Border radius of elements | `0.5em` | File Uploader | | `--height-field` | Height of form fields | `40px` | Choose Document | **Example**: ```css facephi-sdk-provider { --color-text-primary: #000000; --secondaryColor: #ff6600; --tertiaryColor: #cc5200; } ``` > **Note**: The CSS configuration must be applied with the correct encapsulation (global, scoped, ...). In component integrations, it is recommended to add the CSS configuration of `facephi-sdk-provider` and its variables within the component tag `:host`. In addition, a global CSS configuration for the component will work the same way. *** #### Selphi variables These variables control the style of the Selphi component for Face Capture. All variables apply to the `facephi-sdk-provider`. | CSS variable | Description | Default value | | ------------------------------------------- | ----------------------------------------------------------------------- | -------------------- | | **Color variables** | | | | `--wrapper-color-background` | Main background color of the Widget | `#FFFFFF` | | `--wrapper-color-primary` | Color of primary elements | `#3167FC` | | `--wrapper-color-secondary` | Color of secondary elements | `#FFFFFF` | | `--wrapper-color-hover` | Hover effect color | `#2B50B6` | | `--wrapper-color-primary-text` | Main text color | `#1D2C4D` | | `--wrapper-color-secondary-text` | Secondary text color | `#1D2C4D` | | `--wrapper-color-progress-bar` | Progress bar color during extraction | `#3167FC` | | `--wrapper-color-progress-bar-background` | Background color of the progress bar around the camera stream | `transparent` | | `--wrapper-color-capture-success` | Border color when the face is captured successfully | `#60C782` | | `--wrapper-color-capture-fail` | Text and progress bar color when extraction fails | `#F24B45` | | `--wrapper-color-capture-warning` | Failure color in the activity test during the Active Liveness challenge | `#EB6A00` | | `--wrapper-color-liveness-arrow` | Directional arrow color during activity verification | `#5FC982` | | `--wrapper-color-icon` | Icon color in the component | `#243760` | | `--wrapper-color-error-icon` | Primary color of the error icon in the error view | `#DD3631` | | `--wrapper-color-browser-icon-background` | Browser icon background color in the BrowserError view | `transparent` | | `--wrapper-color-debug-error-message` | Internal error message color when Debug is enabled | `#DD3631` | | `--wrapper-color-loading-camera-background` | Camera background color before it is fully loaded in the DOM | `#000000` | | `--wrapper-color-loading` | Main color of the default loading animation | `#1D2C4D` | | **Tutorial animation colors** | | | | `--wrapper-color-tutorial-background` | Background color in the default tutorial animations | `#EAEEF6` | | `--wrapper-color-tutorial-progress` | Progress bar color in the default tutorial animations | `#5FC982` | | `--wrapper-color-tutorial-tshirt` | T-shirt color in the default tutorial animations | `#3167FC` | | `--wrapper-color-tutorial-earrings` | Earrings and sunglasses color in the default tutorial animations | `#F4A485` | | `--wrapper-color-tutorial-border-error` | Error border color in the default tutorial animations | `#F24B45` | | `--wrapper-color-tutorial-glow-error` | Glow/error fill color in the default tutorial animations | `#F24B45` | | **Typography variables** | | | | `--wrapper-primary-font` | Main text font | `"Poppins-Regular"` | | `--wrapper-primary-font-weight` | Main font weight | `400` | | `--wrapper-secondary-font` | Secondary text font | `"Poppins-Semibold"` | | `--wrapper-secondary-font-weight` | Secondary font weight | `600` | | `--wrapper-text-font-size` | Widget text font size | `1em` | | `--wrapper-title-font-size` | Widget title font size | `1.4em` | | `--wrapper-line-height` | Text line height | `1.3125em` | | `--wrapper-vertical-align` | Vertical alignment of the text in the container | `center` | | `--wrapper-text-align` | Horizontal alignment of the text in the container | `center` | | **Design variables** | | | | `--wrapper-progress-bar-width` | Progress bar width | `0.5em` | | `--wrapper-border-radius` | Button border radius | `0.5em` | | `--wrapper-error-icon-max-width` | Maximum width of the error view icon | `unset` | | **Logo visibility** | | | | `--wrapper-display-logo` | Show or hide the logo (use `block` to show or `none` to hide) | `none` | **Example**: ```css facephi-sdk-provider { --wrapper-color-primary: #3f2eff; --wrapper-color-secondary: #ffffff; --wrapper-color-hover: rgb(106, 93, 250); } ``` *** #### SelphID variables These variables control the style of the SelphID component for Document Capture. All variables apply to the `facephi-sdk-provider`. | CSS variable | Description | Default value | | ------------------------------------------ | ------------------------------------------------------------------------------------ | -------------------- | | **Color variables** | | | | `--wrapper-color-background` | Main background color of the Widget | `#FFFFFF` | | `--wrapper-color-primary` | Color of primary elements | `#3167FC` | | `--wrapper-color-secondary` | Color of secondary elements | `#FFFFFF` | | `--wrapper-color-hover` | Hover effect color | `#2B50B6` | | `--wrapper-color-primary-text` | Main text color | `#1D2C4D` | | `--wrapper-color-secondary-text` | Secondary text color | `#1D2C4D` | | `--wrapper-color-capture-success` | Border color when the document is captured successfully | `#07A13A` | | `--wrapper-color-capture-fail` | Text, progress bar, and document border color when extraction fails | `#F24B45` | | `--wrapper-color-capture-neutral` | Document border color in its neutral state (by default, the primary color) | `#3167FC` | | `--wrapper-color-diagnostic-primary` | Informational text background color | `#EAEEF6` | | `--wrapper-color-diagnostic-secondary` | Informational text background color when cameraOverflow is enabled | `#243760` | | `--wrapper-color-background-camera` | Background color of the video stream in the capture view | `#10192B` | | `--wrapper-color-background-preview-image` | Preview image background color | `#FFFFFF` | | `--wrapper-color-camera-overflow` | Widget background color in the document capture view when cameraOverflow is enabled | `#10192b85` | | `--wrapper-color-camera-overflow-filter` | Widget background filter in the document capture view when cameraOverflow is enabled | `#00000030` | | `--wrapper-color-icon` | Icon color in the component | `#243760` | | `--wrapper-color-error-icon` | Primary color of the error icon in the error view | `#DD3631` | | `--wrapper-color-browser-icon-background` | Browser icon background color in the BrowserError view | `transparent` | | `--wrapper-color-debug-error-message` | Internal error message color when Debug is enabled | `#DD3631` | | `--wrapper-color-loading` | Main color of the default loading animation | `#1D2C4D` | | **Tutorial animation colors** | | | | `--wrapper-color-tutorial-background` | Background color in the default tutorial animations | `#3167FC` | | `--wrapper-color-tutorial-success` | Success layer color in the default tutorial animations | `#5BBF7E` | | **Typography variables** | | | | `--wrapper-primary-font` | Main text font | `"Poppins-Regular"` | | `--wrapper-primary-font-weight` | Main font weight | `400` | | `--wrapper-secondary-font` | Secondary text font | `"Poppins-Semibold"` | | `--wrapper-secondary-font-weight` | Secondary font weight | `600` | | `--wrapper-text-font-size` | Widget text font size | `1em` | | `--wrapper-title-font-size` | Widget title font size | `1.4em` | | `--wrapper-title-font-size-mobile` | Widget title font size on mobile resolutions | `1.125em` | | `--wrapper-line-height` | Text line height | `1.75em` | | `--wrapper-vertical-align` | Vertical alignment of the text in the container | `center` | | `--wrapper-text-align` | Horizontal alignment of the text in the container | `center` | | **Design variables** | | | | `--wrapper-document-border-width` | Video stream border width | `0.225em` | | `--wrapper-diagnostic-border-width` | Informational message border width | `0.175em` | | `--wrapper-border-radius` | Button border radius | `0.5em` | | `--wrapper-error-icon-max-width` | Maximum width of the error view icon | `unset` | | **Logo visibility** | | | | `--wrapper-display-logo` | Show or hide the logo (use `block` to show or `none` to hide) | `none` | **Example**: ```css facephi-sdk-provider { --wrapper-color-primary: #3f2eff; --wrapper-color-capture-success: #00aa00; --wrapper-color-diagnostic-primary: #f0f0f0; } ``` *** ## Dark mode customization SDK Provider components can be easily adapted to dark mode themes by overriding the CSS variables with the appropriate color values. Below are minimal configuration examples for each component category. ### Dark mode for SDK components Apply these variables to customize File Uploader, Choose Document, QR Widget, and the rest of the main SDK components in dark mode: ```css facephi-sdk-provider { /* SDK components */ --backgroundColor: #1D2C4D; --color-background-primary: #17223B; --color-background-hover: #0E1B3D; --color-background-disabled: #243760; --color-text-primary: #ffffff; --color-text-secondary: #ffffff; --color-text-disabled: #6b7a90; --color-text-on-primary: #10192B; --color-border-primary: #3d4a6c; --color-state-error: #e85550; --color-state-success: #2d9d5f; --secondaryColor: #5b8def; --tertiaryColor: #4a6bc9; /* Tutorial animations */ --color-tutorial-computer-bg: #4c7cfc; --color-tutorial-avatar-bg: #2B50B6; --color-tutorial-check: #2d9d5f; --color-tutorial-progress: #5fc982; --color-tutorial-capture: #2d9d5f; --color-tutorial-device-bg: #2B50B6; --color-tutorial-scan-line: #5fc982; --color-tutorial-earrings: #f4a485; /* Selphi and SelphID */ --wrapper-color-background: #1D2C4D; --wrapper-color-primary: #5b8def; --wrapper-color-secondary: #1D2C4D; --wrapper-color-hover: #4a6bc9; --wrapper-color-primary-text: #ffffff; --wrapper-color-secondary-text: #ffffff; --wrapper-color-progress-bar: #5b8def; --wrapper-color-loading: #ffffff; --wrapper-color-tutorial-background: #526080; --wrapper-color-tutorial-success: #2d9d5f; --wrapper-color-diagnostic-primary: #243760; } ``` {% hint style="info" %} **Tip**: You can combine these dark mode variables with a CSS media query to change themes automatically according to the user's preferences: {% endhint %} ```css @media (prefers-color-scheme: dark) { facephi-sdk-provider { /* Apply the dark mode variables here */ } } ``` *** ## Language Property The language property in this SDK provider component provides a robust and flexible approach to language selection and internationalization. It supports pre-defined translations for Spanish (default), English, and Portuguese, and can also be extended with custom translation files. This property accepts three types: an enum `Language` built-in, a string (such as a URL to a translation JSON) or an object for custom configuration. Default languages: * `is`: Texts in Spanish (default value). * `en`: Texts in English. * `pt`: Texts in Portuguese. Property type: `Language | string | object` ### Supported Types and Usage **1. Enum Language** Use the predefined enum for the default supported languages. Usage: ```jsx ``` **2. String (URL to Translation JSON)** Pass a string to the language property to obtain a JSON file containing complete or partial translations for one or more widgets within the SDK provider component. Examples: ```jsx // Local directory // CDN ``` JSON schema: The root level must be an object containing one or more of the following widget keys: * `sdk` * `selphi` * `selphid` {% hint style="info" %} The configuration of the following components is performed within the `sdk`: * **FileUploader** (File Upload). * **VideoProvider** (Video Recording Service). {% endhint %} Each object will allow full or partial editing of the texts used within its components. Example structure: ```json { "sdk": { ... }, "selphi": { ... }, "selphid": { ... }, } ``` > Note: If none of these four keys is present, the SDK provider component will fall back to the default language: Spanish. JSON structure – Options **1. Default Language Selection: Specify an existing language for a widget:** ```json { "sdk": "en", "selphi": "pt" } ``` **2. Partial Translation Overrides: This provides a way to override specific literals for a widget/language.** ```json { "sdk": "en", "selphi": { "en": { "Initializing...": "Wait a second..." } }, "selphid": { "en": { "Initializing...": "Wait a second..." } } } ``` {% hint style="info" %} The overridden literal must match exactly an existing translation key. See the Widget Literals section for a complete list. {% endhint %} **3. Add a New Language: To define a completely new language, provide all the required literals for the corresponding widget(s).** ```json { "sdk": { "Literal 1": "Translation for literal 1", "Literal 2": "Translation for literal 2", "...": "..." } } ``` Korean example: ```json { "sdk": { "The process has been completed": "프로세스가 완료되었습니다", "Ready": "안녕, 친구", // ... all other literals } } ``` {% hint style="warning" %} When adding a new language, you must provide all the required literals for each affected widget. {% endhint %} **4. Combining Options: You can combine default language selections, partial overrides, and new language definitions within the same object or JSON as needed.** Example: ```json { "sdk": "en", "selphid": { "en": { "Initializing...": "Wait a second..." } }, "recruitment": { "Start": "Let's begin", "Finish": "End" // ...rest of the required literals for this widget } } ``` **3. Object (Direct Assignment)** You can also pass an object directly with the same schema as the JSON described above. ```javascript myComponent.language = { sdk: { /* ... */ }, selphi: { /* ... */ } } ``` #### Fallback Behavior * If the provided translation (whether by URL or by object) does not contain any valid root key (sdk, selphi, selphid, recruitment), the default language will be used: Spanish. * Any missing literal for a new language will also fall back to the default values for that literal in Spanish. *** ### Literal templates The complete list of translation literals for each widget, needed to create full or partial overrides, can be found here: **SDK Provider Literals**: {% columns %} {% column %} **Spanish** {% file src="/files/984652c4c7f202cf7d88e5e759d9aab283bc9674" %} {% endcolumn %} {% column %} **English** {% file src="/files/64345e7b503dedf368e4fe7eb28ecfeb2baf9dd6" %} {% endcolumn %} {% column %} **Portuguese** {% file src="/files/9f782e25dfe720a67be9a925293e4d3871bdd682" %} {% endcolumn %} {% column %} **Template** {% file src="/files/36a74fdfad69d1574454c9fa3dd0b93efe89413f" %} {% endcolumn %} {% endcolumns %} {% hint style="info" %} In this object/file, the strings for the components are also configured: * FileUploader * VideoProvider * VideoAssistance {% endhint %} ```typescript // Usage example language = { sdk = sdkCustomJson } ``` **SelphID Literals**: {% columns %} {% column %} Spanish {% file src="/files/08bc3eabaa348c68b149c9ce39bea129f695fbb2" %} {% endcolumn %} {% column %} English {% file src="/files/003a670759a2a0b4d6ca2b90cc4aefc4f47ba03c" %} {% endcolumn %} {% column %} Portuguese {% file src="/files/56ca8324dca139985cee79668e6414d5047be2f8" %} {% endcolumn %} {% column %} Template {% file src="/files/939ee210c9ec9afdc1dcfb8cb3107a8701c224e4" %} {% endcolumn %} {% endcolumns %} ```typescript // Usage example language = { sdk = { ... }, selphid: selphidCustomJson } ``` **Selphi Literals**: {% columns %} {% column %} **Spanish** {% file src="/files/4a09862bfd11a9adf9e4efb13092bd6c2882b7df" %} {% endcolumn %} {% column %} **English** {% file src="/files/1e00337a4c0fb1461a28ec35b8b1568a943c3415" %} {% endcolumn %} {% column %} **Portuguese** {% file src="/files/7fb42c3ae8d9989e858023c81ab3d8ea7303713b" %} {% endcolumn %} {% column %} **Template** {% file src="/files/0fb8dfe8f4ad3060807fc4c965fa7d6980b362ed" %} {% endcolumn %} {% endcolumns %} ```typescript // Usage example language = { sdk = { ... }, selphi: selphiCustomJson } ``` *** ### Use Case Examples Change Component to English ```jsx ``` Add Korean Using a CDN JSON ```jsx ``` Where `kr.json` es: ```json { "sdk": { // ... Korean translations for all SDK literals } } ``` Combine Different Scenarios ```json { "sdk": "en", "selphi": { "en": { "Starting camera...": "Preparing the camera...", "Initializing...": "Wait a second..." } }, "recruitment": { // ...complete set of required Chinese literals } } ``` #### Notes and Recommendations * When overriding or adding translations, make sure all required literals for the desired widget are provided to ensure a complete user experience in the new language. * For consistent results, make sure the literal keys exactly match those of the default translation packages. * If a translation package or a schema does not meet the requirements, the fallback (Spanish) will be applied. #### Appendix See the Widget Literals Reference for a complete list of translation keys for each widget separately in its customization section. *** ## Useful customization tips ### Customization of loading animations It is possible to modify the default animations (change colors) or replace them with custom animations. #### Change the color of the loading animations To change the color of the animations, the CSS variables offered for this purpose will be used: * SDK Provider (Loading Ellipsis): `--color-state-loading`. * Selphi and SelphID components: `--wrapper-color-loading`. #### Change loading animation Loading animations can be replaced through the property `loadingAnimation`. This property is available for the components: * SDK Provider ([link](/docs.facephi-en/sdks/sdk-web/componentes/sdk-provider/propiedades/loadinganimation.md)). * SelphID Widget ([link](/docs.facephi-en/sdks/sdk-web/componentes/selphid-documentos/propiedades/loadinganimation.md)). * Selphi Widget ([link](/docs.facephi-en/sdks/sdk-web/componentes/selphi-biometria-facial/propiedades/loadinganimation.md)). *** ### Hide loading times When using a custom loading screen instead of the default ones offered by the SDK components, it is possible to hide the loading screens with an overlay element until the first widget is fully loaded. This can be controlled through the widgets' "loading complete" events. **Example (JSX):** state-controlled overlay; hidden when SelphID emits `moduleLoaded`. ```jsx
{showLoadingOverlay && }
let showLoadingOverlay = true; function handleSelphIDLoaded(ev) { let showLoadingOverlay = false; } ``` {% hint style="info" %} **Note:** The loading of the next component (usually Selphi) can be hidden in the same way, or by customizing the widget's loading animation through the property `loadingAnimation`. {% endhint %} {% hint style="warning" %} **Warning:** Ensure that this overlay does not cover possible components, error screens, or error flows. This behavior is the responsibility of the implementer. {% endhint %}