> 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 SDK Web customization guide ## Customization of visual assets 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 // 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**: If you configure an animation using this property and the direct prop (For example: `customAnimations.sdkProvider.loading` and `loadingAnimation`), the value configured in `customAnimations`. {% endhint %} ## Style customization 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 within the component tag `:host`. Also, a global CSS configuration for the component will 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, Terms and Conditions | | `--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, Terms and Conditions | | `--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, Terms and Conditions | | `--color-text-primary` | Primary text color | `#1d2c4d` | File Uploader, Choose Document, QR Widget, Desktop View, Error View, Finish Widget, Loading Ellipsis, Tip Widget, Terms and Conditions | | `--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, Terms and Conditions | | `--color-text-on-primary` | Text color on primary-colored backgrounds | `#ffffff` | File Uploader, Choose Document, QR Widget, Tip Widget, Terms and Conditions | | `--color-border-primary` | Border color of elements | `#ccd4e5` | File Uploader, Choose Document, Terms and Conditions | | `--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, Terms and Conditions | | `--tertiaryColor` | Hover and focus color of buttons | `#2b50b6` | File Uploader, Choose Document, QR Widget, Tip Widget, Terms and Conditions | | **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` | Circular progress bar color in the Selphi tutorial | `#5fc982` | Lottie Widget (Selphi tutorial) | | `--color-tutorial-capture` | Capture success color in the mobile tutorial | `#07a13a` | Lottie Widget (SelphID mobile tutorial) | | `--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, Terms and Conditions | | `--text-font` | Main text font | `"Poppins-Regular"` | File Uploader, Choose Document, QR Widget, Desktop View, Error View, Finish Widget, Loading Ellipsis, Tip Widget, Terms and Conditions | | `--wrapper-font-family` | Drag-and-drop component font family | `'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 | | **Design 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 integrations with components, it is recommended to add the CSS configuration of `facephi-sdk-provider` and its variables within the component tag `:host`. Also, 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 are applied 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` | Color of the main text | `#1D2C4D` | | `--wrapper-color-secondary-text` | Color of secondary text | `#1D2C4D` | | `--wrapper-color-progress-bar` | Progress bar color during extraction | `#3167FC` | | `--wrapper-color-progress-bar-background` | Progress bar background color around the camera stream | `transparent` | | `--wrapper-color-capture-success` | Border color when the face is captured correctly | `#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` | Main 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 into 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` | Error glow/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 text in the container | `center` | | `--wrapper-text-align` | Horizontal alignment of 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 are applied 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` | Color of the main text | `#1D2C4D` | | `--wrapper-color-secondary-text` | Color of secondary text | `#1D2C4D` | | `--wrapper-color-capture-success` | Border color when the document is captured correctly | `#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 the informative text | `#EAEEF6` | | `--wrapper-color-diagnostic-secondary` | Background color of the informative text when cameraOverflow is enabled | `#243760` | | `--wrapper-color-background-camera` | Video stream background color 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` | Main 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 text in the container | `center` | | `--wrapper-text-align` | Horizontal alignment of text in the container | `center` | | **Design variables** | | | | `--wrapper-document-border-width` | Video stream border width | `0.225em` | | `--wrapper-diagnostic-border-width` | Informative 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 examples of minimal configuration 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 { /* 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 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 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` , a string (such as a URL to a translation JSON) or an object for custom configuration. Default languages: * `is`: Spanish texts (default value). * `in`: English texts. * `pt`: Portuguese texts. Property type: `Language | string | object` ### Supported Types and Usage **1. Language enum** 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 obtain 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 carried out 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...": "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": "Translation for literal 1", "Literal 2": "Translation for literal 2", "...": "..." } } ``` Example for Korean: ```json { "sdk": { "The process has been completed": "프로세스가 완료되었습니다", "Ready": "안녕, 친구", // ... all the other literals } } ``` {% hint style="warning" %} When adding a new language, you must provide all the 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" // ...rest of the required literals for this Widget } } ``` **3. Object (Direct Mapping)** 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 component strings 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 Switch Component to English ```jsx ``` Add Korean Using a CDN JSON ```jsx ``` Where `kr.json` is: ```json { "sdk": { // ... Korean translations for all SDK literals } } ``` Combine Different Scenarios ```json { "sdk": "en", "selphi": { "en": { "Starting camera...": "Preparando la cámara...", "Initializing...": "Espera un segundo..." } }, "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 match exactly 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 Literal 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 loading animations To change the color of the animations, the CSS variables provided for that 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 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' "loading finished" events. **Example (JSX):** state-controlled overlay; it is 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 this overlay does not cover possible components, error screens, or error flows. This behavior is the responsibility of the implementer. {% endhint %}