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

.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}

packages/ui/src/elements/__tests__/Collapsible.test.tsx

@@ -367,15 +367,17 @@ describe('Collapsible', () => {
  });
 
  describe('Inert Attribute', () => {
- it('sets inert to empty string when open={false}', async () => {
+ it('sets inert when open={false}', async () => {
  const { wrapper } = await createFixtures();
  const { container, rerender } = render(<Collapsible open>Content</Collapsible>, { wrapper });
 
  await waitForAnimationFrame();
  rerender(<Collapsible open={false}>Content</Collapsible>);
 
  const element = container.querySelector('.cl-collapsible') as HTMLElement;
- expect(element).toHaveAttribute('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');
  });
 
  it('does not set inert when open={true}', async () => {

.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}

packages/ui/src/elements/__tests__/Collapsible.test.tsx

@@ -367,15 +367,17 @@ describe('Collapsible', () => {
  });
 
  describe('Inert Attribute', () => {
- it('sets inert to empty string when open={false}', async () => {
+ it('sets inert when open={false}', async () => {
  const { wrapper } = await createFixtures();
  const { container, rerender } = render(<Collapsible open>Content</Collapsible>, { wrapper });
 
  await waitForAnimationFrame();
  rerender(<Collapsible open={false}>Content</Collapsible>);
 
  const element = container.querySelector('.cl-collapsible') as HTMLElement;
- expect(element).toHaveAttribute('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');
  });
 
  it('does not set inert when open={true}', async () => {

.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}

packages/ui/src/elements/__tests__/Collapsible.test.tsx

@@ -367,15 +367,17 @@ describe('Collapsible', () => {
  });
 
  describe('Inert Attribute', () => {
- it('sets inert to empty string when open={false}', async () => {
+ it('sets inert when open={false}', async () => {
  const { wrapper } = await createFixtures();
  const { container, rerender } = render(<Collapsible open>Content</Collapsible>, { wrapper });
 
  await waitForAnimationFrame();
  rerender(<Collapsible open={false}>Content</Collapsible>);
 
  const element = container.querySelector('.cl-collapsible') as HTMLElement;
- expect(element).toHaveAttribute('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');
  });
 
  it('does not set inert when open={true}', async () => {

.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}

packages/ui/src/elements/__tests__/Collapsible.test.tsx

@@ -367,15 +367,17 @@ describe('Collapsible', () => {
  });
 
  describe('Inert Attribute', () => {
- it('sets inert to empty string when open={false}', async () => {
+ it('sets inert when open={false}', async () => {
  const { wrapper } = await createFixtures();
  const { container, rerender } = render(<Collapsible open>Content</Collapsible>, { wrapper });
 
  await waitForAnimationFrame();
  rerender(<Collapsible open={false}>Content</Collapsible>);
 
  const element = container.querySelector('.cl-collapsible') as HTMLElement;
- expect(element).toHaveAttribute('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');
  });
 
  it('does not set inert when open={true}', async () => {

.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}

packages/ui/src/elements/__tests__/Collapsible.test.tsx

@@ -367,15 +367,17 @@ describe('Collapsible', () => {
  });
 
  describe('Inert Attribute', () => {
- it('sets inert to empty string when open={false}', async () => {
+ it('sets inert when open={false}', async () => {
  const { wrapper } = await createFixtures();
  const { container, rerender } = render(<Collapsible open>Content</Collapsible>, { wrapper });
 
  await waitForAnimationFrame();
  rerender(<Collapsible open={false}>Content</Collapsible>);
 
  const element = container.querySelector('.cl-collapsible') as HTMLElement;
- expect(element).toHaveAttribute('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');
  });
 
  it('does not set inert when open={true}', async () => {

.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}

packages/ui/src/elements/__tests__/Collapsible.test.tsx

@@ -367,15 +367,17 @@ describe('Collapsible', () => {
  });
 
  describe('Inert Attribute', () => {
- it('sets inert to empty string when open={false}', async () => {
+ it('sets inert when open={false}', async () => {
  const { wrapper } = await createFixtures();
  const { container, rerender } = render(<Collapsible open>Content</Collapsible>, { wrapper });
 
  await waitForAnimationFrame();
  rerender(<Collapsible open={false}>Content</Collapsible>);
 
  const element = container.querySelector('.cl-collapsible') as HTMLElement;
- expect(element).toHaveAttribute('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');
  });
 
  it('does not set inert when open={true}', async () => {

.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}

packages/ui/src/elements/__tests__/Collapsible.test.tsx

@@ -367,15 +367,17 @@ describe('Collapsible', () => {
  });
 
  describe('Inert Attribute', () => {
- it('sets inert to empty string when open={false}', async () => {
+ it('sets inert when open={false}', async () => {
  const { wrapper } = await createFixtures();
  const { container, rerender } = render(<Collapsible open>Content</Collapsible>, { wrapper });
 
  await waitForAnimationFrame();
  rerender(<Collapsible open={false}>Content</Collapsible>);
 
  const element = container.querySelector('.cl-collapsible') as HTMLElement;
- expect(element).toHaveAttribute('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');
  });
 
  it('does not set inert when open={true}', async () => {

.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}

packages/ui/src/elements/__tests__/Collapsible.test.tsx

@@ -367,15 +367,17 @@ describe('Collapsible', () => {
  });
 
  describe('Inert Attribute', () => {
- it('sets inert to empty string when open={false}', async () => {
+ it('sets inert when open={false}', async () => {
  const { wrapper } = await createFixtures();
  const { container, rerender } = render(<Collapsible open>Content</Collapsible>, { wrapper });
 
  await waitForAnimationFrame();
  rerender(<Collapsible open={false}>Content</Collapsible>);
 
  const element = container.querySelector('.cl-collapsible') as HTMLElement;
- expect(element).toHaveAttribute('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');
  });
 
  it('does not set inert when open={true}', async () => {