Themes

Unit's White-label UIs support multiple Themes. In order to create a new Theme, you would need to upload a JSON that contains the White-label settings associated with that theme via an API. In response, you will get a URL. You will then specify that URL as you initialize any UI Component, under the theme attribute.

The best way to understand how to use the White-label Themes is to see them in action. Try out the Component Preview page in order to make a Component look and feel like your brand. Once you are happy with the result, you can copy the JSON settings from under the 'Appearance Config' tab in the preview page, and create the theme by uploading the JSON to the API.

After creating the theme, you can use the link from the response to apply the theme to UI components. Here's an example with an account component:

<unit-elements-account
  account-id="12345"
  customer-token="{{customerToken}}"
  theme="https://ui.s.unit.sh/resources/1/themes/291ccb0e-9447-4010-98ef-0b9bf0fd04dc.json"
></unit-elements-account>

Customization Options

The settings that make up a theme are divided into two main categories - global settings and component specific settings.

Global settings are meant to reflect your brand's design system - colors, fonts, basic component look and feel.
Component specific settings are meant to allow you to control UI Elements that are unique to a specific Component (e.g. the color of the font on a card image). On the component specific level, you may also provide overrides to any parameter specified in the global settings.

Note

Please reach out to Unit if you need additional customization options to support your brand.

Global Settings

This object located on the root of the theme JSON object, but it can also be overridden on the component level.

Name	Type	Description
logoUrl	string	URL to a logo image.
faviconUrl	string	URL to a favicon image.
colors	object	Color palette
typography	object	Typography (text) preferences
buttons	object	buttons states preferences
menuButton	object	menu-button states preferences
avatar	object	avatar preferences
cardIcon	object	card icon preferences
sidebar	object	sidebar preferences

Colors

Name	Type	Description
background	string	Will be used as background color of the components, drop downs menus and inner flows.
primary	string	Will be used for buttons, icons, highlight fields that are in focus, cover elements.
secondary	string	The secondary brand color is used for secondary buttons.
neutral	string	We will derive 6 neutral shades based on your main Neutral color. These shades will be used for texts, light background colors and disabled/inactive elements.
success	string	Semantic. Will be used in messages, toasts, statuses and alerts.
warning	string	Semantic. Will be used in messages, toasts, statuses and alerts.
error	string	Semantic. Will be used in messages, toasts, statuses and alerts.

Typography

Name	Type	Description
common	object	Common typography settings (running texts).
titles	object	Titles typography settings.

Common

Name	Type	Description
fontFamily	string	Font family for Elements. Note, the Components components will not fetch the font. Font should be available on the page from which the Components are used.
fontSize	string	Font size for elements. Can be set to either relative or absolute units.
rootFontSize	string	Sets the base font size, similar to applying font-size on :root or the "html" element. Affects text scaling and all relative-based units within the component.

Titles

Name	Type	Description
h2	Title	The main title used in the Components. Examples include the Card title, Activity table title etc.
h3	Title	The secondary title used in the Components. Examples include menus and empty states.
menuTitle	Title	The title used for mobile menus (card-menu, account-list menu, etc).
componentTitle	Title	The title applied to various components such as card and activity components.
bigNumber	BigNumber	The title used for big number displays in components.
flow	Flow	The titles used for a flow or series of steps in a component. (card-actions, payments flows, etc.)
response	Response	The titles used for a response or message in components.
emptyState	EmptyState	The titles displayed in empty states within component.
table	Table	The titles for tables used in components.

Title

Name	Type	Description
fontWeight	100 , 200 , 300 , 400 , 500 , 600 , 700 , 800 , 900 , 950 , "normal" , "bold" , "bolder" , "lighter"	The thickness or boldness of the font.
color	string	The color of the text in the title.
fontSize	string	The size of the font used in the title.
fontFamily	string	The specific font family for the title's text.

Big Number

