Building pop-ups with custom HTML gives your team complete creative freedom to adapt your pop-ups to your exact brand guidelines and design requirements. If you prefer a visual, code-free alternative, you can design pop-ups using the visual builder in "Website Experience" instead.
When using custom HTML, following the interaction rules in this guide ensures that contact details map correctly to your workspace and that your pop-up performance statistics (including shown, clicked, and submitted interactions) are accurately recorded.
Basic input fields in pop-ups collect essential contact details, such as names, email addresses, or phone numbers. To ensure proper data mapping in Positive User, the name attribute of each input field must match its corresponding contact attribute name. Positive User supports standard attributes like “First name”, “Last name”, and “Phone number”, as well as custom attributes defined for specific business needs like marketing consents or e-commerce statistics. Specifying the field type (such as text, email, or number) and adding descriptive placeholder text guides contacts and ensures accurate data collection.
Required input fields ensure that contacts provide essential information before submitting a pop-up form. Include the required attribute in the input element to enable browser-level validation, prompting contacts to complete the field before submission. Pairing this with clear placeholder text or labels enhances usability.
Example: Required input
<input type="email" name="email" placeholder="Enter your email address" required>In this example:
type="email" ensures the input is validated as an email address.
name="email" maps the field to the contact’s email attribute in your Positive User workspace.
“required” ensures the field must be filled out before the form is submitted.
placeholder="Enter your email address" guides the contact.
Optional input fields complement required fields by allowing contacts to provide additional, non-mandatory data. To configure an optional field, include the name attribute for data mapping, but omit the required attribute.
Example: Configuring required and optional input fields
<input type="email" name="email" placeholder="Enter your email address" required>
<input type="text" name="first_name" placeholder="Enter your first name (optional)">In this example:
The “email” input is mandatory because it includes the required attribute.
The “first name” input is optional because the required attribute is omitted.
name="email" and name="first_name" ensure data maps to the correct attributes in Positive User.
A single checkbox is often used for binary choices, such as granting consent. Use <input type="checkbox"> and map the name attribute to the contact attribute in Positive User. When the box is checked, the value “true” is sent to Positive User. Wrapping the input in a <label> tag makes the text clickable to improve usability.
Example: Newsletter consent checkbox
<label>
<input type="checkbox" name="newsletter_consent">
I agree to receive the newsletter.
</label>In this example:
type="checkbox" creates a single checkbox.
name="newsletter_consent" maps the input to the “newsletter_consent” contact attribute.
The <label> makes the text clickable, improving usability.
Fixed-choice inputs allow contacts to select one or more predefined options from a list, which is ideal for collecting data on interests or communication preferences. Use multiple <input type="checkbox"> elements that share the same name attribute so all selected values map to that single contact attribute. Before adding them to your code, go to "Workspace Settings" → "Attributes" to create the custom attribute and define its options. The value attribute in your HTML must match the option name created in your workspace settings exactly.
Example: Configuring multiple choice inputs
<p>What topics are you interested in?</p>
<label>
<input type="checkbox" name="interests" value="product_updates">
Product Updates
</label>
<br>
<label>
<input type="checkbox" name="interests" value="monthly_newsletter">
Monthly Newsletter
</label>
<br>
<label>
<input type="checkbox" name="interests" value="special_offers">
Special Offers
</label>In this example:
type="checkbox" creates a selectable box for each option.
name="interests" is the same for all three inputs. This groups them together, ensuring that all selected values are saved to the “Interests” contact attribute.
value="..." specifies the unique text that will be saved for each option when it is checked. Important: the values provided in the value attribute (e.g., "product_updates") must be created as options for the corresponding custom attribute (e.g., “Interests”) within your workspace in prior. The value in the HTML must be an exact match for the option created in the app.
The <label> element improves usability by allowing contacts to click on the text to select the corresponding checkbox.
Configure submit buttons to process form submissions and collect important statistics about your pop-up performance.
Assign id="submitButton" to a button element inside your <form> tag. This specific ID is critical for triggering the redirecting and for collecting pop-up submission statistics in Positive User. It allows to validate inputs, map attributes, track submission statistics, and launch automated workflows.
Example: Form with input and submit button
<form>
<input type="email" name="email" placeholder="Enter your email address" required>
<button id="submitButton">Submit</button>
</form>Configure a submit button that redirects contacts to another page using an anchor <a> tag with id="submitButton". This specific ID is critical because it triggers the redirect while allowing Positive User to collect pop-up submission statistics. Use the href attribute in the <a> tag to specify the destination URL, making this setup ideal for directing contacts to thank-you pages or special offers after they click.
If your button includes complex nested elements (like styled text or images) ensure that only the <a> tag itself receives the click event. Apply pointer-events: none; via CSS to all elements inside the <a> tag to prevent inner elements from blocking the redirect or click tracking.
Example: Configuring a redirection button with nested elements
<a id="submitButton" href="https://example.com/thank-you">
<b>Click here to continue</b>
<img src="https://example.com/image.png" alt="Submit" onerror="this.style.display='none'">
</a>
<style>
#submitButton * {
/* This prevents any element inside the link from capturing the click event. */
pointer-events: none;
}
</style>Allow contacts to dismiss pop-ups cleanly without submitting data.
Add the data-dismiss="true" attribute to any valid HTML element, such as a <span> or <svg> close icon. Clicking this element signals Positive User to dismiss the pop-up and track the close action.
Example: Configuring a close button
<!-- Using a span element -->
<span data-dismiss="true" class="close-icon">×</span>By default, the overlay (the background area outside the pop-up content) may also close the pop-up. However, if a contact accidentally clicks inside the pop-up and their click lands on the overlay area within the iframe, it can unintentionally dismiss it. To prevent this, you can add a script that ensures only direct clicks on the overlay background will trigger a close action.
// Handle overlay clicks to close popup
document.querySelector('.ue-overlay').addEventListener('click', function (event) {
// Only close if clicking directly on the overlay background
if (event.target === this) {
// Find and click the close button to trigger User.com's close function
const closeBtn = document.querySelector('[data-dismiss="true"]');
if (closeBtn) {
closeBtn.click();
}
}
});The only valid method to close a pop-up in Positive User is by using the data-dismiss="true" attribute. You must never write custom JavaScript to hide the pop-up manually.
Because the pop-up is rendered inside an <iframe> that covers the entire page, using custom code to hide the pop-up's content will only make it invisible. The <iframe> itself will remain active, covering the underlying page and blocking all clicks. This is a critical mistake that can make your website unusable for visitors.