I’m working on creating an email template in HubSpot and need help with something specific. I want to allow users to change the background image directly from the template editor without having to mess with code. I’ve noticed this feature exists in some other templates I’ve looked at, but I can’t figure out how to implement it myself. I’ve been searching through the HubL documentation but haven’t found clear instructions on how to make background images editable from the frontend interface. Does anyone know the right approach or specific HubL tags I should be using for this? Any code examples or guidance would be really helpful since I’m a bit stuck on this one.
You’ll need to create a custom module with a background_image field. Set it to type: "image" so users can edit it through the template editor. Then add style="background-image: url('{{ module.background_image.src }}')" to your template. Make sure your fields.json file is set up correctly - if it’s not, the image picker won’t show up in the editor. I ran into this same issue recently and fixing the module setup solved it.
The thing most people miss is setting up the module correctly in your template structure. When I implemented this, just adding the image field wasn’t enough - you’ve got to register the module in your template’s meta.json file. After creating your custom module with the background_image field, reference it in your email template with {% module "your_module_name" %}. Here’s a gotcha I ran into: HubSpot’s email editor caches module definitions, so clear your browser cache or use incognito when testing changes. Also, email clients handle background images differently, so test across multiple platforms before you finalize anything.
You’re likely missing the field definition in your module structure. Create a custom module and add this to your fields.json file: “type”: “image” and “required”: false for your background image field. Then use {{ module.background_image.src }} in your HTML template’s CSS background-image property. The editor may not refresh after adding new fields, so try saving and refreshing the template editor. Additionally, include background-size: cover and background-position: center to ensure better display across email clients.
There’s actually another way - use the {% image %} tag with export_to_template_context=True. This lets you reference the image in CSS later. Wrap your content div with style="background-image: url('{{ widget_data.background_image.src }}')" and you’re good to go. Add no_wrapper=True if u want cleaner markup.