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