Skip to main content
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>

​
Multi-widget embeds

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

VariableTypeDescription
widget-property-valueNumberProperty purchase price or current value
widget-property-typeStringType of property: Detached, Condo/Apartment, Townhouse, Semi-Detached, or Other
widget-annual-property-taxesNumberAnnual property tax amount
widget-monthly-maintenance-feeNumberMonthly maintenance or HOA fees
widget-down-paymentNumberDown payment amount in dollars
widget-down-payment-percentNumberDown payment as a percentage
widget-annual-incomeNumberAnnual household income
widget-referral-codeStringPartner referral code for lead attribution
widget-advisor-profile-idStringSpecific advisor profile ID for attribution

​
Styling options

VariableTypeDescription
widget-primary-colorString (hex)Primary brand color (e.g., “#327766”)
widget-secondary-colorString (hex)Secondary accent color
widget-hide-titlesBooleanWhether to hide widget titles

​
Localization

VariableTypeDescription
widget-localeStringLanguage/locale code (e.g., “en”, “fr”)

​
UTM tracking parameters

VariableTypeDescription
widget-utm-idStringUnique identifier for the embed instance
widget-utm-campaignStringCampaign name for tracking
widget-utm-mediumStringMarketing medium (defaults to “embed”)
widget-utm-sourceStringTraffic 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.