Geo-Targeting for Next.js and React
Works with App Router, Pages Router, and plain React
GeoSwap works with any React-based setup. No npm package to install, no build configuration to change. You add one script tag and geo-targeting just works.
One script tag — no npm package needed
Works with App Router, Pages Router, and plain React
Compatible with Vite, Create React App, and any bundler
Next.js App Router
If you are using Next.js 13+ with the App Router, add the GeoSwap script to your root layout using the Script component from next/script.
app/layout.tsxtsx
// app/layout.tsx
import Script from "next/script";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
{children}
<Script
src="https://cdn.geoswap.co/geoswap.js"
data-account="YOUR_ACCOUNT_ID"
strategy="afterInteractive"
/>
</body>
</html>
);
}Why afterInteractive?
The afterInteractive strategy loads the script after the page hydrates, which is the sweet spot for geo-targeting. It does not block your initial page render, but loads early enough to execute redirect rules before the visitor has time to read the page.
Next.js Pages Router
If you are using the Pages Router, add the GeoSwap script to _app.tsx. This ensures the script loads on every page of your application.
pages/_app.tsxtsx
// pages/_app.tsx
import Script from "next/script";
import type { AppProps } from "next/app";
export default function App({ Component, pageProps }: AppProps) {
return (
<>
<Component {...pageProps} />
<Script
src="https://cdn.geoswap.co/geoswap.js"
data-account="YOUR_ACCOUNT_ID"
strategy="afterInteractive"
/>
</>
);
}You can also add it to _document.tsx if you prefer, but _app.tsx with the Script component is the recommended approach because it gives Next.js control over loading strategy.
Plain React (Vite, CRA, etc.)
For React apps that do not use Next.js (Vite, Create React App, or any other setup), add the script directly to your index.html file.
index.htmlhtml
<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Your App</title>
<!-- GeoSwap — add before closing </head> -->
<script
src="https://cdn.geoswap.co/geoswap.js"
data-account="YOUR_ACCOUNT_ID"
defer
></script>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>The defer attribute ensures the script loads without blocking your app's rendering.
Server-Side Rendering Note
GeoSwap runs client-side
The GeoSwap script runs in the browser after page load. This means geo redirects and content personalization happen on the client side. For most use cases — redirects, popups, bars, content swaps — this is exactly what you want.
Need server-side geo-targeting?
If you need to serve entirely different HTML from the server based on visitor location (e.g., for SEO or performance reasons), consider using our Geo API in your Next.js middleware or server components. The API returns location data that you can use to make server-side decisions.
Content Personalization in React
GeoSwap's content personalization works by finding elements in the DOM using CSS selectors and swapping their content. In React, the easiest way to target elements is with data-geoswap attributes.
components/hero-banner.tsxtsx
// Your React component
export function HeroBanner() {
return (
<section>
<h1 data-geoswap="hero-headline">
The #1 Geo-Targeting Platform
</h1>
<p data-geoswap="hero-subtext">
Show the right content to the right audience.
</p>
</section>
);
}Then in the GeoSwap dashboard, create a Geo Content rule with the selector [data-geoswap="hero-headline"] and set the replacement text for each country.
Verify Your Installation
Start your development server and open your app in a browser.
Open Developer Tools (F12) and go to the Console tab. You should see [GeoSwap] Initialized in the output.
In the GeoSwap dashboard, go to Settings → Install and click Verify Installation. A green checkmark confirms you are set up correctly.
Best Practices
Use the next/script component with strategy="afterInteractive" in Next.js. Don't add a raw <script> tag to your JSX — Next.js won't manage it properly.
Add data-geoswap attributes to elements you want to personalize. This is more reliable than targeting class names, which can change during CSS refactoring.
Don't use strategy="beforeInteractive" unless you have a specific reason. It forces the script to load before hydration, which can slow down your initial page load.
If you see a brief flash of default content before personalized content appears, add the anti-flicker CSS from the installation guide.
For single-page apps with client-side routing, GeoSwap automatically re-evaluates rules on route changes. No extra configuration needed.
Next up
Create your first geo redirect or content personalization rule.