> ## 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.

# Customization

> Learn how to customize Perch's embeddable tools with pre-filled data and styling options

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

```html theme={null}
<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

```html theme={null}
<!-- 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

| 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

```html theme={null}
<!-- 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

```html theme={null}
<!-- 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

```php theme={null}
<!-- 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.