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 Required	string	URL to a logo image.
faviconUrl Required	string	URL to a favicon image.
colors Required	object	Color palette
typography Required	object	Typography (text) preferences
buttons Required	object	buttons states preferences
menuButton Required	object	menu-button states preferences
menu Required	object	menu preferences
anchorButton Required	object	anchor button preferences
avatar Required	object	avatar preferences
cardIcon Required	object	card icon preferences
sidebar Required	object	sidebar preferences
whiteLabelAppBox Required	object	application box preferences
whiteLabelAppHeader Required	object	application header preferences
admonition Required	object	admonition (alert) preferences
chip Required	object	chip preferences
box Required	object	box preferences
tabs Required	object	tab preferences
breadcrumbs Required	object	breadcrumbs preferences
fields Required	object	form field preferences

Colors

Name	Type	Description
background Required	string	Will be used as background color of the components, drop downs menus and inner flows.
primary Required	string	Will be used for buttons, icons, highlight fields that are in focus, cover elements.
secondary Required	string	The secondary brand color is used for secondary buttons.
neutral Required	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 Required	string	Semantic. Will be used in messages, toasts, statuses and alerts.
warning Required	string	Semantic. Will be used in messages, toasts, statuses and alerts.
error Required	string	Semantic. Will be used in messages, toasts, statuses and alerts.

Typography

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

Common

Name	Type	Description
fontFamily Required	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 Required	string	Font size for elements. Can be set to either relative or absolute units.
rootFontSize Required	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 Required	Title	The main title used in the Components. Examples include the Card title, Activity table title etc.
h3 Required	Title	The secondary title used in the Components. Examples include menus and empty states.
menuTitle Required	Title	The title used for mobile menus (card-menu, account-list menu, etc).
componentTitle Required	Title	The title applied to various components such as card and activity components.
bigNumber Required	BigNumber	The title used for big number displays in components.
flow Required	Flow	The titles used for a flow or series of steps in a component. (card-actions, payments flows, etc.)
response Required	Response	The titles used for a response or message in components.
emptyState Required	EmptyState	The titles displayed in empty states within component.
table Required	Table	The titles for tables used in components.

Title

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

Big Number

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

Flow

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

Response

Name	Type	Description
title Required	Title	The title for the response.

Empty State

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

Table

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

Buttons

Name	Type	Description
fontWeight Required	100 , 200 , 300 , 400 , 500 , 600 , 700 , 800 , 900 , 950 , "normal" , "bold" , "bolder" , "lighter"	Font weight for buttons. Omit to use the default.
primary Required	ButtonStates	The primary style of the button.
secondary Required	ButtonStates	A secondary style option for the button.
subtle Required	ButtonStates	A subtle style option for the button.
outline Required	ButtonStates	An outlined style option for the button.
flat Required	ButtonStates	A flat style option for the button.

Example:

{
  "global": {
    "buttons": {
      "fontWeight": 600
    }
  }
}

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

Button States

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

Button Attributes

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

Border

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

Controls the appearance of action menus across components (for example, card actions, account actions, and selection menus).

Name	Type	Description
actionItems Required	object	Action menu item preferences.

Name	Type	Description
fontWeight Required	100 , 200 , 300 , 400 , 500 , 600 , 700 , 800 , 900 , 950 , "normal" , "bold" , "bolder" , "lighter"	Font weight for menu action items. Omit to use the default.

Example:

{
  "global": {
    "menu": {
      "actionItems": {
        "fontWeight": 600
      }
    }
  }
}

Anchor Button

Controls the default color for anchor buttons (text-style link buttons) across components.

Name	Type	Description
defaultColor Required	string	Default color for anchor buttons. Accepted values: `"primary"`, `"neutral"`. Omit to use the default (`"primary"`).

Example:

{
  "global": {
    "anchorButton": {
      "defaultColor": "neutral"
    }
  }
}

Avatar

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

Card Icon

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

White Label App Box

Styles the container box used in application form flows.

Name	Type	Description
backgroundColor Required	string	Will control the background color of the box.
borderRadius Required	string	Will control the border radius of the box.
borderColor Required	string	Will control the border color of the box.
boxShadow Required	string	Will control the box shadow of the box.

Styles the header used in application form flows.

Name	Type	Description
actions Required	object	Header action preferences.

Name	Type	Description
fontSize Required	string	Will control the font size of header actions.
iconSize Required	string	Will control the icon size of header actions.

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 Required	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 Required	string	Will be used as background color of the sidebar.
primary Required	string	Will be used for primary elements inside the sidebar, such as the active step indicator.
secondary Required	string	The secondary brand color used inside the sidebar.
neutral Required	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 Required	string	Semantic. Will be used in informational sidebar messages and statuses.
success Required	string	Semantic. Will be used in sidebar messages, toasts, statuses and alerts.
warning Required	string	Semantic. Will be used in sidebar messages, toasts, statuses and alerts.
error Required	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.

Admonition

Controls the appearance of admonition (alert) components used across White-label UIs — for example, informational, success, warning, and error callouts.

