Customization

Perch’s embeddable tools can be customized to pre-fill certain pieces of information and modify their appearance, which can significantly improve their usability and integration with your website.

Overview

Embeds support two types of customization: pre-filling data to reduce user friction, and styling to match your brand. For example, if you run a property listing website you can pre-fill the property price so the mortgage calculator loads with the right value already set — no manual input required.

Pre-filling data

Use our predefined data attributes directly in the embed div to pass values in. Set them using your CMS or templating language.

Static values

<div class="perch-widget" 
     widget-id="uMsnqDSA" 
     widget-property-value="YOUR-VARIABLE" 
     widget-down-payment="YOUR-VARIABLE">  
  <div class="perch-widget-loading-indicator">Loading...</div>  
</div>

Dynamic values

<!-- Example with property listing data -->
<div class="perch-widget" 
     widget-id="uMsnqDSA" 
     widget-property-value="{{ property.price }}" 
     widget-annual-property-taxes="{{ property.taxes }}"
     widget-monthly-maintenance-fee="{{ property.maintenance }}">  
  <div class="perch-widget-loading-indicator">Loading...</div>  
</div>

Perch supports both single and multi-widget embeds. Multi-widget embeds include a navigation bar to help users navigate between different calculators.

Variables are global

Data attributes are applied globally across all widgets in the embed, which means:

Set them once on the embed code
All widgets contained in the embed will receive the provided variables
User-inputted values (e.g. income, down payment amount) are cached
If the user loads the same calculator again or on another page, the embed will remember their values

Supported variables

Each widget has its own set of supported variables based on functionality. Here are the current supported global variables:

Financial data

Variable	Type	Description
`widget-property-value`	Number	Property purchase price or current value
`widget-property-type`	String	Type of property: `Detached`, `Condo/Apartment`, `Townhouse`, `Semi-Detached`, or `Other`
`widget-annual-property-taxes`	Number	Annual property tax amount
`widget-monthly-maintenance-fee`	Number	Monthly maintenance or HOA fees
`widget-down-payment`	Number	Down payment amount in dollars
`widget-down-payment-percent`	Number	Down payment as a percentage
`widget-annual-income`	Number	Annual household income
`widget-referral-code`	String	Partner referral code for lead attribution
`widget-advisor-profile-id`	String	Specific advisor profile ID for attribution

Styling options

Variable	Type	Description
`widget-primary-color`	String (hex)	Primary brand color (e.g., “#327766”)
`widget-secondary-color`	String (hex)	Secondary accent color
`widget-hide-titles`	Boolean	Whether to hide widget titles

Localization

Variable	Type	Description
`widget-locale`	String	Language/locale code (e.g., “en”, “fr”)

UTM tracking parameters

Variable	Type	Description
`widget-utm-id`	String	Unique identifier for the embed instance
`widget-utm-campaign`	String	Campaign name for tracking
`widget-utm-medium`	String	Marketing medium (defaults to “embed”)
`widget-utm-source`	String	Traffic source identifier

Examples

Property listing

<!-- Real estate listing page -->
<div class="perch-widget" 
     widget-id="mortgage-calculator"
     widget-property-value="850000"
     widget-annual-property-taxes="8500"
     widget-monthly-maintenance-fee="350"
     widget-primary-color="#327766"
     widget-referral-code="REALTY-PARTNER-001">
  <div class="perch-widget-loading-indicator">Loading calculator...</div>  
</div>

Custom branding

<!-- Customized appearance -->
<div class="perch-widget" 
     widget-id="pre-qualification-tool"
     widget-primary-color="#1a365d"
     widget-secondary-color="#2d3748"
     widget-hide-titles="true">
  <div class="perch-widget-loading-indicator">Loading...</div>  
</div>

CMS integration

<!-- Example with PHP/WordPress -->
<div class="perch-widget" 
     widget-id="payment-calculator"
     widget-property-value="<?php echo get_field('property_price'); ?>"
     widget-down-payment-percent="<?php echo get_field('suggested_down_payment'); ?>"
     widget-referral-code="<?php echo get_option('perch_referral_code'); ?>">
  <div class="perch-widget-loading-indicator">Loading...</div>  
</div>

Best practices

Pre-fill as many relevant values as possible to reduce friction
Ensure pre-filled values make sense in context — a property price should match the listing it appears alongside
Use your referral code to ensure leads are properly attributed
Match your brand colors and test on both light and dark backgrounds
Use widget-hide-titles if widget headings conflict with your page layout

Need help?

Contact your Perch representative for assistance with customization or implementation questions.

Welcome

Core API

Lending API

Embeds

Overview

Pre-filling data

Static values

Dynamic values

Multi-widget embeds

Variables are global

Supported variables

Financial data

Styling options

Localization

UTM tracking parameters

Examples

Property listing

Custom branding

CMS integration

Best practices

Need help?

​Overview

​Pre-filling data

​Static values

​Dynamic values

​Multi-widget embeds

​Variables are global

​Supported variables

​Financial data

​Styling options

​Localization

​UTM tracking parameters

​Examples

​Property listing

​Custom branding

​CMS integration

​Best practices

​Need help?

Overview

Pre-filling data

Static values

Dynamic values

Multi-widget embeds

Variables are global

Supported variables

Financial data

Styling options

Localization

UTM tracking parameters

Examples

Property listing

Custom branding

CMS integration

Best practices

Need help?