next-language-selector

A lightweight, unstyled language selector / locale switcher for Next.js (App Router & Pages Router).
Manages the NEXT_LOCALE cookie and works with next-intl or any i18n solution.

Live demo →

• Installation
• Basic Usage
• Styling
• Custom UI
• Dropdown mode
• Setup with next-intl
• Without full reloads
• No flash on first paint
• Props
• setLocaleCookie utility
• SSR & hydration

Key Features

• Next.js Native: Built for the Next.js ecosystem (App Router & Pages Router).
• Zero Dependencies: No runtime deps — just React.
• Unstyled by default: Bring your own CSS, Tailwind, Shadcn, Radix — no style conflicts.
• SSR-rendered: Real markup on the server — no post-hydration pop-in, no layout shift.
• Cookie-based: Reads and writes NEXT_LOCALE automatically.
• Secure: Cookie injection-safe, SameSite=Lax out of the box.

Installation

pnpm add next-language-selector
# or
npm install next-language-selector

Basic Usage

Drop the component into your Footer or Navbar. It handles cookie sync and state out of the box.

import { LanguageSelector } from "next-language-selector";

const locales = [
  { name: "English", code: "en", flag: "🇺🇸" },
  { name: "Deutsch", code: "de", flag: "🇩🇪" },
];

export default function Footer() {
  return (
    <footer>
      <LanguageSelector
        locales={locales}
        defaultLocale="en"
      />
    </footer>
  );
}

Styling

The component is unstyled by default. Use className / itemClassName props or target the data-active attribute:

/* Plain CSS */
.lang-btn {
  background: none;
  border: none;
  cursor: pointer;
  opacity: 0.5;
}

.lang-btn[data-active="true"] {
  opacity: 1;
  font-weight: 600;
  border-bottom: 2px solid currentColor;
}

<LanguageSelector
  locales={locales}
  defaultLocale="en"
  className="flex gap-2"
  itemClassName="lang-btn"
/>

With Tailwind:

<LanguageSelector
  locales={locales}
  defaultLocale="en"
  className="flex items-center gap-3"
  itemClassName="text-sm text-gray-400 data-[active=true]:text-black data-[active=true]:font-semibold"
/>

Custom UI

Use the renderCustom prop to take full control over rendering while keeping the cookie logic.

<LanguageSelector
  locales={locales}
  defaultLocale="en"
  renderCustom={({ locales, currentLocale, onChange }) => (
    <div className="flex gap-4">
      {locales.map((lang) => (
        <button
          key={lang.code}
          onClick={() => onChange(lang.code)}
          className={currentLocale === lang.code ? "font-bold" : "opacity-50"}
        >
          {lang.flag} {lang.name}
        </button>
      ))}
    </div>
  )}
/>

Dropdown mode

<LanguageSelector
  locales={locales}
  defaultLocale="en"
  isDropdown
  className="border rounded px-2 py-1"
/>

Setup with next-intl

Update your middleware.ts to read the cookie set by this component:

import createMiddleware from "next-intl/middleware";
import { routing } from "./i18n/routing";

export default createMiddleware({
  ...routing,
  localeCookie: {
    name: "NEXT_LOCALE",
    path: "/",
    maxAge: 31536000,
  },
});

Prefix-based routing. If your URLs carry the locale (/de/about), the middleware only consults the cookie when a request has no prefix. Writing the cookie and reloading /de/about keeps you on /de/about. Navigate to the new prefix instead of reloading:

const router = useRouter();
const pathname = usePathname(); // e.g. "/de/about"

<LanguageSelector
  locales={locales}
  defaultLocale="en"
  reloadStrategy={(code) =>
    router.replace(pathname.replace(/^\/[a-z]{2}(?=\/|$)/, `/${code}`))
  }
/>

The default cookie-plus-reload flow suits localePrefix: "never" and any other setup where the locale is resolved from the cookie alone.

Without full reloads

By default the page does a full window.location.reload() after a locale change so the server picks up the new cookie. That throws away client state, scroll position and the router cache. Use reloadStrategy to hand control to the Next.js router instead:

"use client";

import { useRouter } from "next/navigation";
import { LanguageSelector } from "next-language-selector";

export function LocaleSwitch({ initialLocale }: { initialLocale?: string }) {
  const router = useRouter();
  return (
    <LanguageSelector
      locales={locales}
      defaultLocale="en"
      initialLocale={initialLocale}
      reloadStrategy={() => router.refresh()}
    />
  );
}

reloadStrategy accepts:

| Value | Behaviour | | :----------------------- | :-------------------------------------------------------------- | | "reload" (default) | Full window.location.reload() | | "none" | Nothing — the cookie is written, you re-render yourself | | (code: string) => void | Called with the selected code, e.g. router.refresh() |

