Theming

The Borrower Dashboard Element is built with a strong emphasis on visual customization, giving you straightforward tools to adjust the overall look and feel you can offer to your users. The goal here is to create a single unified user experience between the Borrower Dashboard (the embedded application) and your application (the embedding application). You can customize the styling of the Borrower Dashboard by providing a theme prop on the BorrowerDashboard Element:

Prop	Type	Description
`theme`	`Theme`	Theme configuration object. See the Theme reference for complete documentation.

Theming approach

The theming approach is broken into 3 levels:

Level	Description
Global	Targets overarching design that crosses all pages, e.g. colors, fonts, borders etc.
Component	Targets specific design components that are seen site wide, e.g. text inputs, typography, cards, buttons etc.
Page	Targets specific elements on specific pages, e.g. card on welcome page, title on success page etc.

To apply theming at each of the 3 levels, you can specify different configuration on each of the level’s named properties on the configuration object. The Global and Component levels exist as named properties at the root level, whereas the Page level exists at the root level as well as inside of a defined Component at the root level:

We offer the Page property at both levels to help you organize your styles to suit your own needs-there is no right or wrong way.

import { BorrowerDashboardElement } from "@pylonlending/react-elements";

const ThemeConfig = {
  Global: {
    colors: {
      core: {
        primary: "blue",
      },
    },
  },
  Component: {
    Container: {
      Card: {
        background: "#FFFFFF",
        // We can define the styles for a card on a specific page here
        Page: {
          ".borrower-dashboard-preapproval-page .form-container .card": {
            background: "#EEEEEE",
          },
        },
      },
    },
  },
  Page: {
    // We can also define styles for a card on a specific page here.
    ".borrower-dashboard-address-page .form-container .card": {
      background: "#AAAAAA",
    },
  },
};

<BorrowerDashboardElement
  authLeaseCallback={fetchPylonAuthLease}
  loanId="loan_12345"
  theme={ThemeConfig}
/>

The theme is a completely optional prop at each of the 3 levels. If you’re using TypeScript, the type for it exists as Theme and will give you type ahead and feedback regarding type issues when you’re creating it.While we don’t advise it, any invalid properties or values in the theme configuration will simply be ignored and cause no issues to the functionality of the Borrower Dashboard.

Level 1: Global Theme configuration

Depending on your use case, the global option may be all that’s needed. This hits all of the typical global elements and follows patterns similar to other design frameworks that you may already be familiar with.

Global theme properties

The following table details which configurations are available at the global level:

Property	Type	Description	Example
`fonts.fontFamily`	`string`	Any valid CSS value for the `font-family` property. This sets the default font and will be applied to all text content unless overridden.	`"Inter"`
`fonts.fontUrls`	`string[]`	A string array of valid font URLs that we can load. We dynamically load these URLs into the head of the borrower dashboard allowing you access to any custom font you wish to use.	`["https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700"]`
`colors.core.primary`	`string`	Any valid CSS value for the `background-color` property. We use this to set the primary color according to our theme. This is applied to elements like the progress tracker, buttons, loaders, links, focused form input borders etc.	`"#ffffff"`
`colors.core.neutral`	`string`	Any valid CSS value for the `background-color` property. This is applied to elements like back buttons, cancel buttons, dividers, inactive form input borders etc.	`"#ffffff"`
`colors.core.error`	`string`	Any valid CSS value for the `background-color` property. This is applied to form input borders when errors are present and error boxes etc.	`"#ffffff"`
`colors.core.warning`	`string`	Any valid CSS value for the `background-color` property. This is applied to warning notification boxes.	`"#ffffff"`
`colors.core.success`	`string`	Any valid CSS value for the `background-color` property. This is applied to success icons for completed tasks, credit checks etc.	`"#ffffff"`
`colors.text.primary`	`string`	Any valid CSS value for the `color` property. This is applied to page titles, body text etc.	`"#ffffff"`
`colors.text.secondary`	`string`	Any valid CSS value for the `color` property. This is applied to sub-titles, sub text etc.	`"#ffffff"`
`colors.text.disabled`	`string`	Any valid CSS value for the `color` property. This is applied to disabled button text, disabled form text etc.	`"#ffffff"`
`colors.text.contrast`	`string`	Any valid CSS value for the `color` property. This is applied to text content in elements with the primary background color.	`"#ffffff"`
`colors.text.error`	`string`	Any valid CSS value for the `color` property. This is applied to form element text errors, text in error boxes etc.	`"#ffffff"`
`colors.text.warning`	`string`	Any valid CSS value for the `color` property. This is applied to text in warning boxes.	`"#ffffff"`
`colors.text.success`	`string`	Any valid CSS value for the `color` property. This is applied to text inside of success elements.	`"#ffffff"`
`colors.background.content`	`string`	Any valid CSS value for the `color` property. This is applied to the background of containers and cards.	`"#ffffff"`
`colors.background.application`	`string`	Any valid CSS value for the `background` property. This sets the background color of the borrower dashboard.	`"#ffffff"`
`colors.loanStatus.approved`	`{ backgroundColor: string; color?: string }`	Any valid CSS value for the `background-color` and `color` properties. This sets the loan status color for Approved.	`{ backgroundColor: "#4caf50" }`
`colors.loanStatus.inReview`	`{ backgroundColor: string; color?: string }`	Any valid CSS value for the `background-color` and `color` properties. This sets the loan status color for In Review.	`{ backgroundColor: "#757575" }`
`colors.loanStatus.preApproved`	`{ backgroundColor: string; color?: string }`	Any valid CSS value for the `background-color` and `color` properties. This sets the loan status color for Pre Approved.	`{ backgroundColor: "#9c27b0" }`
`colors.loanStatus.withdrawn`	`{ backgroundColor: string; color?: string }`	Any valid CSS value for the `background-color` and `color` properties. This sets the loan status color for Withdrawn.	`{ backgroundColor: "#000000" }`
`colors.loanStatus.suspended`	`{ backgroundColor: string; color?: string }`	Any valid CSS value for the `background-color` and `color` properties. This sets the loan status color for Suspended.	`{ backgroundColor: "#FFFFFF", color: "#000000" }`
`colors.loanStatus.declined`	`{ backgroundColor: string; color?: string }`	Any valid CSS value for the `background-color` and `color` properties. This sets the loan status color for Declined.	`{ backgroundColor: "#f44336" }`

