next-language-selector 0.3.1 → 0.4.0

package/README.md

@@ -9,6 +9,19 @@
 A lightweight, unstyled language selector for Next.js (App Router & Pages Router).  
 Manages the `NEXT_LOCALE` cookie and works with `next-intl` or any i18n solution.
 
+**[Live demo →](https://kirilinsky.github.io/next-language-selector/)**
+
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+- [Styling](#styling)
+- [Custom UI](#custom-ui)
+- [Dropdown mode](#dropdown-mode)
+- [Setup with next-intl](#setup-with-next-intl)
+- [Without full reloads](#without-full-reloads)
+- [Props](#props)
+- [`setLocaleCookie` utility](#setlocalecookie-utility)
+- [SSR & hydration](#ssr--hydration)
+
 ## Key Features
 
 - **Next.js Native**: Built for the Next.js ecosystem (App Router & Pages Router).
@@ -142,15 +155,41 @@ export default createMiddleware({
 });
 ```
 
+## Without full reloads
+
+By default the page reloads after a locale change so the server picks up the new cookie. For a smoother UX combine `autoReload={false}` with the `onChange` callback and the Next.js router:
+
+```tsx
+"use client";
+
+import { useRouter } from "next/navigation";
+import { LanguageSelector } from "next-language-selector";
+
+export function LocaleSwitch() {
+  const router = useRouter();
+  return (
+    <LanguageSelector
+      locales={locales}
+      defaultLocale="en"
+      autoReload={false}
+      onChange={() => router.refresh()}
+    />
+  );
+}
+```
+
+`onChange` fires with the selected code before the cookie is written (and before the reload when `autoReload` is on) — also handy for analytics.
+
 ## Props
 
-| Prop            | Type             | Default        | Description                                          |
-| :-------------- | :--------------- | :------------- | :--------------------------------------------------- |
-| `locales`       | `LocaleConfig[]` | **Required**   | Array of `{ name, code, flag? }` objects             |
-| `defaultLocale` | `string`         | **Required**   | Fallback locale code                                 |
-| `isDropdown`    | `boolean`        | `false`        | Render as `<select>` instead of buttons              |
-| `autoReload`    | `boolean`        | `true`         | Reload page after cookie change                      |
-| `cookieName`    | `string`         | `NEXT_LOCALE`  | Cookie name to store the selected locale             |
+| Prop            | Type                     | Default        | Description                                          |
+| :-------------- | :----------------------- | :------------- | :--------------------------------------------------- |
+| `locales`       | `LocaleConfig[]`         | **Required**   | Array of `{ name, code, flag? }` objects             |
+| `defaultLocale` | `string`                 | **Required**   | Fallback locale code                                 |
+| `isDropdown`    | `boolean`                | `false`        | Render as `<select>` instead of buttons              |
+| `autoReload`    | `boolean`                | `true`         | Reload page after cookie change                      |
+| `onChange`      | `(code: string) => void` | -              | Called on selection, before cookie write/reload      |
+| `cookieName`    | `string`                 | `NEXT_LOCALE`  | Cookie name to store the selected locale             |
 | `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                      |
@@ -165,6 +204,26 @@ interface LocaleConfig {
 }
 ```
 
+## `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:
+
+```ts
+import { setLocaleCookie } from "next-language-selector";
+
+// setLocaleCookie(locale, cookieName?, autoReload?)
+setLocaleCookie("de");                        // sets NEXT_LOCALE=de and reloads
+setLocaleCookie("de", "MY_LOCALE", false);    // custom cookie, no reload
+```
+
+The name and value are URI-encoded (cookie-injection safe), written with `max-age=31536000; path=/; SameSite=Lax`. On the server it is a no-op.
+
+## SSR & hydration
+
+The component renders `null` until it has mounted and read the cookie on the client, so server and client markup never mismatch. Expect the selector to appear only after hydration — reserve space with CSS if layout shift matters. Malformed or unknown cookie values are ignored and `defaultLocale` is used.
+
+Buttons are rendered with `type="button"`, so placing the selector inside a `<form>` won't trigger submits.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";var f=Object.defineProperty;var v=Object.getOwnPropertyDescriptor;var E=Object.getOwnPropertyNames;var x=Object.prototype.hasOwnProperty;var h=(t,o)=>{for(var a in o)f(t,a,{get:o[a],enumerable:!0})},P=(t,o,a,n)=>{if(o&&typeof o=="object"||typeof o=="function")for(let c of E(o))!x.call(t,c)&&c!==a&&f(t,c,{get:()=>o[c],enumerable:!(n=v(o,c))||n.enumerable});return t};var b=t=>P(f({},"__esModule",{value:!0}),t);var I={};h(I,{LanguageSelector:()=>w,setLocaleCookie:()=>i});module.exports=b(I);var s=require("react");var i=(t,o="NEXT_LOCALE",a=!0)=>{if(typeof document>"u")return;let n=encodeURIComponent(o),c=encodeURIComponent(t);document.cookie=`${n}=${c}; max-age=31536000; path=/; SameSite=Lax`,a&&window.location.reload()};var r=require("react/jsx-runtime");function N(t){let{locales:o,defaultLocale:a,cookieName:n="NEXT_LOCALE",isDropdown:c=!1,autoReload:g=!0,renderCustom:L,className:C,itemClassName:S}=t,[R,y]=(0,s.useState)(!1),[l,u]=(0,s.useState)(a);(0,s.useEffect)(()=>{let e=encodeURIComponent(n),k=document.cookie.split("; ").find(d=>d.startsWith(`${e}=`)),p=k?decodeURIComponent(k.split("=").slice(1).join("=")):null;p&&o.some(d=>d.code===p)?u(p):u(a),y(!0)},[n,a,o]);let m=(0,s.useCallback)(e=>{u(e),i(e,n,g)},[n,g]);return R?L?(0,r.jsx)(r.Fragment,{children:L({locales:o,currentLocale:l,onChange:m})}):c?(0,r.jsx)("select",{value:l,onChange:e=>m(e.target.value),className:C,children:o.map(e=>(0,r.jsxs)("option",{value:e.code,className:S,children:[e.flag," ",e.name]},e.code))}):(0,r.jsx)("div",{className:C,children:o.map(e=>(0,r.jsxs)("button",{onClick:()=>m(e.code),"data-active":l===e.code,"aria-pressed":l===e.code,className:S,children:[e.flag," ",e.name]},e.code))}):null}var w=N;0&&(module.exports={LanguageSelector,setLocaleCookie});
+"use strict";var p=Object.defineProperty;var R=Object.getOwnPropertyDescriptor;var h=Object.getOwnPropertyNames;var v=Object.prototype.hasOwnProperty;var x=(t,o)=>{for(var n in o)p(t,n,{get:o[n],enumerable:!0})},b=(t,o,n,a)=>{if(o&&typeof o=="object"||typeof o=="function")for(let r of h(o))!v.call(t,r)&&r!==n&&p(t,r,{get:()=>o[r],enumerable:!(a=R(o,r))||a.enumerable});return t};var P=t=>b(p({},"__esModule",{value:!0}),t);var w={};x(w,{LanguageSelector:()=>X,setLocaleCookie:()=>u});module.exports=P(w);var s=require("react");var S=(t="NEXT_LOCALE")=>{if(typeof document>"u")return null;let o=encodeURIComponent(t),n=document.cookie.split(";").map(a=>a.trim()).find(a=>a.startsWith(`${o}=`));if(!n)return null;try{return decodeURIComponent(n.slice(o.length+1))}catch{return null}},u=(t,o="NEXT_LOCALE",n=!0)=>{if(typeof document>"u")return;let a=encodeURIComponent(o),r=encodeURIComponent(t);document.cookie=`${a}=${r}; max-age=31536000; path=/; SameSite=Lax`,n&&window.location.reload()};var c=require("react/jsx-runtime");function k(t){let{locales:o,defaultLocale:n,cookieName:a="NEXT_LOCALE",isDropdown:r=!1,autoReload:d=!0,onChange:f,renderCustom:g,className:L,itemClassName:C}=t,[y,N]=(0,s.useState)(!1),[l,i]=(0,s.useState)(n);(0,s.useEffect)(()=>{let e=S(a);e&&o.some(E=>E.code===e)?i(e):i(n),N(!0)},[a,n,o]);let m=(0,s.useCallback)(e=>{i(e),f?.(e),u(e,a,d)},[a,d,f]);return y?g?(0,c.jsx)(c.Fragment,{children:g({locales:o,currentLocale:l,onChange:m})}):r?(0,c.jsx)("select",{value:l,onChange:e=>m(e.target.value),className:L,children:o.map(e=>(0,c.jsxs)("option",{value:e.code,className:C,children:[e.flag," ",e.name]},e.code))}):(0,c.jsx)("div",{className:L,children:o.map(e=>(0,c.jsxs)("button",{type:"button",onClick:()=>m(e.code),"data-active":l===e.code,"aria-pressed":l===e.code,className:C,children:[e.flag," ",e.name]},e.code))}):null}var X=k;0&&(module.exports={LanguageSelector,setLocaleCookie});

package/dist/index.d.mts

@@ -15,6 +15,12 @@ interface LanguageSelectorProps {
     className?: string;
     itemClassName?: string;
     autoReload?: boolean;
+    /**
+     * Called with the selected locale code after the internal state updates,
+     * before the cookie is written (and before the reload when autoReload is on).
+     * Use for analytics, router navigation or other side effects.
+     */
+    onChange?: (code: string) => void;
     renderCustom?: (props: {
         locales: LocaleConfig[];
         currentLocale: string;

package/dist/index.d.ts

@@ -15,6 +15,12 @@ interface LanguageSelectorProps {
     className?: string;
     itemClassName?: string;
     autoReload?: boolean;
+    /**
+     * Called with the selected locale code after the internal state updates,
+     * before the cookie is written (and before the reload when autoReload is on).
+     * Use for analytics, router navigation or other side effects.
+     */
+    onChange?: (code: string) => void;
     renderCustom?: (props: {
         locales: LocaleConfig[];
         currentLocale: string;

package/dist/index.mjs

@@ -1 +1 @@
-import{useCallback as v,useEffect as E,useState as S}from"react";var m=(c,o="NEXT_LOCALE",a=!0)=>{if(typeof document>"u")return;let t=encodeURIComponent(o),r=encodeURIComponent(c);document.cookie=`${t}=${r}; max-age=31536000; path=/; SameSite=Lax`,a&&window.location.reload()};import{Fragment as x,jsx as p,jsxs as k}from"react/jsx-runtime";function N(c){let{locales:o,defaultLocale:a,cookieName:t="NEXT_LOCALE",isDropdown:r=!1,autoReload:d=!0,renderCustom:f,className:g,itemClassName:L}=c,[R,y]=S(!1),[n,s]=S(a);E(()=>{let e=encodeURIComponent(t),C=document.cookie.split("; ").find(u=>u.startsWith(`${e}=`)),i=C?decodeURIComponent(C.split("=").slice(1).join("=")):null;i&&o.some(u=>u.code===i)?s(i):s(a),y(!0)},[t,a,o]);let l=v(e=>{s(e),m(e,t,d)},[t,d]);return R?f?p(x,{children:f({locales:o,currentLocale:n,onChange:l})}):r?p("select",{value:n,onChange:e=>l(e.target.value),className:g,children:o.map(e=>k("option",{value:e.code,className:L,children:[e.flag," ",e.name]},e.code))}):p("div",{className:g,children:o.map(e=>k("button",{onClick:()=>l(e.code),"data-active":n===e.code,"aria-pressed":n===e.code,className:L,children:[e.flag," ",e.name]},e.code))}):null}var A=N;export{A as LanguageSelector,m as setLocaleCookie};
+import{useCallback as R,useEffect as h,useState as C}from"react";var L=(a="NEXT_LOCALE")=>{if(typeof document>"u")return null;let o=encodeURIComponent(a),n=document.cookie.split(";").map(t=>t.trim()).find(t=>t.startsWith(`${o}=`));if(!n)return null;try{return decodeURIComponent(n.slice(o.length+1))}catch{return null}},u=(a,o="NEXT_LOCALE",n=!0)=>{if(typeof document>"u")return;let t=encodeURIComponent(o),c=encodeURIComponent(a);document.cookie=`${t}=${c}; max-age=31536000; path=/; SameSite=Lax`,n&&window.location.reload()};import{Fragment as v,jsx as i,jsxs as S}from"react/jsx-runtime";function k(a){let{locales:o,defaultLocale:n,cookieName:t="NEXT_LOCALE",isDropdown:c=!1,autoReload:m=!0,onChange:p,renderCustom:d,className:f,itemClassName:g}=a,[y,N]=C(!1),[r,s]=C(n);h(()=>{let e=L(t);e&&o.some(E=>E.code===e)?s(e):s(n),N(!0)},[t,n,o]);let l=R(e=>{s(e),p?.(e),u(e,t,m)},[t,m,p]);return y?d?i(v,{children:d({locales:o,currentLocale:r,onChange:l})}):c?i("select",{value:r,onChange:e=>l(e.target.value),className:f,children:o.map(e=>S("option",{value:e.code,className:g,children:[e.flag," ",e.name]},e.code))}):i("div",{className:f,children:o.map(e=>S("button",{type:"button",onClick:()=>l(e.code),"data-active":r===e.code,"aria-pressed":r===e.code,className:g,children:[e.flag," ",e.name]},e.code))}):null}var O=k;export{O as LanguageSelector,u as setLocaleCookie};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-language-selector",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Configurable language selector for Next.js",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -18,7 +18,8 @@
     "lint": "tsc --noEmit",
     "test": "vitest",
     "test:run": "vitest run",
-    "test:coverage": "npx vitest run --coverage"
+    "test:coverage": "npx vitest run --coverage",
+    "demo:build": "esbuild demo/main.tsx --bundle --minify --jsx=automatic --outfile=dist-demo/main.js && cp demo/index.html demo/og.png dist-demo/"
   },
   "files": [
     "dist"
@@ -39,7 +40,7 @@
   ],
   "author": "Kirilinsky (https://github.com/kirilinsky)",
   "license": "MIT",
-  "homepage": "https://github.com/kirilinsky/next-language-selector#readme",
+  "homepage": "https://kirilinsky.github.io/next-language-selector/",
   "bugs": {
     "url": "https://github.com/kirilinsky/next-language-selector/issues"
   },
@@ -52,13 +53,22 @@
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
     "@vitest/coverage-v8": "^4.1.2",
+    "esbuild": "^0.28.1",
     "happy-dom": "^20.8.9",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "tslib": "^2.8.1",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.2"
   },
   "sideEffects": false,
-  "packageManager": "pnpm@10.32.1"
-}
+  "packageManager": "pnpm@10.32.1",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}