Skip to content
Last updated

Hosted Widget Branding and Customization

This articles refers to the multi-region widget

The content of this article refers to the multi-region widget (applicable for Employments and Fiscal in Mexico as well as Employments in Brazil). If you wish to operate in Brazil, please see our Hosted Widget for Regulated OFDA.

With Belvo's Connect Widget, you can optionally add the following branding and customization:

  • Your company logo
  • Your company icon
  • Your company name
  • Link to your privacy policy
  • Text to highlight the benefits of your product
  • Text when a user chooses to close the widget
  • Hide messaging in the account connect screen
  • Add a custom overlay color
  • Enable dark mode
  • Add custom colors to the widget
Add branding when generating access_token

To add branding to your widget, it must be done in the same backend call as your request to generate an access_token.

Add a company icon

You can add your company icon to the widget to make it more aligned with your brand.
When you add your company icon, it appears on the following screens:

  • initial start of the widget

Make sure that your icon has square dimensions, in SVG format, has a transparent background, and contains no surrounding whitespace. If your icon does not follow these specifications, the Belvo widget will display the following icon:

Instructions
To add a custom company icon, just add the URL to your SVG image to the company_icon key.

{
  "widget": {
    "branding": {
      "company_icon": "https://mysite.com/icon.svg",
        }
     }
}

You can add your company logo to the widget to make it more aligned with your brand. When you add your company logo, it appears on the following screens:

  • while the account is being linked
  • once an account is successfully linked
  • when a user chooses to cancel the linking process

Make sure that your logo is in SVG format, has a transparent background, and contains no surrounding whitespace. For the best visibility and scaling, we suggest that you use a horizontal logo (see the top-left example in the image below).

Instructions
To add a custom company logo, just add the URL to your SVG image to the company_logo key.

{
  "widget": {
    "branding": {
      "company_logo": "https://mysite.com/logo.svg",
        }
     }
}

Add your company name

You can add your company name to be displayed when the widget first starts. By default, it'll just display "Link your account". When you add your company name, the message will follow the format "[company_name] uses Belvo to connect your account".

Please note, only the company name is customizable in the introductory sentence

Instructions

To add your company name, just add it to the company_name key.

{
  "widget": {
    "branding": {
      "company_name": "ACME",
        }
     }
}

You can add a link to your privacy policy (or terms and conditions) on the initial screen of the widget that, when clicked, will redirect your users to the linked webpage. This helps your users better understand what your use case is regarding the data you are requesting. By default the widget will include the URL to Belvo's privacy policy (<https://belvo.com/terms-service/>).

Instructions
To add a link to your privacy policy in the initial connect screen, just add the URL to your policy to the company_terms_url key.

{
  "widget": {
    "branding": {
      "company_terms_url": "https://belvo.com/terms-service/",
        }
     }
}

Add text to the connect screen

You can add a custom message on the initial screen of the widget to provide additional information to your users about why they need to connect their account using Belvo. This helps to drive conversion and increase end-user trust to link their account.

Instructions
To add custom text in the initial connect screen:

  1. Add the title of the expand box to the company_benefit_header key.
    📝 The maximum length (including spaces) for the title is 30 characters.

  2. Add the content for the expand box to the company_benefit_content key.
    📝 The maximum length (including spaces) for the content is 140 characters.

You must provide content for both company_benefit_header and company_benefit_content. If you don't provide content for both, nothing will appear

{
  "widget": {
    "branding": {
      "company_benefit_header": "Faster approvals",
      "company_benefit_content": "Using Belvo cuts down on your loan approval time by up to 15 days.",
        }
     }
}

Add an exit message

You can add a custom message to be displayed when an end user chooses to cancel connecting their account. The message appears below a standard "Are you sure you want to cancel?" prompt. You can highlight the benefits of continuing to link their account using the widget in comparison to traditional methods.

Instructions

To add a custom exit message, add the content to display to the opportunity_loss key.

📝 Your message can have a maximum of 120 characters, including spaces.

{
  "widget": {
    "branding": {
      ...
      "opportunity_loss": "It can take up to 20 days to evaluate your request using traditional methods.",
      ...
        }
     }
}

Hide messaging in the account connect screen