Complete global theme example

import { BorrowerDashboardElement } from "@pylonlending/react-elements";

const ThemeConfig = {
  Global: {
    fonts: {
      fontFamily: "Inter, sans-serif",
      fontUrls: [
        "https://fonts.googleapis.com/css2?family=Inter:wght@400,500,600,700&display=swap",
      ],
    },
    colors: {
      core: {
        primary: "#2438EE",
        neutral: "#eeeeee",
        error: "#FF0000",
        warning: "#FF9033",
        success: "#4FD831",
      },
      text: {
        primary: "#000000",
        secondary: "#AAAAAA",
        disabled: "#EEEEEE",
        contrast: "#ffffff",
        error: "#FF0000",
        warning: "#FF9033",
        success: "#4FD831",
      },
      background: {
        application: "#F8F8F8",
        content: "#ffffff",
      },
      loanStatus: {
        approved: {
          backgroundColor: "#4caf50",
        },
        inReview: {
          backgroundColor: "#757575",
        },
        preApproved: {
          backgroundColor: "#9c27b0",
        },
        withdrawn: {
          backgroundColor: "#000000",
        },
        suspended: {
          backgroundColor: "#FFFFFF",
          color: "#000000",
        },
        declined: {
          backgroundColor: "#f44336",
        },
      },
    },
  },
};

<BorrowerDashboardElement
  authLeaseCallback={fetchPylonAuthLease}
  loanId="loan_12345"
  theme={ThemeConfig}
/>

The following image shows an example of what the global theme properties will target:

Level 2: Component Theme configuration

The Component level configuration will help you if you would like to get more specific about individual component styles. The Borrower Dashboard has a fairly repetitive UI so the components to configure with your own theme is somewhat minimal.

Available components

The following table details the Components available to customize:

