How to add a popup to a Contentful site

By Mert Özeren, Customer Success Specialist at Popupsmart · Updated September 24, 2026

To add a popup to a Contentful site, paste Popupsmart's embed code into the shared layout of the front end that renders your content, such as a Next.js root layout, and deploy once. Contentful serves content through its APIs and doesn't build your pages, so nothing changes in your space; Popupsmart runs every popup from its dashboard.

Add a popup to Contentful

Setup at a glance

Runs on: Contentful
Where the code goes: Front end's root layout → before </body>
Add-on: No app needed

Before you start

You need access to your front end's code, not to your Contentful space:

Access to the code of the front end that renders your Contentful content, and a way to deploy it. If a developer or an agency runs the site, send them Step 3 of this guide.
A free Popupsmart account. The free plan covers one website and one live popup, so you can finish this guide without paying.
The address your visitors use for the live site, which Popupsmart verifies after the install.

A Contentful site gets a Popupsmart popup from one embed code in the layout every page of its front end shares, added once. From then on, popups are built and changed in Popupsmart, and Contentful keeps serving your content as before.

Step 1: Create your Popupsmart account

Create a free Popupsmart account, or sign in to the one you have.

popupsmart register page

Step 2: Copy your embed code

In the dashboard, click Embed Code in the left-hand menu.

A window shows your code. Click Copy to clipboard. The code is one line, <script src="https://cdn.popupsmart.com/bundle.js" data-id="…" async defer></script>, and the data-id belongs to your account.

embed code window

Step 3: Paste the code into your front end's layout

Open the front-end project that renders your Contentful content and find the file that wraps every page. Paste the embed code just before the closing </body> tag. Where that is depends on the framework:

Next.js, App Router: the root layout, app/layout.tsx (or .js), inside <body>. You can also load the same URL with the Script component from next/script, keeping the data-id; the Next.js guide to scripts confirms that custom data attributes reach the final script tag.
Next.js, Pages Router: the custom document, pages/_document.tsx.
Other frameworks and plain HTML: the one base layout or HTML template that every page uses.

Commit the change and deploy the front end. Contentful needs no change and no rebuild of its own. After the deploy, open a few different pages, such as the home page, an article and a landing page, and check that each one loads the code.

Step 4: Add and verify your website

Back in Popupsmart, open the profile menu at the bottom left and click Websites.

Click New Website.

Enter the address of your live site, not the Contentful web app, and click Save.

adding a new website

If the site shows as Unverified, click Unverified, then Verify website, and go back to the dashboard and click Refresh. The guide to verifying your website covers the other cases.

Click New Campaign, choose your website and pick a template. Change its copy, colours and form fields to match your site.

Go to the builder's Publish step and click Publish.

publish your popupsmart campaign

A Successfully published window confirms that the campaign is live. Open your site in a private window and load a page; the popup appears when its trigger fires.

publish success

No. Contentful is a headless CMS that stores content and serves it to your front end, so it has no popup of its own. Contentful's Marketplace apps don't add one either: according to Contentful's App Framework docs, apps render inside the Contentful web app, in locations such as the entry editor, the entry sidebar and a page of their own, so an app changes where editors work, not the pages visitors see.

That leaves a modal your developers code into the front end, or one script. A coded modal is a fair choice for one fixed message: it adds no third party and follows your own design system. The cost comes later, because every new offer, copy change or targeting rule is a code change and a deploy. With Popupsmart, the script goes in once, and marketers build, target and publish popups from the dashboard, with the leads sent on to their email tool.

A Contentful site's popup is limited to some pages by a targeting rule in Popupsmart, not by the layout. Each campaign has its own targeting in the builder's Segment step, and URL targeting shows a popup only where the address contains or matches what you set, such as /blog. I'd keep popup rules out of the content model: a "show a popup" field on every entry has to be maintained entry by entry and rendered by a developer, while a URL rule in Popupsmart changes in one place.

Pages are half of the rule, and timing is the other half. In Popupsmart's 2026 benchmark, popups that wait before appearing convert 0.83% against 0.61% for popups shown the instant the page loads (median campaign), a lean rather than a proven gap, and exit intent shows no statistically reliable advantage. When a popup fires is worth deciding on purpose, so choose the trigger in the same step as the pages.

Start from the job the page has:

Newsletter signups on articles and resource pages: the email popup guide.
Webinar or event registrations on product pages: the webinar invitation popup recipe.
A last offer for visitors about to leave: the exit-intent popup recipe.
Feedback on docs and help pages: the survey popup recipe.

Contentful stores content, not contacts, so the leads a popup collects go from Popupsmart straight to the email or CRM tool you already use. You connect it in the campaign's Integration section. The HubSpot popup guide and the Mailchimp popup guide walk through a connection; the help center lists 19 destinations, and a webhook, Zapier or Make covers a tool that isn't one of them.

A Popupsmart popup doesn't hold up a Contentful site's pages: the embed code loads asynchronously (async defer), so the browser finishes building your page before it fetches Popupsmart. The script adds nothing to your Contentful API calls or to your front end's build: the visitor's browser fetches it after the page.

When a popup doesn't appear on a Contentful site, work down this list; the first three causes come from the headless setup.

The change isn't deployed. The layout edit only reaches visitors after the front end is built and deployed. Check that the deploy finished, then view the page source and search for cdn.popupsmart.com.
The code went into an entry, not the layout. Your front end decides how Contentful fields become HTML, and most renderers don't run a script stored in content. Move the code to the layout.
A page uses another layout. Some projects give the blog or landing pages their own layout. Add the code to each one, or to a component they all include.
You're testing on a preview URL. A preview deployment has a different address from the one you added in Popupsmart. Test on the live address, and make sure it matches exactly: www.example.com and example.com are different sites to a browser.
A Content Security Policy blocks the script. If your front end or your host sends a CSP header, add Popupsmart's script domain, cdn.popupsmart.com, to it.
The trigger hasn't fired yet. An exit-intent or scroll trigger waits for the visitor to leave or scroll; test in a private window and behave like a visitor.

💬

From the support queue: What I check first on a Contentful site is where the code was pasted. A script pasted into a text or rich text field is stored as content, and the front end decides how to render it, so it usually never runs. My advice is to put the code in the layout file once, deploy, and then view the page source and search for cdn.popupsmart.com before you look at the campaign.

Yes. Popupsmart's free plan is permanent, not a trial: one website, one live popup and 5,000 pageviews a month, with Popupsmart branding. It is enough to install the code and run your first popup on a Contentful site.

The Popupsmart pricing page compares it with the paid plans.

Only once. Someone who can edit and deploy your front end pastes one line into its layout. After that, the design, targeting and publishing happen in Popupsmart's visual editor, with no code and no deploy.

Does it work with any front-end framework?

Yes. Any front end that sends HTML pages to the browser can load the script, whether it is built with Next.js, Nuxt, Astro or plain HTML. Only the file that holds the shared layout changes.

Yes. Add email, name, phone or other form fields to any popup in the drag-and-drop editor. Submissions appear under Leads in Popupsmart and can be sent on to your email or CRM tool.

The drag-and-drop editor guide shows how to add form elements.

Yes. Popups are responsive, the builder has a desktop and a mobile preview, and device targeting can show a popup on mobile only or on desktop only.

The code side is one line in a layout and one deploy; the rest is building the popup. Among people who published a campaign in the 90 days to 16 September 2026, the median time from signup to the first published campaign was 32.5 minutes, and 287 of 332 published within a day, according to Popupsmart's own product data. That figure covers every platform, not Contentful sites alone.

How to add a popup to a Contentful site

Before you start