Name	Type	Description
fontWeight	100 , 200 , 300 , 400 , 500 , 600 , 700 , 800 , 900 , 950 , "normal" , "bold" , "bolder" , "lighter"	The thickness or boldness of the font.
color	string	The color of the text in the big number display.
fontFamily	string	The specific font family for the big number text.
largeFontSize	string	The font size for larger big number displays.
extraLargeFontSize	string	The font size for extra-large big number displays.

Flow

Name	Type	Description
title	Title	The main title for the flow.
subtitle	Title	The secondary title for the flow.

Response

Name	Type	Description
title	Title	The title for the response.

Empty State

Name	Type	Description
title	Title	The title displayed in the empty state.

Table

Name	Type	Description
headers	Title	The titles for the table headers.

Buttons

Name	Type	Description
primary	ButtonStates	The primary style of the button.
secondary	ButtonStates	A secondary style option for the button.
subtle	ButtonStates	A subtle style option for the button.
outline	ButtonStates	An outlined style option for the button.
flat	ButtonStates	A flat style option for the button.

Name	Type	Description
default	ButtonAttributes	The default style of the menu button.
hover	ButtonAttributes	The style when the button is hovered.
active	ButtonAttributes	The style when the button is active.
disabled	ButtonAttributes	The style when the button is disabled.

Button States

Name	Type	Description
default	ButtonAttributes	The default style of the menu button.
hover	ButtonAttributes	The style when the button is hovered.
active	ButtonAttributes	The style when the button is active.
disabled	ButtonAttributes	The style when the button is disabled.

Button Attributes

Name	Type	Description
border	Border	The border attributes for the button.
textColor	string	The color of the text in the button.
backgroundColor	string	The background color of the button.

Border

Name	Type	Description
width	string	The width of the border around the element.
radius	string	The border radius or curvature of the element's corners.
color	string	The color of the border around the element.

Avatar

Name	Type	Description
iconColor	string	Will control the color of the icon.
borderColor	string	Will control the color of the border.
backgroundColor	string	Will control the color of the background.

Card Icon

Name	Type	Description
backgroundColor	string	Will control the color of the background.
visaTextColor	string	Will control the color of the Visa text.

Controls the color palette for sidebars rendered by Components (for example, the stages sidebar in unit-elements-application-form or unit-elements-create-card). Setting this object re-derives the sidebar's text, border and icon colors from the seed colors, so a dark sidebar stays legible.

Name	Type	Description
colors	object	Sidebar color palette.

Accepts the same shape as the top-level colors palette. The SDK derives the sidebar's text, border and icon colors from these seeds to preserve contrast.

Name	Type	Description
background	string	Will be used as background color of the sidebar.
primary	string	Will be used for primary elements inside the sidebar, such as the active step indicator.
secondary	string	The secondary brand color used inside the sidebar.
neutral	string	We will derive 6 neutral shades based on your main Neutral color. These shades will be used for sidebar texts, borders, icons and disabled/inactive elements.
info	string	Semantic. Will be used in informational sidebar messages and statuses.
success	string	Semantic. Will be used in sidebar messages, toasts, statuses and alerts.
warning	string	Semantic. Will be used in sidebar messages, toasts, statuses and alerts.
error	string	Semantic. Will be used in sidebar messages, toasts, statuses and alerts.

Example — theme-wide sidebar palette (applies everywhere a sidebar is shown):

{
  "global": {
    "sidebar": {
      "colors": {
        "primary": "#4F46E5",
        "neutral": "#0B1020",
        "background": "#0B1020"
      }
    }
  }
}

To scope the palette to a single component (for example, only the Application Form sidebar), set the same object under that component's override.global.sidebar. See Application Form.

Component Specific Settings

Card

Name	Type	Description
designs	Array of Design	The main title used in the Components. Examples include the Card title, Activity table title etc
override	Global	The secondary title used in the Components. Examples include menus and empty states

Card Design

Name	Type	Description
name	string	Name of your design, should match the name of Card design in Unit. For charge cards the name must contain "_credit".
url	string	Link to Card image
fontColor	string	Will control the font color on top of the Card
boxShadow	string	Will control the Card shadow

Account