Component	Description
`Typography.Title`	Main Title on a given page
`Typography.SubTitle`	Main Sub Title on a given page
`Typography.CardTitle`	Main Title inside of a Card
`Typography.CardSubTitle`	Main Sub Title inside of a Card
`Typography.LabelPrimary`	Primary text labels, button labels, form labels.
`Typography.LabelSecondary`	Secondary text labels usually seen under or next to Primary Labels.
`Typography.Link`	Textual Link (href)
`Typography.Body`	All other body text not included in its own Typography component listed above
`Typography.SubText`	All other body text not included in its own Typography component listed above
`Button.Primary`	Primary action button e.g. submit forms, next button, pre-approval button etc.
`Button.Neutral`	Secondary action button e.g. cancel forms, back button, close button etc.
`Button.Negative`	Cancel / Delete type action button.
`Button.ListItem`	Multiple buttons shown as a list e.g. task list in the borrower dashboard
`Form.TextInput`	Any type of text input used in a form, including `text`, `email`, `password`, `number` etc.
`Form.CheckBox`	A checkbox used in a form.
`Form.Radio`	A radio button used in a form.
`Form.Chip`	A Chip used in a form
`Form.Select`	A Select used in a form
`Form.Tags`	Free form text input component in a form that allows the user to create tags when we don’t have a predefined list for them to choose from. e.g. Race, Ethnicity etc.
`Form.InlineErrorMessage`	The error message that is displayed inline under a specific form input field that is invalid, e.g. TextInput, Select, Chip etc.
`Form.ErrorAlert`	A small box containing error text that displays above a form submit button if there’s an error.
`Container.Card`	Primary type of container. e.g. each main sections on the dashboard, the container on the review screens etc.
`Container.LoanProgressSimple`	Mobile view of Loan Progress bar indicating how far the user has progressed in the BorrowerDashboard, a global component seen at the top of each page.
`Container.LoanProgressDetailed`	Desktop view of Loan Progress bar indicating how far the user has progressed in the BorrowerDashboard, a global component seen at the top of each page.
`Container.Loader`	A visual loader that gives feedback during longer server requests, e.g. credit check, pre-approval check etc.
`Container.ApprovalStatus`	A Chip like UI that displays the current approval status of the loan, this is a different color depending on its state which you can define in the Global color scheme `colors.loanStatus`. You can use this component to set the general styles for the Chip.
`Communications.PreapprovalLetter`	The preapproval letter PDF that is provided to borrowers upon preapproval. Please note that this component cannot be directly customized using CSS. For more information, refer to the Customizing the Preapproval Letter section.

Customizing components

Our design system is built using Material UI Components. All of the components we offer a theming API for (with the exception of the PreapprovalLetter PDF) hook into the flexibility of Material UI allowing you to override any CSS with your own. To do this styling the parent may be all you need but at times you’ll need to inspect the elements console in the browser and find the relevant child .Mui* classes you need to hit.

In an effort to make this synonymous with native CSS, there are no predefined opinions or standards built around what you should or should not change. We leverage the CSS in JS approach which allows you to apply any type of valid CSS you would like to any component and we will apply it directly (This includes nesting the CSS Object to target child elements in your parent selector).

import { BorrowerDashboardElement } from "@pylonlending/react-elements";

const ThemeConfig = {
  Component: {
    Typography: {
      Title: {
        fontSize: "30px",
      },
      Body: {
        fontSize: "18px",
      },
    },
    Button: {
      Primary: {
        backgroundColor: "black",
      },
    },
    Form: {
      TextInput: {
        "& .MuiFilledInput-root": {
          border: `solid 1px black`,
          borderRadius: "16px",
          marginBottom: "0px",
          backgroundColor: "grey",
          "&:hover": {
            backgroundColor: "white",
          },
          "&.Mui-focused": {
            backgroundColor: "grey",
            borderColor: "green",
          },
          "&.Mui-error": {
            backgroundColor: "grey",
            borderColor: "red",
          },
          "&.Mui-disabled": {
            backgroundColor: "darkgrey",
          },
        },
      },
    },
    Container: {
      LoanProgressDetailed: {
        backgroundColor: "white",
        "> .Mui-active": {
          backgroundColor: "green",
        },
        "> .Mui-inactive": {
          backgroundColor: "grey",
        },
      },
    },
  },
};

<BorrowerDashboardElement
  authLeaseCallback={fetchPylonAuthLease}
  loanId="loan_12345"
  theme={ThemeConfig}
/>

The following images give a visual example of each component listed above:

To update nested elements within a defined component, any valid CSS selector approach will work, however you will likely have to access the live DOM and inspect the HTML in your browser to determine how to construct the correct CSS selector. This is a fairly standard approach in FE development and one for now we don’t have any additional guidance on to make it easier.

Customizing the Preapproval Letter

The preapproval letter’s customization options are somewhat limited due to its PDF format. However, you can customize some of its styles by configuring fields within the Communications.PreapprovalLetter component. The available customization options are outlined below:

Field	Description
`PreapprovalLetter.primaryColor`	The primary color to be displayed on the letter.
`PreapprovalLetter.normalFontUrl`	The URL for a custom font to be applied to the normal font weight within the preapproval letter. The provided URL should direct to a downloadable TTF file, such as: `http://example.com/normal-font.ttf`.
`PreapprovalLetter.boldFontUrl`	The URL for a custom font to be applied to the bold font weight within the preapproval letter. The provided URL should direct to a downloadable TTF file, such as: `http://example.com/bold-font.ttf`.

