Themes

Unit's UI components support multiple Themes. In order to create a new Theme, you would need to upload a JSON that contains the 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 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
menu	object	menu preferences
anchorButton	object	anchor button preferences
avatar	object	avatar preferences
cardIcon	object	card icon preferences
sidebar	object	sidebar preferences
whiteLabelAppBox	object	application box preferences
whiteLabelAppHeader	object	application header preferences
admonition	object	admonition (alert) preferences
chip	object	chip preferences
box	object	box preferences
tabs	object	tab preferences
breadcrumbs	object	breadcrumbs preferences
fields	object	form field 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
fontWeight	100 , 200 , 300 , 400 , 500 , 600 , 700 , 800 , 900 , 950 , "normal" , "bold" , "bolder" , "lighter"	Font weight for buttons. Omit to use the default.
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.

Example:

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

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.

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

Name	Type	Description
actionItems	object	Action menu item preferences.

Name	Type	Description
fontWeight	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	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	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.

White Label App Box

Styles the container box used in application form flows.

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

Styles the header used in application form flows.

Name	Type	Description
actions	object	Header action preferences.

Name	Type	Description
fontSize	string	Will control the font size of header actions.
iconSize	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	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.

Admonition

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

Name	Type	Description
borderWidth	string	Border width around the admonition. Accepts any valid CSS length value (for example, `"1px"`). Omit to use the default (no border).
hideBackground	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	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	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	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	string	Font size for breadcrumb text. Omit to use the default.
activeItem	object	Active breadcrumb item preferences.

Active Item

Name	Type	Description
fontWeight	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	object	Input control preferences.
label	object	Field label preferences.

Input

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

Border

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

Label

Name	Type	Description
fontWeight	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	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": {
    "selectionStageIconsPrimaryColor": true,
    "override": {
      "global": {
        "sidebar": {
          "colors": {
            "background": "#0B1020",
            "neutral": "#0B1020"
          }
        }
      }
    }
  }
}

Name	Type	Description
override	Global	Global overrides scoped to the Application Form, including a sidebar palette.
selectionStageIconsPrimaryColor	boolean	When `true`, icons in the Application Form account-type selection stage use the theme's `primary` color. Default is `false`.
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 UI components.

Note

Creating, updating, and listing themes does not require any scopes. Authenticate with a valid organization API token.

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