Name	Type	Description
titleColor	string	Will control the font color of the account title
balanceTitleColor	string	Will control the font color of the balance title
coverBackgroundColor	string	Will control the color of the cover background

Application Form

Applies to unit-elements-application-form. To recolor the Application Form sidebar without affecting other Components that render a sidebar, set Sidebar colors under override.global.sidebar:

{
  "elementsApplicationForm": {
    "override": {
      "global": {
        "sidebar": {
          "colors": {
            "background": "#0B1020",
            "neutral": "#0B1020"
          }
        }
      }
    }
  }
}

Name	Type	Description
override	Global	Global overrides scoped to the Application Form, including a sidebar palette.
sidebarBackgroundColor	string	Deprecated. Background color of the Application Form sidebar. Prefer the sidebar palette instead.

Important Info

elementsApplicationForm.sidebarBackgroundColor still works but is discouraged. It recolors only the background — sidebar text, borders and icons are not re-derived, so a dark value can produce unreadable content. It exists for backwards-compatibility only.

Prefer setting global.sidebar.colors, or scope it to the Application Form via elementsApplicationForm.override.global.sidebar.colors. These drive the full palette (primary, secondary, neutral, background, info, success, warning, error) and re-derive contrasting text, border and icon colors.

Precedence

When multiple sidebar settings are provided, the background color is resolved in this order (first match wins):

elementsApplicationForm.override.global.sidebar.colors.background — element-scoped palette.
global.sidebar.colors.background — theme-wide palette.
elementsApplicationForm.sidebarBackgroundColor — legacy, deprecated.

Default Theme

You can set a default theme for all components in the Unit Dashboard under Org Settings → Branding. The dashboard displays all themes created by your organization, and the selected theme will be applied to all components by default unless a specific theme is provided.

Create Theme

Creates theme for white label components.

Verb	`POST`
URL	`https://api.s.unit.sh/white-label/theme`
Data Type	`whiteLabelTheme`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
name	string	Theme Name.
global	object	Global theme setup.
elementsCard	object	Card element setup.
elementsActivity	object	Activity element setup.
elementsAccount	object	Account theme setup.
elementsPayment	object	Payment theme setup.
elementsApplicationForm	object	Application Form element setup.

Example Request:

curl -X POST 'https://api.s.unit.sh/white-label/theme'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "whiteLabelTheme",
    "attributes": {
      "name": "VIP Theme",
      "global": {
        "colors": {
          "background": "#2223334",
          "primary": "#0000F0",
          "secondary": "#000000",
          "neutral": "#FF9933",
          "success": "#0CD96F",
          "warning": "#FF9933",
          "error": "#FF4F64"
        },
        "typography": {
          "common": {
            "fontFamily": "sans-serif"
          },
          "titles": {
            "h2": {
              "fontWeight": "800"
            },
            "h3": {
              "fontWeight": "800"
            }
          }
        }
      },
      "elementsCard": {
        "designs": [
          {
            "name": "default",
            "url": "https://d1xlopvhx2cz8k.cloudfront.net/resources/outlay.png",
            "fontColor": "#00ff00",
            "boxShadow": "0px 3.6px 15px 2px rgb(0 0 0 / 0.25)"
          }
        ]
      },
      "elementsAccount": {
        "override": {
          "global": {
            "colors": {
              "background": "#00ff00"
            }
          }
        }
      },
      "elementsPayment": {
        "override": {
          "global": {
            "typography": {
              "common": {
                "fontFamily": "Poppins"
              }
            }
          }
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Name	Type	Description
data	object	The requested resource after the operation was completed.
links	object	Related Link object with url to be used in component.

Name	Type	Description
type	String	Type of the resource in link.
href	object	URL to be set in theme property of component.

Example Response:
{
  "data": {
    "type": "whiteLabelTheme",
    "id": "10008",
    "attributes": {
      "...": "..."
    },
    "links": {
      "related": {
        "type": "application/json",
        "href": "https://ui.s.unit.sh/resources/982/themes/605676c1-b00b-4748-9fa4-258d1a28c3fb.json"
      }
    }
  }
}

Update Theme

Updates theme for white label components.

Note

You need to send the full theme object in the request body, not only the fields that were changed.

Verb	`PUT`
URL	`https://api.s.unit.sh/white-label/theme/{id}`
Data Type	`whiteLabelTheme`
Timeout (Seconds)	`5`

Example Request:

curl --request PUT 'https://api.s.unit.sh/white-label/theme/{id}' \
--header 'Content-Type: application/vnd.api+json' \
--data-raw '{
  "data": {
    "type": "whiteLabelTheme",
    "attributes": {
      "name": "VIP Theme",
      "global": {
        "colors": {
          "background": "#2223334",
          "primary": "#0000F0",
          "secondary": "#000000",
          "neutral": "#FF9933",
          "success": "#0CD96F",
          "warning": "#FF9933",
          "error": "#FF4F64"
        },
        "typography": {
          "common": {
            "fontFamily": "sans-serif"
          },
          "titles": {
            "h2": {
              "fontWeight": "800"
            },
            "h3": {
              "fontWeight": "800"
            }
          }
        }
      },
      "elementsCard": {
        "designs": [
          {
            "name": "default",
            "url": "https://d1xlopvhx2cz8k.cloudfront.net/resources/outlay.png",
            "fontColor": "#00ff00",
            "boxShadow": "0px 3.6px 15px 2px rgb(0 0 0 / 0.25)"
          }
        ]
      },
      "elementsAccount": {
        "override": {
          "global": {
            "colors": {
              "background": "#00ff00"
            }
          }
        }
      },
      "elementsPayment": {
        "override": {
          "global": {
            "typography": {
              "common": {
                "fontFamily": "Poppins"
              }
            }
          }
        }
      }
    }
  }
}'

Get Theme

Get white label theme by id.

Verb	`GET`
URL	`https://api.s.unit.sh/white-label/theme/{id}`
Data Type	`whiteLabelTheme`
Timeout (Seconds)	`5`

Example Request:

curl -X GET 'https://api.s.unit.sh/white-label/theme/{id}' \
-H "Authorization: Bearer ${TOKEN}"

List

List themes resources. Paging and sorting can be applied.

Verb	`GET`
URL	`https://api.s.unit.sh/white-label/theme`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Optional. Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]	integer	0	Optional. Number of resources to skip. See Pagination.
filter[fileName]	string	(empty)	Optional. Find by file name.
sort	string	`sort=-createdAt`	Optional. `sort=createdAt` for ascending order or `sort=-createdAt` (leading minus sign) for descending order.

curl -X GET 'https://api.s.unit.sh/white-label/theme?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"

Themes

Customization Options

Global Settings

Colors

Typography

Common

Titles

Title

Big Number

Flow

Response

Empty State

Table

Buttons

Menu Button

Button States

Button Attributes

Border

Avatar

Card Icon

Sidebar

Sidebar Colors

Component Specific Settings

Card

Card Design

Account

Application Form

Precedence

Default Theme

Create Theme

Attributes

Response

201 Created

Update Theme

Get Theme

List

Query Parameters

Customization Options​

Global Settings​

Colors​

Typography​

Common​

Titles​

Title​

Big Number​

Flow​

Response​

Empty State​

Table​

Buttons​

Menu Button​

Button States​

Button Attributes​

Border​

Avatar​

Card Icon​

Sidebar​

Sidebar Colors​

Component Specific Settings​

Card​

Card Design​

Account​

Application Form​

Precedence​

Default Theme​

Create Theme​

Attributes​

Response​

201 Created​

Related​

Update Theme​

Get Theme​

List​

Query Parameters​

Customization Options

Global Settings

Colors

Typography

Common

Titles

Title

Big Number

Flow

Response

Empty State

Table

Buttons

Menu Button

Button States

Button Attributes

Border

Avatar

Card Icon

Sidebar

Sidebar Colors

Component Specific Settings

Card

Card Design

Account

Application Form

Precedence

Default Theme

Create Theme

Attributes

Response

201 Created

Related

Update Theme

Get Theme

List

Query Parameters