> 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 ## Customization of visual assets The SDK Web animations can be configured with the property `customAnimations` in the ``. With this property, one or more animations of the components offered by the 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 // Ejemplo de configuración 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**: In case an animation is configured using this property and the direct prop (For example: `customAnimations.sdkProvider.loading` and `loadingAnimation`), the value configured in `customAnimations`. {% endhint %} ## Customization of styles 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 tag `facephi-sdk-provider`: **Example**: {% hint style="info" %} The CSS configuration must be set with the correct encapsulation (global, scoped, ...). For component integrations, it is recommended to add the CSS configuration of `facephi-sdk-provider` and its configuration inside the component tag `:host`. Additionally, 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` | Background color of main elements (drop zone, dropdowns, content areas) | `#ffffff` | File Uploader, Choose Document, QR Widget | | `--color-background-hover` | Background color when hovering over 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` | Element border color | `#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` | Computer screen background color 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 (tutorial QR) | | `--color-tutorial-earrings` | Earrings and accessories color in tutorial animations | `#f4a485` | Lottie Widget (tutorial QR) | | `--color-tutorial-check` | Success check color in the Selphi tutorial | `#07a13a` | Lottie Widget (tutorial Selphi) | | `--color-tutorial-progress` | Circular progress bar color in the Selphi tutorial | `#5fc982` | Lottie Widget (tutorial Selphi) | | `--color-tutorial-capture` | Capture success color in the mobile tutorial | `#07a13a` | Lottie Widget (tutorial móvil SelphID) | | `--color-tutorial-device-bg` | Device screen background color in the SelphID tutorial | `#2b50b6` | Lottie Widget (SelphID desktop 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` | Secondary title font weight | `600` | File Uploader | | `--primary-font-weight` | Main text font weight | `400` | File Uploader | | **Layout variables** | | | | | `--wrapper-border-radius` | Element border radius | `0.5em` | File Uploader | | `--height-field` | Form field height | `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 inside the component tag `:host`. Additionally, 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 tag `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 main 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 the activity check | `#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` | Primary 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/fill error 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 text in the container | `center` | | `--wrapper-text-align` | Horizontal alignment of text in the container | `center` | | **Layout 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 tag `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 main 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` | Background color of informational text | `#EAEEF6` | | `--wrapper-color-diagnostic-secondary` | Background color of informational text 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` | Primary 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 text in the container | `center` | | `--wrapper-text-align` | Horizontal alignment of text in the container | `center` | | **Layout 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 The 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 category of components. ### Dark mode for the 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 { /* Componentes del SDK */ --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; /* Animaciones del tutorial */ --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 y 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 automatically change themes according to the user's preferences: {% endhint %} ```css @media (prefers-color-scheme: dark) { facephi-sdk-provider { /* Aplica aquí las variables de modo oscuro */ } } ``` *** ## Language Property The language property in this SDK provider component provides a robust and flexible approach to language selection and internationalization. It supports predefined translations for Spanish (default), English, and Portuguese, and can also be extended with custom translation files. This property accepts three types: a built-in 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). * `in`: 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 languages supported by default. Usage: ```jsx ``` **2. String (URL to Translation JSON)** Pass a string to the language property to retrieve a JSON file containing full or partial translations for one or more widgets within the SDK provider component. Examples: ```jsx // Directorio local // 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 done within the element `sdk`: * **FileUploader** (Subida de ficheros). * **VideoProvider** (Servicio de Video Grabación). {% endhint %} Each object allows 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...": "Espera un segundo..." } }, "selphid": { "en": { "Initializing...": "Espera un segundo..." } } } ``` {% hint style="info" %} The overridden literal must match an existing translation key exactly. See the Widget Literals section for a complete list. {% endhint %} **3. Add a New Language: To define a completely new language, provide all required literals for the corresponding widget(s).** ```json { "sdk": { "Literal 1": "Traducción para literal 1", "Literal 2": "Traducción para literal 2", "...": "..." } } ``` Example for Korean: ```json { "sdk": { "The process has been completed": "프로세스가 완료되었습니다", "Ready": "안녕, 친구", // ... todos los demás literales } } ``` {% hint style="warning" %} When adding a new language, you must provide all required literals for each affected widget. {% endhint %} **4. Combination of 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...": "Espera un segundo..." } }, "recruitment": { "Start": "Comencemos", "Finish": "Fin" // ...resto de los literales requeridos para este widget } } ``` **3. Object (Direct Assignment)** You can also directly pass an object with the same schema as the JSON described above. ```javascript myComponent.language = { sdk: { /* ... */ }, selphi: { /* ... */ } } ``` #### Fallback Behavior * If the provided translation (whether by URL or 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" %} The component strings are also configured in this object/file: * FileUploader * VideoProvider * VideoAssistance {% endhint %} ```typescript // Ejemplo de uso 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 // Ejemplo de uso 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 // Ejemplo de uso language = { sdk = { ... }, selphi: selphiCustomJson } ``` *** ### Use Case Examples Switch Component to English ```jsx ``` Add Korean Using a CDN JSON ```jsx ``` Where `kr.json` es: ```json { "sdk": { // ... Traducciones coreanas para todos los literales del SDK } } ``` Combine Different Scenarios ```json { "sdk": "en", "selphi": { "en": { "Starting camera...": "Preparando la cámara...", "Initializing...": "Espera un segundo..." } }, "recruitment": { // ...conjunto completo de literales chinos requeridos } } ``` #### Notes and Recommendations * When overriding or adding translations, make sure that all required literals are provided for the desired widget to ensure a complete user experience in the new language. * For consistent results, make sure the literal keys exactly match those in the default translation packages. * If a translation package or 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 ### Loading Animation Customization It is possible to modify the default animations (change colors) or replace them with custom animations. #### Change the color of loading animations To change the color of the animations, the CSS variables provided 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 using the property `loadingAnimation`. This property is available for the following 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 until the first widget is fully loaded. This can be controlled through the widgets' "load end" 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 loading animation through the property `loadingAnimation`. {% endhint %} {% hint style="warning" %} **Warning:** Make sure that this overlay does not cover possible components, error screens, or error flows. This behavior is the responsibility of the implementer. {% endhint %}