Level 3: Page Theme Configuration

When the Global and Component level theming fall short of meeting your specific needs, we offer the option of Page level theming. With Page level theming, you gain the ability to focus on components within particular pages and apply distinct themes as necessary. For instance, consider a hypothetical scenario where this approach could prove useful: A “Submit Button” on the pre-approval task of the Borrower Dashboard. By utilizing Page level theming, you can target the Primary Button component on the “pre-approval task” of the Borrower Dashboard and adjust its appearance by making it larger or maybe enhancing the text’s boldness. This functionality should cover any unique branding requirements that come up.

Creating a custom CSS selector

To achieve this customization, your first step involves creating a CSS selector to target specific components or groups of components on a given page. This selector process comprises three parts:

Page class: We attach a unique class to the <body> element of each page, this is used as your root CSS selector. To find this class you’ll need to navigate to the specific page you want to make a change on and copy the name of the class on the <body> element from the browser dev console. See the example below of a unique class on the <body> element:
Container class: Within the Borrower Dashboard each page is split into 3 possible “containers” (Title Container, Form Container and Action Container), so the next step is to locate the “container” in the page where your component lives, the name of the class of this container will be used as the direct child of your root selector you copied from the <body> element. See the image below detailing the 3 containers:
Component class: The last step is to target the component you want to theme differently. Each component listed in the Component level also has a class name that is defined in kebab-case. For example, Typography.Title will be <h1 class="typography-title"> and this is the same for each Component. This class name will be the next direct child in your CSS selector after the container class you found in step 2.

Component class names

Component	Class Name
`Typography.Title`	`typography-title`
`Typography.SubTitle`	`typography-sub-title`
`Typography.CardTitle`	`typography-card-title`
`Typography.CardSubTitle`	`typography-card-sub-title`
`Typography.LabelPrimary`	`typography-label-primary`
`Typography.LabelSecondary`	`typography-label-secondary`
`Typography.Link`	`typography-link`
`Typography.Body`	`typography-body`
`Typography.SubText`	`typography-sub-text`
`Button.Primary`	`button-primary`
`Button.Neutral`	`button-neutral`
`Button.Negative`	`button-negative`
`Button.ListItem`	`button-list-item`
`Form.TextInput`	`form-text-input`
`Form.CheckBox`	`form-checkbox`
`Form.Radio`	`form-radio`
`Form.Chip`	`form-chip`
`Form.Select`	`form-select`
`Form.Tags`	`form-tags`
`Form.InlineErrorMessage`	`form-inline-error-message`
`Form.ErrorAlert`	`form-error-alert`
`Container.Card`	`container-card`
`Container.LoanProgressBar`	`container-loan-progress-bar`
`Container.Loader`	`container-loader`
`Container.ApprovalStatus`	`container-approval-status`

Page-level theming example

Continuing with the hypothetical example of updating the submit button on the pre-approval task of the Borrower Dashboard, we need to gather up the following class names:

Page: <body class="borrower-dashboard-preapproval-page"> → borrower-dashboard-preapproval-page
Container: <div class="action-container"> → action-container
Component: <div class="button-primary"> → button-primary

It’s now possible to piece together the CSS selector and make the desired theming update to a component on this specific page:

import { BorrowerDashboardElement } from "@pylonlending/react-elements";

const ThemeConfig = {
  Component: {
    Button: {
      Primary: {
        Page: {
          ".borrower-dashboard-preapproval-page > .action-container > .button-primary": {
            padding: "30px 20px",
            ".button-label": {
              fontSize: "20px",
              fontWeight: "bold",
            },
          },
        },
      },
    },
  },
};

<BorrowerDashboardElement
  authLeaseCallback={fetchPylonAuthLease}
  loanId="loan_12345"
  theme={ThemeConfig}
/>

In an effort to offer more than one way to organize Page level theming, it’s also possible to put the Page level theming at the root of the theming configuration. You can put as many Page level theming updates as you would like here:

const ThemeConfig = {
  Global: { ... },
  Component: { ... },
  Page: {
    ".borrower-dashboard-preapproval-page > .action-container > .button-primary": {
      padding: "30px 20px",
      ".button-label": {
        fontSize: "20px",
        fontWeight: "bold",
      },
    },
    ".some-other-selector": {
      // ... more styles
    },
  },
};

