refactor approach

Author: alexcarpenter

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

@@ -2,4 +2,4 @@
 "@clerk/ui": patch
 ---
 
-Fix `inert` attribute to work correctly in React 19. The previous value `''` (empty string) is falsy and not set by React 19's boolean attribute handler, leaving hidden panel and collapsible content interactive. Switches to `'true'` which is truthy in both React 18 and 19.
+Add support for the `inert` attribute usage under React 19. Inert content is now correctly non-interactive on both React 18 and 19.

packages/headless/src/global.d.ts

@@ -4,6 +4,7 @@ import { useMergeRefs } from '@floating-ui/react';
 import React, { useRef } from 'react';
 
 import { useTransition } from '../../hooks/use-transition';
+import { inertProps } from '../../utils/inert';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
 import { useTabsContext } from './tabs-context';
 
@@ -51,11 +52,9 @@ export const TabsPanel = React.forwardRef<HTMLDivElement, TabsPanelProps>(functi
     role: 'tabpanel' as const,
     'aria-labelledby': tabId,
     tabIndex: 0,
-    // `inert` must be a truthy string, not a boolean or empty string, to stay
-    // correct across React 18 and 19: React 18 drops a boolean `true` and React
-    // 19 treats `''` as falsy. `'true'` renders the (presence-based) attribute in
-    // both. Matches the existing pattern in packages/ui PricingTableMatrix.
-    inert: !isSelected ? 'true' : undefined,
+    // `inert` reflects differently across React majors; `inertProps` emits the value
+    // each one actually serializes (see packages/headless/src/utils/inert.ts).
+    ...inertProps(!isSelected),
     hidden: !isSelected && !shouldForceMount ? true : undefined,
     ref: combinedRef,
     ...(shouldForceMount

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

@@ -512,7 +512,8 @@ describe('Tabs', () => {
       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 — React 18 renders inert="true", React 19 normalises to 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);
     });

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

@@ -1,2 +1,3 @@
 export { cssVars } from './css-vars';
+export { inertProps } from './inert';
 export { type ComponentProps, mergeProps, type RenderProp, renderElement } from './render-element';

packages/headless/src/utils/index.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;
+
+/**
+ * Props to spread onto an element to apply (or omit) the `inert` attribute correctly
+ * across React 18 and 19.
+ *
+ * Returned 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/headless/src/utils/inert.ts

@@ -4,6 +4,7 @@ import * as React from 'react';
 import { Avatar } from '@/ui/elements/Avatar';
 import { SegmentedControl } from '@/ui/elements/SegmentedControl';
 import { colors } from '@/ui/utils/colors';
+import { inertProps } from '@/ui/utils/inert';
 
 import { usePlansContext } from '../../contexts';
 import {
@@ -265,7 +266,7 @@ export function PricingTableMatrix({
                                   }),
                                   feePeriodNoticeAnimation,
                                 ]}
-                                inert={planPeriod !== 'annual' ? 'true' : undefined}
+                                {...inertProps(planPeriod !== 'annual')}
                               >
                                 <Box
                                   elementDescriptor={descriptors.pricingTableMatrixFeePeriodNoticeInner}

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

@@ -4,6 +4,7 @@ import { css } from '@emotion/react';
 import { type ReactNode, useId, useMemo, useState } from 'react';
 
 import { InternalThemeProvider } from '../../../styledSystem';
+import { inertProps } from '../../../utils/inert';
 import { handleDashboardUrlParsing } from '../shared';
 import { useDragToCorner } from './use-drag-to-corner';
 import { useRevalidateEnvironment } from './use-revalidate-environment';
@@ -506,7 +507,7 @@ function KeylessPromptInternal(props: KeylessPromptProps) {
       </button>
       <div
         id={id}
-        {...(!isOpen && { inert: 'true' })}
+        {...inertProps(!isOpen)}
         css={css`
           ${CSS_RESET};
           display: grid;

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

@@ -3,6 +3,7 @@ import { type PropsWithChildren, useEffect, useState } from 'react';
 import { Box, descriptors, useAppearance } from '../customizables';
 import { usePrefersReducedMotion } from '../hooks';
 import type { ThemableCssProp } from '../styledSystem';
+import { inertProps } from '../utils/inert';
 
 type CollapsibleProps = PropsWithChildren<{
   open: boolean;
@@ -75,7 +76,7 @@ export function Collapsible({ open, children, sx }: CollapsibleProps): JSX.Eleme
         }),
         sx,
       ]}
-      inert={!open ? 'true' : undefined}
+      {...inertProps(!open)}
     >
       <Box
         elementDescriptor={descriptors.collapsibleInner}

packages/ui/src/elements/Collapsible.tsx

@@ -375,7 +375,8 @@ describe('Collapsible', () => {
       rerender(<Collapsible open={false}>Content</Collapsible>);
 
       const element = container.querySelector('.cl-collapsible') as HTMLElement;
-      // Check presence only — React 18 renders inert="true", React 19 normalises to 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(element).toHaveAttribute('inert');
     });