# Hosted Widget Branding and Customization (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
- Custom messaging for consent purpose
- Add a custom overlay color
- Hide messaging in the institution select screen
- 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`. For a full example of how this looks like, see the code example below.

## 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 screen:

- 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.


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

## Add a company logo

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.


```json Company Logo
{
  "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.


```json Company Name
{
  "widget": {
    "branding": {
      ...
      "company_name": "ACME",
      ...
        }
     }
}
```

## Add a link to your privacy policy

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.


```curl Company Terms URL
{
  "widget": {
    "branding": {
      ...
      "company_terms_url": "https://belvo.com/terms-service/",
      ...
        }
     }
}
```

## Custom messaging for consent purpose

You can modify the text describing the purpose for requesting your user's data (*Propósito do compartilhamento*) to better describe your use case.

By default, the displayed text is: _Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito. _

**Instructions**

To customize the text describing the purpose for requesting access to your user's data, just add your text (maximum 600 characters) to the `purpose` key.


```json Consent Purpose
{
  "widget": {
    "consent": {
       "purpose": "Your custom text here. Max 600 characters",
       ...
    }
  }   
}
```

## 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.


```json Overlay Background
{
  "widget": {
    "branding": {
      ...
      "overlay_background_color": "#F0F2F4",
      ...
        }
     }
}
```

## Hide messaging in the institution select screen

You can choose to hide the "*Mais de 5 milhões de usuários já conectaram com segurança suas contas.*" message that appears when your user selects their institution in the widget. By default, this message is visible in the widget (`true`).

**Instructions**

To hide the message in the institution select screen, just set the `social_proof` parameter to `false`.


```json Social Proof
{
  "widget": {
    "branding": {
      ...
      "social_proof": false,
      ...
        }
     }
}
```

## 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.


```json
{
  "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"`.

OFDA Dark Mode
## Add custom colors to the widget

You can further 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 Variable | Default (Light) | Default (Dark) | Description |
|  --- | --- | --- | --- |
| `--color-primary-base` | `#0663F9` | `#0663F9` | Sets the primary color for buttons, checkboxes, and the progress bar. |
| `--nav-bar-title-color` | `#161A1D` | `#011432` | Sets the color of the navigation bar title. |
| `--nav-bar-icon-color` | `#161A1D` | `#011432` | Sets 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

```json 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"
      }
    ],
  }
}
```

Dark

```json Dark Mode Example
{
  "widget": {
    "color_scheme": "DARK",
    "branding": {}, // Your customized branding
    "theme": [
      {
        "css_key": "--color-primary-base",
        "value": "#0663F9"
      },
      {
        "css_key": "--nav-bar-title-color-dark",
        "value": "#011432"
      },
      {
        "css_key": "--nav-bar-icon-color-dark",
        "value": "#011432"
      }
    ],
  }
}
```

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 Variable | Default (Light) | Default (Dark) | Description |
|  --- | --- | --- | --- |
| `--nav-bar-title-color` | `#161a1d` | `#011432` | Sets the color of the navigation bar title. |
| `--nav-bar-title-align` | `center` | `center` | Specifies the alignment of the navigation bar title. Possible positions are: `center`, `start`, and `end`. |
| `--nav-bar-icon-color` | `#161a1d` | `#011432` | Sets the color of navigation bar icons. |
| `--nav-bar-background-color` | `#ffffff` | `#011432` | Defines the background color of the navigation bar. |
| `--nav-bar-box-shadow` | `none` | `none` | Adds a shadow effect to the navigation bar. |
| `--nav-bar-border-color` | `#f0f2f4` | `#2B3D54` | Specifies 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

```json 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
    ]
  }
}
```

Dark

```json Dark Mode Example
{
  "widget": {
    "color_scheme": "DARK",
    "branding": {}, // Your customized branding
    "theme": [
      {
        "css_key": "--nav-bar-title-color-dark",
        "value": "#011432"
      },
      {
        "css_key": "--nav-bar-title-align",
        "value": "center"
      },
      {
        "css_key": "--nav-bar-icon-color-dark",
        "value": "#011432"
      },
      {
        "css_key": "--nav-bar-background-color-dark",
        "value": "#011432"
      },
      {
        "css_key": "--nav-bar-box-shadow",
        "value": "none"
      },
      {
        "css_key": "--nav-bar-border-color-dark",
        "value": "#2B3D54"
      }, // 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 Variable | Default (Light) | Default (Dark) | Description |
|  --- | --- | --- | --- |
| `--button-font-color` | `#ffffff` | `#EEF3F8` | Sets the font color for buttons. |
| `--button-font-color-disabled` | `#ffffff` | `#EEF3F8` | Defines the font color for disabled buttons. |
| `--button-border-radius` | `2px` | `2px` | Specifies the border radius of buttons. |
| `--button-background-color-disabled` | `#009EE3` | `#0663F9` | Defines the background color for disabled buttons. |
| `--button-opacity-disabled` | `0.2` | `0.2` | Specifies the opacity for disabled buttons. |
| `--button-border-color-disabled` | `#09EE354` | `#09EE354` | Sets 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

```json 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
    ]
  }
}
```

Dark

```json Dark Mode Example
{
  "widget": {
    "color_scheme": "DARK",
    "branding": {}, // Your customized branding
    "theme": [
      {
        "css_key": "--button-font-color-dark",
        "value": "#EEF3F8"
      },
      {
        "css_key": "--button-font-color-disabled-dark",
        "value": "#EEF3F8"
      },
      {
        "css_key": "--button-border-radius",
        "value": "2px"
      },
      {
        "css_key": "--button-background-color-disabled-dark",
        "value": "#0663F9"
      },
      {
        "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 Variable | Default (Light) | Default (Dark) | Description |
|  --- | --- | --- | --- |
| `--banner-border-radius` | `4px` | `4px` | Specifies the border radius of banners. |
| `--banner-background-color` | `#ffffff` | `#011432` | Sets the background color of banners. |
| `--banner-border-color` | `#e2e6e9` | `#2B3D54` | Specifies the border color of banners. |
| `--banner-border-color-left-error` | `#f90e06` | `#E04A39` | Left border color for error banners. |
| `--banner-border-color-left-success` | `#59c837` | `#59C837` | Left border color for success banners. |
| `--banner-border-color-left-info` | `#0663F9` | `#0663F9` | Left border color for info banners. |
| `--banner-border-color-left-warning` | `#f9c806` | `#F9C806` | Left border color for warning banners. |
| `--banner-icon-color-error` | `#f90e06` | `#E04A39` | Icon color for error banners. |
| `--banner-icon-color-success` | `#59c837` | `#59C837` | Icon color for success banners. |
| `--banner-icon-color-info` | `#0663F9` | `#0663F9` | Icon color for info banners. |
| `--banner-icon-color-warning` | `#f9c806` | `#F9C806` | Icon color for warning banners. |
| `--banner-title-color` | `#161a1d` | `#EEF3F8` | Sets the color of banner titles. |
| `--banner-body-color` | `#414d58` | `#C2CFD9` | Specifies the color of banner body text. |
| `--banner-title-font-weight` | `600` | `600` | Defines the font weight of banner titles. |
| `--banner-body-font-weight` | `600` | `600` | Specifies the font weight of banner body text. |
| `--banner-box-shadow` | `0 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

```json 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
    ]
  }
}
```

Dark

```json Dark Mode Example
{
  "widget": {
    "color_scheme": "DARK",
    "branding": {}, // Your customized branding
    "theme": [
      {
        "css_key": "--banner-border-radius",
        "value": "4px"
      },
      {
        "css_key": "--banner-background-color-dark",
        "value": "#011432"
      },
      {
        "css_key": "--banner-border-color-dark",
        "value": "#2B3D54"
      },
      {
        "css_key": "--banner-border-color-left-error-dark",
        "value": "#E04A39"
      },
      {
        "css_key": "--banner-border-color-left-success-dark",
        "value": "#59C837"
      },
      {
        "css_key": "--banner-border-color-left-info-dark",
        "value": "#0663F9"
      },
      {
        "css_key": "--banner-border-color-left-warning-dark",
        "value": "#F9C806"
      },
      {
        "css_key": "--banner-icon-color-error-dark",
        "value": "#E04A39"
      },
      {
        "css_key": "--banner-icon-color-success-dark",
        "value": "#59C837"
      },
      {
        "css_key": "--banner-icon-color-info-dark",
        "value": "#0663F9"
      },
      {
        "css_key": "--banner-icon-color-warning-dark",
        "value": "#F9C806"
      },
      {
        "css_key": "--banner-title-color-dark",
        "value": "#EEF3F8"
      },
      {
        "css_key": "--banner-body-color-dark",
        "value": "#C2CFD9"
      },
      {
        "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 Variable | Default (Light) | Default (Dark) | Description |
|  --- | --- | --- | --- |
| `--input-text-border-radius` | `2px` | `2px` | Defines the border radius for input fields. |
| `--input-text-border-color` | `#161a1d` | `#2B3D54` | Specifies the border color for input fields. |
| `--input-text-outline-border-color` | `#c4cdd4` | `#3A4D64` | Defines the outline border color for input fields. (like hover effect) |
| `--input-text-placeholder-color` | `#c4cdd4` | `#2B3D54` | Defines the color for placeholder text. |
| `--input-text-label-color` | `#414d58` | `#EEF3F8` | Sets the label color for input fields. |
| `--input-text-label-color-error` | `#f90e06` | `#E04A39` | Specifies the label color for input fields in error state. |
| `--input-text-label-variation` | `outlined` | `outlined` | Specifies label variation position. Possible options are: `outlined` and `top`. |
| `--input-text-icon-color` | `#000000` | `#E04A39` | Sets 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

```json 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
    ]
  }
}
```

Dark

```json
{
  "widget": {
    "color_scheme": "DARK",
    "branding": {}, // Your customized branding
    "theme": [
      {
        "css_key": "--input-text-border-radius",
        "value": "2px"
      },
      {
        "css_key": "--input-text-border-color-dark",
        "value": "#2B3D54"
      },
      {
        "css_key": "--input-text-outline-border-color-dark",
        "value": "#3A4D64"
      },
      {
        "css_key": "--input-text-placeholder-color-dark",
        "value": "#2B3D54"
      },
      {
        "css_key": "--input-text-label-color-dark",
        "value": "#EEF3F8"
      },
      {
        "css_key": "--input-text-label-color-error-dark",
        "value": "#E04A39"
      },
      {
        "css_key": "--input-text-label-variation",
        "value": "outlined"
      },
      {
        "css_key": "--input-text-icon-color-dark",
        "value": "#E04A39"
      }, // 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 Variable | Default (Light) | Default (Dark) | Description |
|  --- | --- | --- | --- |
| `--tab-text-color` | `#0663f9` | `#0663f9` | Defines the text color for the tabs. |
| `--tab-border-color` | `#0663f9` | `#0663f9` | Specifies 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

```json 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
    ]
  }
}
```

Dark

```json Dark Mode Example
{
  "widget": {
    "color_scheme": "DARK",
    "branding": {}, // Your customized branding
    "theme": [
      {
        "css_key": "--tab-text-color",
        "value": "#0663f9"
      },
      {
        "css_key": "--tab-border-color",
        "value": "#0663f9"
      }, // Add additional theming options here
    ]
  }
}
```