If for some reason you have Page level theming defined at the root level as well as the Component level, the Component level will take precedence if they target the same component.Our selector approach is only a suggestion, there may be scenarios that it needs to be altered. It’s no problem to create your own selectors, the CSS passed in on the Page property is attached to the head of the page so as long as the selector works the CSS will be applied.

Complete theme example

The following is an example of a theme configuration using all 3 levels. As mentioned earlier, the theming config is purely optional at each level so this is just for reference.

import { BorrowerDashboardElement } from "@pylonlending/react-elements";

const ThemeConfig = {
  Global: {
    fonts: {
      fontFamily: "Inter",
      fontUrls: [
        "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700",
        "https://fonts.googleapis.com/css2?family=Montserrat:wght@600&display=swap",
        "https://fonts.googleapis.com/css2?family=Oswald:wght@200&display=swap",
      ],
    },
    colors: {
      core: {
        primary: "#1d8a38",
        neutral: "#d6c6a9",
        error: "#FF0000",
        warning: "#FF9033",
        success: "#4FD831",
      },
      text: {
        primary: "#000000",
        secondary: "#AAAAAA",
        disabled: "#EEEEEE",
        contrast: "#ffffff",
        error: "#FF0000",
        warning: "#FF9033",
        success: "#4FD831",
      },
      background: {
        application: "#F8F8F8",
        content: "#ffffff",
      },
      loanStatus: {
        approved: {
          backgroundColor: "#4caf50",
        },
        inReview: {
          backgroundColor: "#757575",
        },
        preApproved: {
          backgroundColor: "#9c27b0",
        },
        withdrawn: {
          backgroundColor: "#000000",
        },
        suspended: {
          backgroundColor: "#FFFFFF",
          color: "#000000",
        },
        declined: {
          backgroundColor: "#f44336",
        },
      },
    },
  },
  Component: {
    Typography: {
      Title: {
        fontSize: "30px",
        fontWeight: "600",
        letterSpacing: "-0.03em",
        fontFamily: "Montserrat",
      },
      Body: {
        fontFamily: "Oswald",
        fontWeight: "200",
      },
    },
    Button: {
      Primary: {
        borderRadius: 0,
      },
    },
    Form: {
      TextInput: {
        ".MuiFilledInput-root": {
          borderRadius: 0,
        },
      },
    },
    Container: {
      Card: {
        borderRadius: 0,
      },
    },
  },
  Page: {
    // Each page has a unique class on the body
    // This can be used to create css selectors on a specific page
    ".welcome .title-container + .MuiBox-root > .MuiBox-root img": {
      display: "none",
    },
  },
};

<BorrowerDashboardElement
  authLeaseCallback={fetchPylonAuthLease}
  loanId="loan_12345"
  theme={ThemeConfig}
/>

Best practices

Start with Global - The global theme often covers most of your needs
Use Component level for consistency - Apply component-level theming when you want consistent styling across all instances
Use Page level sparingly - Reserve page-level theming for unique cases where you need page-specific customization
Match your brand - Use your brand colors and fonts throughout
Test thoroughly - Ensure all UI elements are readable with your color choices
Maintain contrast - Follow WCAG guidelines for text contrast

Next steps

Theme reference - Complete theme documentation
Polling for updates - Monitor loan status changes
Loan Application Element - For new applications

GET STARTED

EXAMPLES

ELEMENTS

CORE ENTITIES

Theming approach

Level 1: Global Theme configuration

Global theme properties

Complete global theme example

Level 2: Component Theme configuration

Available components

Customizing components

Customizing the Preapproval Letter

Level 3: Page Theme Configuration

Creating a custom CSS selector

Component class names

Page-level theming example

Complete theme example

Best practices

Next steps

GET STARTED

EXAMPLES

ELEMENTS

CORE ENTITIES

​Theming approach

​Level 1: Global Theme configuration

​Global theme properties

​Complete global theme example

​Level 2: Component Theme configuration

​Available components

​Customizing components

​Customizing the Preapproval Letter

​Level 3: Page Theme Configuration

​Creating a custom CSS selector

​Component class names

​Page-level theming example

​Complete theme example

​Best practices

​Next steps

Theming approach

Level 1: Global Theme configuration

Global theme properties

Complete global theme example

Level 2: Component Theme configuration

Available components

Customizing components

Customizing the Preapproval Letter

Level 3: Page Theme Configuration

Creating a custom CSS selector

Component class names

Page-level theming example

Complete theme example

Best practices

Next steps