Skip to main content

Theming and Fonts

Global Theming​

HAPI Elements has some global color variables that make it easy to rebrand the widgets. To check which color variables you can pass, please refer to ThemeGlobalStyles TypeScript Type Definition.


note

Please note that for the colors, we need Hex colors in the three, six or eight digit format. Examples:

  • #000
  • #000000
  • #00000000

These variables are used throughout the app to have a consistent looking UI. For example, changing the borderRadius, will change several different components inside the widgets such as Input, Select, Button, Badges, Cards.


Once these variables are overwritten, the look of the app will change. To change the global colors, use the following SDK function:
window.hapi.theming.state.theme = {
    global: {
        borderRadius: "4px",
        primaryBackgroundColor: "#346CA7",
        primaryTextColor: "#FFF",
    },
}
info

You can use window.hapiUtils.mergeDeepOverwriteArrays utility function that merges two deeply nested objects together while overwriting the arrays.

Example:

// immutable
const updatedObject = window.hapiUtils.mergeDeepOverwriteArrays(originalObject, overwritesObject)

How to adjust theming further​

Apart from the global variables, which adjusts only portion of the UI, there is also the ability to style reusable components and some other exceptional areas of the application. The areas available for customization are listed in HapiThemeRule TypeScript Type Definition.

HAPI Elements uses JSS and Extend Plugin to convert the JS Objects to CSS Classes.


Let's first check how a button is styled by default with the following SDK function:

const theme = window.hapi.theming.state.theme.value;

const buttonBaseStyle = theme.buttonBase
console.log('[HAPI][theme/buttonBaseStyle]', buttonBaseStyle)

Then you can basically change the entire object, override properties and/or extend by adding additional properties:

caution

If you don't pass the existing values of the theme as ...theme to the updated theme object, then the theme object would get overwritten, and you would lose any other theming variables that you have set previously.

const newButtonBaseStyle = {
    ...buttonBaseStyle,
    borderStyle: "dashed"
}
window.hapi.theming.state.theme = {
    // must have not to overwrite the entire object
    // and remove accidentally existing theming properties
    ...theme,
    buttonBase: newButtonBaseStyle
}

Font Options​

To change the font, use the following SDK function:

window.hapi.theming.state.fontOptions = {
    fontFaces: [
        {
            fontFamily: "Poppins",
            src: `url('https://YOUR-DOMAIN.com/Poppins-Regular.ttf') format('opentype')`,
        },
    ],
    fontFamily: "Poppins",
}

Using above method of setting the font will add a style tag to Elements application that does:

@font-face {
    font-family: "${fontFace.fontFamily}";
    src: ${fontFace.src};
}

Alternatively if you are using the font via the <link> tag, you can add property rel: 'stylesheet' to the object inside fontFaces which will load the font via:

<link href={fontFace.src} rel="stylesheet" />

Combining Theming and Font Options​

You can pass multiple font faces using the fontFaces array, with the default font being the fontFamily in the fontOptions object then use the theme setter example given above to add fontFamily: YOURSECONDFONTNAME property to the component you want to have a different font.

FAQs​

Is there a way to change the theme and font in a single function execution?​

Not all ATSs need to change the theme, but only the font. We want to keep these two functionalities apart, for separation of concerns.