Name	Type	Description
borderWidth Required	string	Border width around the admonition. Accepts any valid CSS length value (for example, `"1px"`). Omit to use the default (no border).
hideBackground Required	boolean	When `true`, removes the admonition background color so only the border and icon remain visible. Default is `false`.

Example:

{
  "global": {
    "admonition": {
      "borderWidth": "1px",
      "hideBackground": false
    }
  }
}

Chip

Controls the default rendering style for chip components (for example, status labels on accounts and cards).

Name	Type	Description
outline Required	boolean	When `true`, chips render with an outlined style (border and transparent background) instead of a filled style. Default is `false`.

Example:

{
  "global": {
    "chip": {
      "outline": true
    }
  }
}

Box

Controls the default rendering style for box (container) components.

Name	Type	Description
subtleToOutline Required	boolean	When `true`, boxes with the `subtle` variant render as outlined containers (border with transparent background) instead of filled subtle boxes. Default is `false`.

Example:

{
  "global": {
    "box": {
      "subtleToOutline": true
    }
  }
}

Tabs

Controls the appearance of tab navigation across components.

Name	Type	Description
activeColor Required	string	Accent color for the active tab. Accepted values: `"primary"`, `"neutral"`. Omit to use the default (`"neutral"`).

Example:

{
  "global": {
    "tabs": {
      "activeColor": "primary"
    }
  }
}

Breadcrumbs

Controls the appearance of breadcrumb navigation across components.

Name	Type	Description
fontSize Required	string	Font size for breadcrumb text. Omit to use the default.
activeItem Required	object	Active breadcrumb item preferences.

Active Item

Name	Type	Description
fontWeight Required	100 , 200 , 300 , 400 , 500 , 600 , 700 , 800 , 900 , 950 , "normal" , "bold" , "bolder" , "lighter"	Font weight for the active breadcrumb item. Omit to use the default.

Example:

{
  "global": {
    "breadcrumbs": {
      "fontSize": "14px",
      "activeItem": {
        "fontWeight": 600
      }
    }
  }
}

Fields

Controls the appearance of form fields (inputs, selects, text areas, and their labels) across components.

Name	Type	Description
input Required	object	Input control preferences.
label Required	object	Field label preferences.

Input

Name	Type	Description
size Required	string	Input size preset. Accepted values: `"small"`, `"medium"`. Omit to use the default size.
border Required	object	Input border preferences.

Border

Name	Type	Description
width Required	string	Border width for inputs. Accepts any valid CSS length value (for example, `"1px"`).
radius Required	string	Border radius for inputs. Accepts any valid CSS length value (for example, `"6px"`).

Label

Name	Type	Description
fontWeight Required	string	Font weight for field labels. Accepted values: `"bold"`, `"regular"`. Omit to use the default (`"bold"`).

Example:

{
  "global": {
    "fields": {
      "input": {
        "size": "medium",
        "border": {
          "width": "1px",
          "radius": "6px"
        }
      },
      "label": {
        "fontWeight": "regular"
      }
    }
  }
}

Component Specific Settings

Card

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

Card Design

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

Account

Name	Type	Description
titleColor Required	string	Will control the font color of the account title
balanceTitleColor Required	string	Will control the font color of the balance title
coverBackgroundColor Required	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": {
    "selectionStageIconsPrimaryColor": true,
    "override": {
      "global": {
        "sidebar": {
          "colors": {
            "background": "#0B1020",
            "neutral": "#0B1020"
          }
        }
      }
    }
  }
}

Name	Type	Description
override Required	Global	Global overrides scoped to the Application Form, including a sidebar palette.
selectionStageIconsPrimaryColor Required	boolean	When `true`, icons in the Application Form account-type selection stage use the theme's `primary` color. Default is `false`.
sidebarBackgroundColor Required	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 Required	string	Theme Name.
global Required	object	Global theme setup.
elementsCard Required	object	Card element setup.
elementsActivity Required	object	Activity element setup.
elementsAccount Required	object	Account theme setup.
elementsPayment Required	object	Payment theme setup.
elementsApplicationForm Required	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 Required	object	The requested resource after the operation was completed.
links Required	object	Related Link object with url to be used in component.

Name	Type	Description
type Required	String	Type of the resource in link.
href Required	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}"

Customization Options​

Global Settings​

Colors​

Typography​

Common​

Titles​

Title​

Big Number​

Flow​

Response​

Empty State​

Table​

Buttons​

Menu Button​

Button States​

Button Attributes​

Border​

Menu​

Action Items​

Anchor Button​

Avatar​

Card Icon​

White Label App Box​

White Label App Header​

Actions​

Sidebar​

Sidebar Colors​

Admonition​

Chip​

Box​

Tabs​

Breadcrumbs​

Active Item​

Fields​

Input​

Border​

Label​

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

Menu

Action Items

Anchor Button

Avatar

Card Icon

White Label App Box

White Label App Header

Actions

Sidebar

Sidebar Colors

Admonition

Chip

Box

Tabs

Breadcrumbs

Active Item

Fields

Input

Border

Label

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