HubSpot Embedded Forms with Dynamic UI Logic: A Real-World Use Case

In the complex world of HubSpot CMS development, there are everyday tasks… and then there are moments that demand inventive problem-solving, cross-language fluency, and real-time validation logic across client-side UI and external APIs. This article dives into one such real-world use case where I transformed a static HubSpot form into a dynamic, validated, responsive user experience.

The Challenge

I was tasked with building an embedded HubSpot form that adapts based on user country — specifically US and Canada — displaying respective state and postal code fields, validating them via external APIs, and handling UI changes on the fly. The default HubSpot form functionality wasn’t enough for this level of interaction.

Some of the core requirements were:

• Conditionally display state and postal code fields only for users from the US or CA.

• Validate postal codes using external APIs like Zippopotam.us.

• Auto-suggest states as users typed.

• Ensure compatibility within HubSpot’s CMS modules without breaking server-side rendering or HubL scope.

The Strategy

Instead of relying on HubSpot’s default form field handling, I wrapped the embedded form within a custom module, injecting JavaScript that:

• Hooked into onCountryChange() logic.

• Dynamically mounted or unmounted fields via the DOM.

• Pulled validation responses via fetch() with debounce.

• Styled field visibility and errors using HubSpot’s recommended hs-error-msg patterns.

The Solution Breakdown

1. Country Detection

   const countryField = document.querySelector('[name="country"]');
   countryField.addEventListener('change', handleCountryChange);
   function handleCountryChange() {
    const val = countryField.value;
    toggleUSCAFields(val);
   }
   

2. Field Toggling

   function toggleUSCAFields(country) {
    const stateField = document.getElementById('state-field');
    const postalField = document.getElementById('postal-field');
    const shouldShow = ['United States', 'Canada'].includes(country);
    stateField.style.display = shouldShow ? 'block' : 'none';
    postalField.style.display = shouldShow ? 'block' : 'none';
   }
   

3. Postal Code API Validation (Zippopotam)

   const postalInput = document.querySelector('#postal-code');
   postalInput.addEventListener('input', debounce(validatePostal, 500));
   function validatePostal() {
    const postal = postalInput.value;
    const country = countryField.value === 'Canada' ? 'CA' : 'US';
    fetch(`https://api.zippopotam.us/${country}/${postal}`)
    .then(res => {
    if (!res.ok) throw new Error('Invalid postal');
    return res.json();
    })
    .then(data => showSuccess())
    .catch(() => showError());
   }
   

4. Auto Suggestion for State Input (for free-typed fields)
   I used a local JSON of US/CA states mapped by code and label, and added dynamic suggestions with keyboard navigation — completely inside the form.

Testing & Edge Handling

I accounted for:

• Mobile vs desktop behavior.

• Browser autofill conflicts.

• HubSpot's internal field validation layer (hs-validation-error).

• Default values from pre-filled form states.

The Outcome

This implementation not only enhanced the UX but also prevented invalid submissions and helped sync accurate user location data directly into HubSpot CRM. It performed flawlessly within a modular CMS layout and even supported multilingual variants without major refactor.

Takeaways for HubSpot CMS Developers

• Don’t limit yourself to HubL and form builder UI. When needed, step beyond and inject logic the smart way.

• Use external validation only if latency can be mitigated — debounce and caching are key.

• Always test for field rehydration if the form is reused in a multi-step process or gets re-rendered post submission.

Tech Stack:

• HubL

• Vanilla JS (no jQuery)

• JSON APIs (Zippopotam)

• Inline module-level styling

• HubSpot embedded forms

If you’re developing advanced HubSpot CMS modules and need interactive, intelligent forms — this approach can unlock flexibility that blends natively with HubSpot's ecosystem.

Want to see a live demo or use this logic in your own project? Reach out or fork the logic into your own custom module today.