useid-polyfill 1.0.3 → 1.1.0

package/README.md

@@ -4,6 +4,8 @@ A React `useId` polyfill for React 16 and 17, with SSR support.
 
 React 18 introduced `useId()` for generating unique, stable IDs — critical for accessibility (ARIA attributes, label associations). This package detects React 18+ and delegates to the native `useId`. On React 16/17, it provides a fallback that avoids hydration mismatches.
 
+Need to support a third-party library that uses `useId` on React 16/17? See [Polyfilling Third-Party Libraries](#polyfilling-third-party-libraries).
+
 ## Installation
 
 ```bash
@@ -29,10 +31,15 @@ function FormField({ label }: { label: string }) {
 
 ## API
 
-### `useId(): string | undefined`
+### `useId()`
 
 Returns a unique, stable ID string. On React 18+, delegates to the native `React.useId()`.
 
+TypeScript return type is conditional on your installed React typings:
+
+- React 18+ typings: `string`
+- React 16/17 typings: `string | undefined`
+
 On React 16/17 during SSR, returns `undefined` on the initial server render and hydration pass, then resolves to a string ID after a layout effect. This avoids hydration mismatches.
 
 ## SSR Caveats
@@ -50,6 +57,73 @@ const id = useId();
 return <input id={id ?? undefined} aria-describedby={id ? `${id}-help` : undefined} />;
 ```
 
+## Polyfilling Third-Party Libraries
+
+If you use React 16 or 17 and install a third-party library (e.g., MUI, Radix UI) that internally calls `React.useId`, it will crash because `React.useId` does not exist before React 18.
+
+### Option 1: Auto-patching (recommended)
+
+Import `useid-polyfill/auto` **once** at the very top of your app entry point, **before any other imports**:
+
+```js
+// src/index.js — must be the first import
+import 'useid-polyfill/auto';
+
+import React from 'react';
+import ReactDOM from 'react-dom';
+import App from './App';
+```
+
+This patches `React.useId` globally so any library importing `useId` from `react` will get the polyfill. On React 18+, this is a no-op.
+
+> **SSR note:** On React 16/17, the patched `useId` returns `undefined` during server rendering and hydration (same as the direct polyfill — see [SSR Caveats](#ssr-caveats)). Most libraries handle this gracefully, but if a third-party component breaks during hydration, this is likely why.
+
+### Option 2: Bundler alias
+
+If runtime patching does not work in your environment, you can configure your bundler to shim React.
+
+Create a file `react-shim.js` at your project root:
+
+```js
+const React = require('react');
+if (!React.useId) {
+  const { useId } = require('useid-polyfill');
+  React.useId = useId;
+}
+module.exports = React;
+```
+
+**Webpack** — in `webpack.config.js`:
+
+```js
+module.exports = {
+  resolve: {
+    alias: {
+      react: require.resolve('./react-shim.js'),
+    },
+  },
+};
+```
+
+**Vite** — in `vite.config.ts`:
+
+```ts
+import { defineConfig } from 'vite';
+import path from 'path';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      react: path.resolve(__dirname, './react-shim.js'),
+    },
+  },
+});
+```
+
+### Option 3: patch-package
+
+As a last resort, you can use [patch-package](https://www.npmjs.com/package/patch-package) to modify the offending library's source to import from `useid-polyfill` instead of `react`.
+
 ## How It Works
 
 1. **React 18+ detection**: If `React.useId` exists, it is used directly

package/dist/auto.d.mts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/auto.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/auto.js

@@ -0,0 +1 @@
+"use strict";var l=Object.create;var u=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var I=Object.getPrototypeOf,g=Object.prototype.hasOwnProperty;var y=(e,t,o,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let s of m(t))!g.call(e,s)&&s!==o&&u(e,s,{get:()=>t[s],enumerable:!(r=p(t,s))||r.enumerable});return e};var d=(e,t,o)=>(o=e!=null?l(I(e)):{},y(t||!e||!e.__esModule?u(o,"default",{value:e,enumerable:!0}):o,e));var C=d(require("react"));var R=d(require("react")),n=require("react"),b={...R},h=0,w=Math.random().toString(36).slice(2,6),a=()=>`uid-${w}${h++}`,v=typeof window!="undefined"?n.useLayoutEffect:n.useEffect,i=!1;function x(){let[e,t]=(0,n.useState)(()=>i?a():void 0);return v(()=>{e===void 0&&t(a())},[]),(0,n.useEffect)(()=>{i||(i=!0)},[]),e}var f=b.useId||x;var c=C;if(typeof c.useId!="function")try{Object.defineProperty(c,"useId",{value:f,writable:!0,configurable:!0,enumerable:!0})}catch(e){typeof console!="undefined"&&console.warn&&console.warn("[useid-polyfill/auto] Could not patch React.useId. Your environment may not support runtime patching. Consider using a bundler alias instead. See: https://github.com/dermyhughes/useid-polyfill#option-2-bundler-alias")}

package/dist/auto.mjs

@@ -0,0 +1 @@
+import{a as e}from"./chunk-5VLUJQZZ.mjs";import*as t from"react";var o=t;if(typeof o.useId!="function")try{Object.defineProperty(o,"useId",{value:e,writable:!0,configurable:!0,enumerable:!0})}catch(n){typeof console!="undefined"&&console.warn&&console.warn("[useid-polyfill/auto] Could not patch React.useId. Your environment may not support runtime patching. Consider using a bundler alias instead. See: https://github.com/dermyhughes/useid-polyfill#option-2-bundler-alias")}

package/dist/chunk-5VLUJQZZ.mjs

@@ -0,0 +1 @@
+import*as o from"react";import{useState as f,useEffect as s,useLayoutEffect as i}from"react";var r={...o},u=0,c=Math.random().toString(36).slice(2,6),n=()=>`uid-${c}${u++}`,a=typeof window!="undefined"?i:s,e=!1;function p(){let[t,d]=f(()=>e?n():void 0);return a(()=>{t===void 0&&d(n())},[]),s(()=>{e||(e=!0)},[]),t}var g=r.useId||p;export{g as a};

package/dist/index.d.mts

@@ -1,3 +1,8 @@
-declare const useId: () => string | undefined;
+import * as React from 'react';
+
+type UseId = typeof React extends {
+    useId: (...args: never[]) => infer R;
+} ? () => R : () => string | undefined;
+declare const useId: UseId;
 
 export { useId };

package/dist/index.d.ts

@@ -1,3 +1,8 @@
-declare const useId: () => string | undefined;
+import * as React from 'react';
+
+type UseId = typeof React extends {
+    useId: (...args: never[]) => infer R;
+} ? () => R : () => string | undefined;
+declare const useId: UseId;
 
 export { useId };

package/dist/index.js

@@ -1 +1 @@
-"use strict";var a=Object.create;var d=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var I=Object.getPrototypeOf,g=Object.prototype.hasOwnProperty;var l=(e,t)=>{for(var n in t)d(e,n,{get:t[n],enumerable:!0})},r=(e,t,n,i)=>{if(t&&typeof t=="object"||typeof t=="function")for(let s of m(t))!g.call(e,s)&&s!==n&&d(e,s,{get:()=>t[s],enumerable:!(i=p(t,s))||i.enumerable});return e};var x=(e,t,n)=>(n=e!=null?a(I(e)):{},r(t||!e||!e.__esModule?d(n,"default",{value:e,enumerable:!0}):n,e)),y=e=>r(d({},"__esModule",{value:!0}),e);var $={};l($,{useId:()=>c});module.exports=y($);var E=x(require("react")),o=require("react"),R={...E},h=0,w=Math.random().toString(36).slice(2,6),u=()=>`uid-${w}${h++}`,L=typeof window!="undefined"?o.useLayoutEffect:o.useEffect,f=!1;function S(){let[e,t]=(0,o.useState)(()=>f?u():void 0);return L(()=>{e===void 0&&t(u())},[]),(0,o.useEffect)(()=>{f||(f=!0)},[]),e}var c=R.useId||S;0&&(module.exports={useId});
+"use strict";var a=Object.create;var o=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var I=Object.getOwnPropertyNames;var g=Object.getPrototypeOf,m=Object.prototype.hasOwnProperty;var l=(e,t)=>{for(var n in t)o(e,n,{get:t[n],enumerable:!0})},i=(e,t,n,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let d of I(t))!m.call(e,d)&&d!==n&&o(e,d,{get:()=>t[d],enumerable:!(r=p(t,d))||r.enumerable});return e};var y=(e,t,n)=>(n=e!=null?a(g(e)):{},i(t||!e||!e.__esModule?o(n,"default",{value:e,enumerable:!0}):n,e)),R=e=>i(o({},"__esModule",{value:!0}),e);var L={};l(L,{useId:()=>c});module.exports=R(L);var x=y(require("react")),s=require("react"),E={...x},U=0,h=Math.random().toString(36).slice(2,6),u=()=>`uid-${h}${U++}`,v=typeof window!="undefined"?s.useLayoutEffect:s.useEffect,f=!1;function w(){let[e,t]=(0,s.useState)(()=>f?u():void 0);return v(()=>{e===void 0&&t(u())},[]),(0,s.useEffect)(()=>{f||(f=!0)},[]),e}var c=E.useId||w;0&&(module.exports={useId});

package/dist/index.mjs

@@ -1 +1 @@
-import*as d from"react";import{useState as f,useEffect as o,useLayoutEffect as i}from"react";var r={...d},u=0,c=Math.random().toString(36).slice(2,6),n=()=>`uid-${c}${u++}`,a=typeof window!="undefined"?i:o,e=!1;function p(){let[t,s]=f(()=>e?n():void 0);return a(()=>{t===void 0&&s(n())},[]),o(()=>{e||(e=!0)},[]),t}var m=r.useId||p;export{m as useId};
+import{a as e}from"./chunk-5VLUJQZZ.mjs";export{e as useId};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "useid-polyfill",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "React useId polyfill for React 16/17 with SSR support",
   "author": {
     "name": "Dermot Hughes",
@@ -15,6 +15,18 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
+    },
+    "./auto": {
+      "types": "./dist/auto.d.ts",
+      "import": "./dist/auto.mjs",
+      "require": "./dist/auto.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "auto": [
+        "./dist/auto.d.ts"
+      ]
     }
   },
   "files": [