> ## Documentation Index > Fetch the complete documentation index at: https://docs.pylon.mortgage/llms.txt > Use this file to discover all available pages before exploring further. # Theming > Customize the appearance of the Loan Application Element to match your brand The Loan Application 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 Loan Application (the embedded application) and your application (the embedding application). You can customize the theme of the Loan Application by providing a `theme` prop on the Loan Application Element: | Prop | Type | Description | | ------- | ------- | ------------------------------------------------------------------------------------------------------------ | | `theme` | `Theme` | Theme configuration object. See the [Theme reference](/elements/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. ```tsx theme={null} import { LoanApplicationComponent } from "@pylonlending/react-elements"; const ThemeConfig = { Global: { colors: { core: { primary: "blue", }, }, }, Components: { Container: { Card: { background: "#FFFFFF", // We can define the styles for a card on a specific page here Page: { ".loan-application-subject-property-page .form-container .card": { background: "#EEEEEE", }, }, }, }, }, Page: { // We can also define styles for a card on a specific page here. ".loan-application-address-page .form-container .card": { background: "#AAAAAA", }, }, }; ``` 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 Loan Application. ## 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 loan application 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 loan application. | `"#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 ```tsx theme={null} import { LoanApplicationComponent } 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", }, }, }, }, }; ``` The following image shows an example of what the global theme properties will target: Loan Application Global Theme Example ## 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 Loan Application 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](#customizing-the-preapproval-letter) section. | ### Customizing components Our design system is built using [Material UI](https://mui.com/material-ui/getting-started/) 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). ```tsx theme={null} import { LoanApplicationComponent } from "@pylonlending/react-elements"; const ThemeConfig = { Components: { Typography: { Title: { fontSize: "30px", }, Body: { fontSize: "18px", }, }, Button: { Primary: { backgroundColor: "black", }, }, Form: { TextInput: { border: "1px solid green", backgroundColor: "white", padding: "5px", "& .focused": { border: "1px solid black", }, }, }, Container: { LoanProgressDetailed: { backgroundColor: "white", "> .Mui-active": { backgroundColor: "green", }, "> .Mui-inactive": { backgroundColor: "grey", }, }, }, }, }; ``` The following images give a visual example of each component listed above: Loan Application Components Example ### 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 final page of the Loan Application. By utilizing Page level theming, you can target the Primary Button component on the "completed page" of the Loan Application 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: 1. **Page class**: We attach a unique class to the `` 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 `` element from the browser dev console. See the example below of a unique class on the `` element: Loan Application Body Class 2. **Container class**: Within the Loan Application each page is split into 4 possible "containers" (Progress Container, 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 `` element. See the image below detailing the 4 containers: Loan Application Sections 3. **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 `

` 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.LoanProgressSimple` | `container-loan-progress-simple` | | `Container.LoanProgressDetailed` | `container-loan-progress-detailed` | | `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 final page of the loan application, we need to gather up the following class names: * Page: `` → `loan-application-completed-page` * Container: `
` → `action-container` * Component: `
` → `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: ```tsx theme={null} import { LoanApplicationComponent } from "@pylonlending/react-elements"; const ThemeConfig = { Components: { Button: { Primary: { Page: { ".loan-application-completed-page > .action-container > .button-primary": { padding: "30px 20px", ".button-label": { fontSize: "20px", fontWeight: "bold", }, }, }, }, }, }, }; ``` 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: ```tsx theme={null} const ThemeConfig = { Global: { ... }, Components: { ... }, Page: { ".loan-application-completed-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. ```tsx theme={null} import { LoanApplicationComponent } 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", }, }, }, }, Components: { Typography: { Title: { fontSize: "30px", fontWeight: "600", letterSpacing: "-0.03em", fontFamily: "Montserrat", }, SubTitle: { fontSize: "22px", }, CardTitle: { fontFamily: "Montserrat", letterSpacing: "-0.03em", }, Body: { fontFamily: "Oswald", fontWeight: "200", }, }, Button: { Primary: { borderRadius: 0, }, Neutral: { borderRadius: 0, }, }, Form: { TextInput: { ".MuiFilledInput-root": { borderRadius: 0, }, }, }, Container: { Card: { borderRadius: 0, }, LoanProgressDetailed: { // ... css rules }, }, }, 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", }, }, }; ``` ## Best practices 1. **Start with Global** - The global theme often covers most of your needs 2. **Use Component level for consistency** - Apply component-level theming when you want consistent styling across all instances 3. **Use Page level sparingly** - Reserve page-level theming for unique cases where you need page-specific customization 4. **Match your brand** - Use your brand colors and fonts throughout 5. **Test thoroughly** - Ensure all form elements and buttons are readable with your color choices 6. **Maintain contrast** - Follow WCAG guidelines for text contrast ## Next steps * [Theme reference](/elements/theme-reference) - Complete theme documentation * [Polling for updates](/elements/loan-application/polling) - Monitor loan status changes * [Borrower Dashboard Element](/elements/borrower-dashboard/introduction) - For managing completed applications