Documentation Index
Fetch the complete documentation index at: https://docs.myperch.io/llms.txt
Use this file to discover all available pages before exploring further.
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>
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.