The package never imports next/navigation itself, so it stays zero-dependency and works in the Pages Router too — pass the callback from your own client component.

onChange fires with the selected code before the cookie is written (and before the strategy runs) — handy for analytics.

Selecting the locale that is already active writes the cookie (in case it was missing) but skips both onChange and the reload strategy, so a stray click never throws the page away.

autoReload is deprecated as of 0.5.0. autoReload={false} still works and maps to reloadStrategy="none"; reloadStrategy wins when both are set.

No flash on first paint

The selector renders defaultLocale on the server and switches to the cookie value after mount. If the visitor's cookie differs, that first paint shows the wrong locale for a frame. Read the cookie server-side and pass it as initialLocale to render the right one immediately:

// app/layout.tsx — a Server Component
import { cookies } from "next/headers";
import { LocaleSwitch } from "./locale-switch";

export default async function Layout({ children }: { children: React.ReactNode }) {
  const initialLocale = (await cookies()).get("NEXT_LOCALE")?.value;

  return (
    <html>
      <body>
        <LocaleSwitch initialLocale={initialLocale} />
        {children}
      </body>
    </html>
  );
}

The cookie read on mount still wins afterwards, so the value stays correct if it changed in another tab.

Props

| Prop | Type | Default | Description | | :-------------- | :----------------------- | :------------- | :--------------------------------------------------- | | locales | LocaleConfig[] | Required | Array of { name, code, flag? } objects | | defaultLocale | string | Required | Fallback locale code | | initialLocale | string | defaultLocale| Locale rendered on the server and during hydration | | isDropdown | boolean | false | Render as <select> instead of buttons | | reloadStrategy| "reload" \| "none" \| (code) => void | "reload" | What happens after the cookie is written | | autoReload | boolean | true | Deprecated — use reloadStrategy | | onChange | (code: string) => void | - | Called on selection, before cookie write/reload | | cookieName | string | NEXT_LOCALE | Cookie name to store the selected locale | | cookieOptions | CookieOptions | see below | maxAge, path, domain, sameSite, secure | | aria-label | string | - | Accessible name for the <select> / button group | | className | string | - | CSS class for the wrapper <div> or <select> | | itemClassName | string | - | CSS class for each <button> or <option> | | renderCustom | Function | - | Render prop for fully custom UI |

LocaleConfig

interface LocaleConfig {
  name: string;   // Display name, e.g. "English"
  code: string;   // Locale code, e.g. "en"
  flag?: string;  // Optional emoji flag, e.g. "🇺🇸"
}

CookieOptions

interface CookieOptions {
  maxAge?: number;                      // seconds, default 31536000 (1 year)
  path?: string;                        // default "/"
  domain?: string;                      // e.g. ".example.com" to share across subdomains
  sameSite?: "Lax" | "Strict" | "None"; // default "Lax"
  secure?: boolean;                     // default false; forced on for sameSite "None"
}

<LanguageSelector
  locales={locales}
  defaultLocale="en"
  cookieOptions={{ domain: ".example.com", secure: true }}
/>

Validation

defaultLocale, initialLocale and any code passed to the renderCustom onChange must exist in locales. Unknown codes from onChange are ignored. In development a console.warn explains what went wrong; production builds strip the checks.

setLocaleCookie utility

The cookie writer is exported separately — useful if you want to switch the locale from your own code (a settings page, a keyboard shortcut, etc.) without rendering the component:

import { setLocaleCookie } from "next-language-selector";

// setLocaleCookie(locale, cookieName?, reloadStrategy?, cookieOptions?)
setLocaleCookie("de");                             // sets NEXT_LOCALE=de and reloads
setLocaleCookie("de", "MY_LOCALE", "none");        // custom cookie, no reload
setLocaleCookie("de", "NEXT_LOCALE", router.refresh); // hand off to the router
setLocaleCookie("de", "MY_LOCALE", false);         // deprecated boolean form, still works
setLocaleCookie("de", "NEXT_LOCALE", "none", { domain: ".example.com", secure: true });

The name and value are URI-encoded (cookie-injection safe). Without cookieOptions the cookie is written with max-age=31536000; path=/; SameSite=Lax. On the server it is a no-op.

SSR & hydration

The component renders real markup on the server, using initialLocale ?? defaultLocale. The first client render uses the same value, so hydration always matches; the cookie is read in an effect right after mount and updates the active locale if it differs.

Pass initialLocale to avoid that one-frame correction entirely. Malformed or unknown cookie values are ignored and the initial locale is kept.

Before 0.5.0 the component returned null until mount, which caused a layout shift and left the selector missing without JS. If you reserved space with CSS to work around that, you can drop it.

Buttons are rendered with type="button", so placing the selector inside a <form> won't trigger submits. The button wrapper has role="group" and each button carries aria-pressed; pass aria-label to give the group (or the <select>) an accessible name.

License

MIT