You can choose to hide the "+1m users have securely connected their accounts using Belvo" message that appears when your user reaches the account connection screen in the widget. By default, this message is visible in the widget (true).

** Instructions**

To hide the message in the account connection screen, just set the social_proof parameter to false.

{
  "widget": {
    "branding": {
      "social_proof": false,
        }
     }
}

Add a custom overlay color

You can add a custom overlay color for when the widget loads in your desktop application. We recommend choosing a neutral color related to your brand to keep environmental context. By default, this overlay is set to grey.

Overlay opacity

No matter what color you upload, Belvo will automatically set the opacity to 90%. This is due to the following UX best practices:

  • With lower opacities (less than 70%), the user can experience difficulties focusing on the flow as they will have “visual noise" in the background.
  • Block colors (opacity set at 100%) may cause a drastic change, resulting in a disjointed or unnatural experience.

Instructions

To set the overlay color, just add the full HEX code (## followed by six characters) to the overlay_background_color key.

{
  "widget": {
    "branding": {
      "overlay_background_color": "#F0F2F4",
        }
     }
}

Enable dark mode

The Connect Widget supports a dark mode theme. To enable it, you need to pass the DARK value in the color_scheme parameter inside the widget object.

{
  "widget": {
    "color_scheme": "DARK",
  }
}

When dark mode is enabled, you can also customize the colors. To apply a custom style specifically for dark mode, simply append -dark to any of the CSS variables listed in the sections below. For example, to change the primary color in dark mode, you would use "--color-primary-base-dark".

Multi-Region Dark Mode

Add custom colors to the widget

You can customize the widget by adding your own brand’s colors to several parts of the widget:

  • The primary color for buttons, checkboxes, and the progress bar
  • The color of the navigation icons and text

The possible modifications are listed in the table below:

CSS VariableDefault (Light)Default (Dark)Description
--color-primary-base#0663F9#0663F9Sets the primary color for buttons, checkboxes, and the progress bar.
--nav-bar-title-color#161A1D#011432Sets the color of the navigation bar title.
--nav-bar-icon-color#161A1D#011432Sets the color of navigation bar icons.

Instructions

To set your brand’s colors:

  1. Add the theme array to the widget object.
  2. For each item you want to modify, add an object that has the keys css_key and value (see the code sample below). The color values can be either in HEX, RGB, or RGBA format.
Light Mode Example
{
  "widget": {
    "color_scheme": "LIGHT",
    "branding": {}, // Your customized branding
    "theme": [
      {
        "css_key": "--color-primary-base",
        "value": "#0663F9"
      },
      {
        "css_key": "--nav-bar-title-color",
        "value": "#161A1D"
      },
      {
        "css_key": "--nav-bar-icon-color",
        "value": "#161A1D"
      }
    ],
  }
}

You do not have to include all the possible css_keys. You can just set the keys (and values) that you want to modify

Modify the widget navigation bar

You can customize the widget's navigation bar by modifying the colors to suit your brand's needs:

The possible modifications are listed in the table below:

CSS VariableDefault (Light)Default (Dark)Description
--nav-bar-title-color#161a1d#011432Sets the color of the navigation bar title.
--nav-bar-title-aligncentercenterSpecifies the alignment of the navigation bar title. Possible positions are: center, start, and end.
--nav-bar-icon-color#161a1d#011432Sets the color of navigation bar icons.
--nav-bar-background-color#ffffff#011432Defines the background color of the navigation bar.
--nav-bar-box-shadownonenoneAdds a shadow effect to the navigation bar.
--nav-bar-border-color#f0f2f4#2B3D54Specifies the border color of the navigation bar.

To modify the widget's navigation bar:

  1. Add the theme array to the widget object.
  2. For each item you want to modify, add an object that has the keys css_key and value (see the code sample below). The color values can be either in HEX, RGB, or RGBA format.
Light Mode Example
{
  "widget": {
    "color_scheme": "LIGHT",
    "branding": {}, // Your customized branding
    "theme": [
      {
        "css_key": "--nav-bar-title-color",
        "value": "#161a1d"
      },
      {
        "css_key": "--nav-bar-title-align",
        "value": "center"
      },
      {
        "css_key": "--nav-bar-icon-color",
        "value": "#161a1d"
      },
      {
        "css_key": "--nav-bar-background-color",
        "value": "#ffffff"
      },
      {
        "css_key": "--nav-bar-box-shadow",
        "value": "none"
      },
      {
        "css_key": "--nav-bar-border-color",
        "value": "#f0f2f4"
      }, // Add additional theming options here
    ]
  }
}

Modify the widget buttons

You can customize the widget's buttons by modifying the colors and border radiuses to suit your brand's needs:

These modifications apply to all buttons in the widget

The possible modifications are listed in the table below:

CSS VariableDefault (Light)Default (Dark)Description
--button-font-color#ffffff#EEF3F8Sets the font color for buttons.
--button-font-color-disabled#ffffff#EEF3F8Defines the font color for disabled buttons.
--button-border-radius2px2pxSpecifies the border radius of buttons.
--button-background-color-disabled#009EE3#0663F9Defines the background color for disabled buttons.
--button-opacity-disabled0.20.2Specifies the opacity for disabled buttons.
--button-border-color-disabled#09EE354#09EE354Sets the border color for disabled buttons.

To make modifications to the widget's buttons:

  1. Add the theme array to the widget object.
  2. For each item you want to modify, add an object that has the keys css_key and value (see the code sample below). The color values can be either in HEX, RGB, or RGBA format.
Light Mode Example
{
  "widget": {
    "color_scheme": "LIGHT",
    "branding": {}, // Your customized branding
    "theme": [
      {
        "css_key": "--button-font-color",
        "value": "#ffffff"
      },
      {
        "css_key": "--button-font-color-disabled",
        "value": "#ffffff"
      },
      {
        "css_key": "--button-border-radius",
        "value": "2px"
      },
      {
        "css_key": "--button-background-color-disabled",
        "value": "#009EE3"
      },
      {
        "css_key": "--button-opacity-disabled",
        "value": "0.2"
      },
      {
        "css_key": "--button-border-color-disabled",
        "value": "#09EE354"
      }, // Add additional theming options here
    ]
  }
}

Modify the widget banners (callouts)

You can customize the widget's banners to suit your brand's needs:

The possible modifications are listed in the table below:

CSS VariableDefault (Light)Default (Dark)Description
--banner-border-radius4px4pxSpecifies the border radius of banners.
--banner-background-color#ffffff#011432Sets the background color of banners.
--banner-border-color#e2e6e9#2B3D54Specifies the border color of banners.
--banner-border-color-left-error#f90e06#E04A39Left border color for error banners.
--banner-border-color-left-success#59c837#59C837Left border color for success banners.
--banner-border-color-left-info#0663F9#0663F9Left border color for info banners.
--banner-border-color-left-warning#f9c806#F9C806Left border color for warning banners.
--banner-icon-color-error#f90e06#E04A39Icon color for error banners.
--banner-icon-color-success#59c837#59C837Icon color for success banners.
--banner-icon-color-info#0663F9#0663F9Icon color for info banners.
--banner-icon-color-warning#f9c806#F9C806Icon color for warning banners.
--banner-title-color#161a1d#EEF3F8Sets the color of banner titles.
--banner-body-color#414d58#C2CFD9Specifies the color of banner body text.
--banner-title-font-weight600600Defines the font weight of banner titles.
--banner-body-font-weight600600Specifies the font weight of banner body text.
--banner-box-shadow0 2px 4px 0 rgba(0, 0, 0, 0.05)0 2px 4px 0 rgba(0, 0, 0, 0.05)Adds a shadow effect to banners.

To make modifications to the widget's banners:

  1. Add the theme array to the widget object.
  2. For each item you want to modify, add an object that has the keys css_key and value (see the code sample below). The color values can be either in HEX, RGB, or RGBA format.
Light Mode Example
{
  "widget": {
    "color_scheme": "LIGHT",
    "branding": {}, // Your customized branding
    "theme": [
      {
        "css_key": "--banner-border-radius",
        "value": "4px"
      },
      {
        "css_key": "--banner-background-color",
        "value": "#ffffff"
      },
      {
        "css_key": "--banner-border-color",
        "value": "#e2e6e9"
      },
      {
        "css_key": "--banner-border-color-left-error",
        "value": "#f90e06"
      },
      {
        "css_key": "--banner-border-color-left-success",
        "value": "#59c837"
      },
      {
        "css_key": "--banner-border-color-left-info",
        "value": "#0663F9"
      },
      {
        "css_key": "--banner-border-color-left-warning",
        "value": "#f9c806"
      },
      {
        "css_key": "--banner-icon-color-error",
        "value": "#f90e06"
      },
      {
        "css_key": "--banner-icon-color-success",
        "value": "#59c837"
      },
      {
        "css_key": "--banner-icon-color-info",
        "value": "#0663F9"
      },
      {
        "css_key": "--banner-icon-color-warning",
        "value": "#f9c806"
      },
      {
        "css_key": "--banner-title-color",
        "value": "#161a1d"
      },
      {
        "css_key": "--banner-body-color",
        "value": "#414d58"
      },
      {
        "css_key": "--banner-title-font-weight",
        "value": "600"
      },
      {
        "css_key": "--banner-body-font-weight",
        "value": "600"
      },
      {
        "css_key": "--banner-box-shadow",
        "value": "0 2px 4px 0 rgba(0, 0, 0, 0.05)"
      }, // Add additional theming options here
    ]
  }
}

Modify the widget input fields

You can customize the widget's input fields to suit your brand's needs:

The possible modifications are listed in the table below:

CSS VariableDefault (Light)Default (Dark)Description
--input-text-border-radius2px2pxDefines the border radius for input fields.
--input-text-border-color#161a1d#2B3D54Specifies the border color for input fields.
--input-text-outline-border-color#c4cdd4#3A4D64Defines the outline border color for input fields. (like hover effect)
--input-text-placeholder-color#c4cdd4#2B3D54Defines the color for placeholder text.
--input-text-label-color#414d58#EEF3F8Sets the label color for input fields.
--input-text-label-color-error#f90e06#E04A39Specifies the label color for input fields in error state.
--input-text-label-variationoutlinedoutlinedSpecifies label variation position. Possible options are: outlined and top.
--input-text-icon-color#000000#E04A39Sets the color of input icons.

To modify the widget's input fields:

  1. Add the theme array to the widget object.
  2. For each item you want to modify, add an object that has the keys css_key and value (see the code sample below). The color values can be either in HEX, RGB, or RGBA format.
Light Mode Example
{
  "widget": {
    "color_scheme": "LIGHT",
    "branding": {}, // Your customized branding
    "theme": [
      {
        "css_key": "--input-text-border-radius",
        "value": "2px"
      },
      {
        "css_key": "--input-text-border-color",
        "value": "#161a1d"
      },
      {
        "css_key": "--input-text-outline-border-color",
        "value": "#c4cdd4"
      },
      {
        "css_key": "--input-text-placeholder-color",
        "value": "#c4cdd4"
      },
      {
        "css_key": "--input-text-label-color",
        "value": "#414d58"
      },
      {
        "css_key": "--input-text-label-color-error",
        "value": "#f90e06"
      },
      {
        "css_key": "--input-text-label-variation",
        "value": "outlined"
      },
      {
        "css_key": "--input-text-icon-color",
        "value": "#000000"
      }, // Add additional theming options here
    ]
  }
}

Modify Widget Tab Components

You can customize the widget's tabs to suit your brand's needs:

The possible modifications are listed in the table below:

CSS VariableDefault (Light)Default (Dark)Description
--tab-text-color#0663f9#0663f9Defines the text color for the tabs.
--tab-border-color#0663f9#0663f9Specifies the border color for the bottom of the tabs.

To modify the widget's tabs:

  1. Add the theme array to the widget object.
  2. For each item you want to modify, add an object that has the keys css_key and value (see the code sample below). The color values can be either in HEX, RGB, or RGBA format.
Light Mode Example
{
  "widget": {
    "color_scheme": "LIGHT",
    "branding": {}, // Your customized branding
    "theme": [
      {
        "css_key": "--tab-text-color",
        "value": "#0663f9"
      },
      {
        "css_key": "--tab-border-color",
        "value": "#0663f9"
      }, // Add additional theming options here
    ]
  }
}