How to add a popup to a Hygraph site

Q: Can I show a different popup for each language of a Hygraph site?

Yes. If each locale has its own path, such as /de/, give each popup a URL rule for that path. Popupsmart's browser language targeting can also show a campaign only to browsers set to the languages you choose.

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

To add a popup to a Hygraph site, paste Popupsmart's embed code into the shared layout of the front end that queries Hygraph, such as a Next.js or Astro layout, and deploy once. Hygraph, called GraphCMS until 2022, serves content through a GraphQL API and doesn't render pages; Popupsmart runs every popup from its dashboard.

Add a popup to Hygraph

Setup at a glance

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

Before you start

You need access to the front end, not admin rights in Hygraph. Your schema and content stay as they are.

Access to the code of the front end that queries Hygraph, and a way to deploy it. If a developer or an agency runs the site, Step 2 is the part to send them.
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 Hygraph site gets a Popupsmart popup from one embed code in the layout its front end's pages share, added once. After that, you create and change popups in Popupsmart without a new deploy.

Step 1: Copy your embed code

getting the embed code

Click Copy to clipboard under the code. 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.

copying the embed code

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

Open the project that renders your Hygraph content and find the layout that wraps every page. Paste the embed code just before the closing </body> tag:

Next.js, App Router: inside <body> in the root layout, app/layout.tsx.
Astro: the base layout component in src/layouts/ that holds <body>.
Any other framework or plain HTML: the one base template that every page uses.

Commit the change and deploy the front end. Hygraph itself needs no change. When I set this up with a customer's developer, I ask for the code in the root layout rather than in a page component, because a page component loads it on that one page only.

Step 3: Add and verify your website

Back in Popupsmart, hover over the profile icon at the bottom left and click Websites.

Click New Website to add your site.

adding a new website

Enter your site's address and click Save.

enter your website and click save

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 the Popupsmart icon to open your campaigns, then click New Campaign. Name the campaign and choose your site's domain.

creating a new campaign

Pick a template, change its copy, colours and form fields to match your site, and click Save.

save publish ps

Go to the builder's Publish step and click Publish. Then open your site in a private window and load a page; the popup appears when its trigger fires.

published success ps

No. Hygraph is a headless CMS with no popup of its own: according to Hygraph's API reference, your front end fetches content through the GraphQL Content API, so the pages, and any popup on them, are the front end's job. Hygraph's Marketplace apps don't change that. Hygraph's App Framework docs describe apps that add custom fields, sidebar elements and pages to the Hygraph studio, so an app changes where your team edits content, not what visitors see.

That leaves a modal coded into your front end, or one script. A coded modal is a fair choice for a single fixed message, and it adds no third party. Every new offer, trigger or page rule after that is a code change and a deploy. Popupsmart puts that work in a dashboard: the script goes in once, and marketers build, target and publish popups themselves, with the leads sent to their email tool.

A Hygraph site's popup is limited to some pages by a targeting rule in Popupsmart, not by where the code sits. Each campaign has its own targeting in the builder's Segment step, and URL targeting limits a popup to addresses that contain or match what you set, such as /products. Pasting the code into a single page component instead makes the next change a developer's job.

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.

Match the popup to what the page is for:

Newsletter signups on articles and guides: the email popup guide.
A launch with a countdown and a signup: the countdown popup recipe.
A free shipping offer in exchange for an email on product pages: the free shipping popup recipe.
Callback requests on service and pricing pages: the callback popup recipe.

Hygraph holds content, not subscribers, so the leads go from Popupsmart to your email or CRM tool. You connect it in the campaign's Integration section. The Brevo popup guide and the MailerLite 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 Hygraph site's pages: the embed code loads asynchronously (async defer), so the browser finishes building your page before it fetches Popupsmart. It adds no GraphQL queries and nothing to your build: the visitor's browser loads the script after the page.

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

The layout change isn't live. Check that the deploy finished, then view the page source and search for cdn.popupsmart.com.
The code is in a content field. A script pasted into a rich text field in Hygraph is data; your front end decides how that data is rendered, and most renderers won't run it. Move the code to the layout.
A route has its own layout. Some projects give the blog or landing pages a separate layout. Add the code to each one.
The website isn't verified, or the address doesn't match. Test on the live address you added in Popupsmart, not a preview deployment, and remember that www.example.com and example.com are different sites to a browser.
A Content Security Policy blocks the script. If your front end or 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 Hygraph site is one page from each kind of route, not just the home page. Some projects give the blog or landing pages their own layout, and a layout without the code shows no popup while the rest of the site works. My advice is to open the home page, a blog post and a product page after the deploy, view each page's source and search for cdn.popupsmart.com.

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 site built with Hygraph.

The Popupsmart pricing page compares it with the paid plans.

Not for the popups. The one code step is pasting a single line into your front end's layout, which whoever deploys the site can do once. The design, targeting and publishing happen in Popupsmart's visual editor.

Is Hygraph the same as GraphCMS?

Yes. GraphCMS renamed itself Hygraph on 12 July 2022, according to Hygraph's announcement, so a project started on GraphCMS is a Hygraph project today. The steps here apply to it unchanged, because the popup code goes into your front end, not into Hygraph.

No. The popup never queries Hygraph. It loads in the visitor's browser from Popupsmart's script, so your schema, your content API and its permissions stay as they are.

Yes. If each locale has its own path, such as /de/, give each popup a URL rule for that path. Popupsmart's browser language targeting can also show a campaign only to browsers set to the languages you choose.

The browser language targeting guide shows where to set it.

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 Hygraph sites alone.

How to add a popup to a Hygraph site

Before you start