fix(ui): inert attribute for React 18/19 compatibility (#8820)

Author: alexcarpenter

.changeset/fix-inert-react-19-compat.md

@@ -0,0 +1,5 @@
+---
+"@clerk/ui": patch
+---
+
+Add support for the `inert` attribute usage under React 19. Inert content is now correctly non-interactive on both React 18 and 19.

.changeset/shared-inert-props-helper.md

@@ -0,0 +1,5 @@
+---
+"@clerk/shared": patch
+---
+
+Add an `inertProps` helper (`@clerk/shared/inert`) that resolves the correct `inert` attribute value for the consumer's React major (React 19 dropped the `inert` attribute for falsy string values).

packages/headless/package.json

@@ -58,6 +58,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@clerk/shared": "workspace:^",
     "@floating-ui/react": "catalog:repo"
   },
   "devDependencies": {

packages/headless/src/primitives/tabs/tabs-panel.tsx

@@ -1,22 +1,13 @@
 'use client';
 
+import { inertProps } from '@clerk/shared/inert';
 import { useMergeRefs } from '@floating-ui/react';
-import React, { useRef, version } from 'react';
+import React, { useRef } from 'react';
 
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
 import { useTabsContext } from './tabs-context';
 
-const major = parseInt(version, 10);
-const isModernReact = major >= 19 || major === 0;
-
-export function inertProps(active: boolean): Record<string, unknown> {
-  if (!active) {
-    return {};
-  }
-  return { inert: isModernReact ? true : '' };
-}
-
 export interface TabsPanelProps extends ComponentProps<'div'> {
   value: string;
   /** When true, removes `hidden` so the panel stays in layout flow. */

packages/headless/src/primitives/tabs/tabs.test.tsx

@@ -506,6 +506,30 @@ describe('Tabs', () => {
       const panels = document.querySelectorAll('[data-cl-slot="tabs-panel"][data-cl-hidden]');
       expect(panels).toHaveLength(2);
     });
+
+    it('non-selected panels have inert attribute, selected panel does not', () => {
+      renderTabs();
+      const panels = document.querySelectorAll('[data-cl-slot="tabs-panel"]');
+      const inert = Array.from(panels).filter(p => p.hasAttribute('inert'));
+      const notInert = Array.from(panels).filter(p => !p.hasAttribute('inert'));
+      // Presence check only — `inertProps` emits the value each React major reflects
+      // (string '' on 18, boolean true on 19), both of which serialize to inert="".
+      expect(inert).toHaveLength(2);
+      expect(notInert).toHaveLength(1);
+    });
+
+    it('inert updates when selection changes', async () => {
+      const user = userEvent.setup();
+      renderTabs();
+
+      await user.click(screen.getByText('Settings'));
+
+      const panels = document.querySelectorAll('[data-cl-slot="tabs-panel"]');
+      const [account, settings, billing] = Array.from(panels);
+      expect(account).toHaveAttribute('inert');
+      expect(settings).not.toHaveAttribute('inert');
+      expect(billing).toHaveAttribute('inert');
+    });
   });
 
   describe('roving tabindex', () => {

packages/headless/vite.config.ts

@@ -31,7 +31,7 @@ export default defineConfig({
       formats: ['es'],
     },
     rollupOptions: {
-      external: ['react', 'react-dom', 'react/jsx-runtime', '@floating-ui/react'],
+      external: ['react', 'react-dom', 'react/jsx-runtime', '@floating-ui/react', /^@clerk\/shared(\/.*)?$/],
       // Preserve module-level directives such as `'use client'`. Rollup otherwise
       // strips them when bundling (emitting a warning), which would drop the
       // client boundary for React Server Component consumers of the primitives.

packages/shared/src/inert.ts

@@ -0,0 +1,29 @@
+import { version } from 'react';
+
+// React 19 turned `inert` into a real boolean attribute, so a falsy value like `''`
+// is no longer reflected to the DOM. React 18 doesn't know `inert` and only serializes
+// a (non-undefined) string value. Resolve the consumer's React major once at module
+// load — `react` is a peer dependency, so this reads the same copy the component renders
+// with — and emit the value that major actually reflects.
+//
+// `parseInt` handles prerelease strings like `19.0.0-rc-...`. Experimental builds report
+// `0.0.0-experimental-...` (major 0) but ship React 19 behavior, so treat 0 as modern too.
+const major = parseInt(version, 10);
+const isModernReact = major >= 19 || major === 0;
+
+/**
+ * Returns props to spread onto an element to apply (or omit) the `inert` attribute
+ * correctly across React 18 and 19.
+ *
+ * Typed as `Record<string, unknown>` on purpose: React 18's types reject `inert` and
+ * React 19's type it as `boolean`, so an untyped spread sidesteps both type-level shapes
+ * regardless of which `@types/react` a consumer compiles against.
+ *
+ * @param active - Whether the element should be inert.
+ */
+export function inertProps(active: boolean): Record<string, unknown> {
+  if (!active) {
+    return {};
+  }
+  return { inert: isModernReact ? true : '' };
+}

packages/ui/src/components/PricingTable/PricingTableMatrix.tsx

@@ -1,3 +1,4 @@
+import { inertProps } from '@clerk/shared/inert';
 import type { BillingPlanResource, BillingSubscriptionPlanPeriod } from '@clerk/shared/types';
 import * as React from 'react';
 
@@ -265,8 +266,7 @@ export function PricingTableMatrix({
                                   }),
                                   feePeriodNoticeAnimation,
                                 ]}
-                                // @ts-ignore - Needed until React 19 support
-                                inert={planPeriod !== 'annual' ? 'true' : undefined}
+                                {...inertProps(planPeriod !== 'annual')}
                               >
                                 <Box
                                   elementDescriptor={descriptors.pricingTableMatrixFeePeriodNoticeInner}

packages/ui/src/components/devPrompts/KeylessPrompt/index.tsx

@@ -1,3 +1,4 @@
+import { inertProps } from '@clerk/shared/inert';
 import { useUser } from '@clerk/shared/react';
 // eslint-disable-next-line no-restricted-imports
 import { css } from '@emotion/react';
@@ -506,7 +507,7 @@ function KeylessPromptInternal(props: KeylessPromptProps) {
       </button>
       <div
         id={id}
-        {...(!isOpen && { inert: '' as any })}
+        {...inertProps(!isOpen)}
         css={css`
           ${CSS_RESET};
           display: grid;

packages/ui/src/elements/Collapsible.tsx

@@ -1,3 +1,4 @@
+import { inertProps } from '@clerk/shared/inert';
 import { type PropsWithChildren, useEffect, useState } from 'react';
 
 import { Box, descriptors, useAppearance } from '../customizables';
@@ -75,8 +76,7 @@ export function Collapsible({ open, children, sx }: CollapsibleProps): JSX.Eleme
         }),
         sx,
       ]}
-      // @ts-ignore - inert not yet in React types
-      inert={!open ? '' : undefined}
+      {...inertProps(!open)}
     >
       <Box
         elementDescriptor={descriptors.collapsibleInner}