fix(compat): restore React 17/18 compatibility in certain components

CLAUDE.md

@@ -153,6 +153,17 @@ Messages are processed in order:
 - Threads: `state.threads[parentId]` (keyed by parent message ID)
 - **Invariant:** Messages in threads MUST also exist in main channel state
 
+### React Version Compatibility
+
+SDK supports **React 17, 18, 19**.
+
+**Forbidden in `src/`** (enforced by the `react-compat` block in `eslint.config.mjs`):
+
+- `useId` from `react` → use `useStableId` from `src/components/UtilityComponents/useStableId`
+- `useSyncExternalStore` from `react` → use the shim from `use-sync-external-store/shim`
+- `useEffectEvent`, `use()` → not allowed (React 19-only)
+- `ref` declared in a prop type or destructured from props → use `forwardRef` (React 17/18 only deliver `ref` to forwardRef'd components)
+
 ### Context Dependency Gotcha
 
 ```ts

eslint.config.mjs

@@ -122,6 +122,55 @@ export default tseslint.config(
       'react-hooks/exhaustive-deps': 'error',
     },
   },
+  {
+    // Forbid patterns that silently break on React 17 or 18. Approved alternatives:
+    // - useId → src/utils/useStableId.ts
+    // - useSyncExternalStore → use-sync-external-store/shim
+    // - useEffectEvent, use() → not allowed; SDK supports React 17+.
+    // - ref as a regular prop → wrap the component with React.forwardRef
+    name: 'react-compat',
+    files: ['src/**/*.{ts,tsx}'],
+    ignores: [
+      'src/components/UtilityComponents/useStableId.ts',
+      'src/**/__tests__/**',
+      'src/mock-builders/**',
+    ],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          paths: [
+            {
+              name: 'react',
+              importNames: ['useId', 'useSyncExternalStore', 'useEffectEvent', 'use'],
+              message:
+                'React 18+/19-only API. Use useStableId from src/utils/useStableId, useSyncExternalStore from use-sync-external-store/shim. useEffectEvent and use() are not allowed: SDK supports React 17+.',
+            },
+          ],
+        },
+      ],
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector:
+            "MemberExpression[object.name='React'][property.name=/^(useId|useSyncExternalStore|useEffectEvent|use)$/]",
+          message:
+            'React 18+/19-only API. Use useStableId / use-sync-external-store/shim instead of React.<api>.',
+        },
+        {
+          selector: "TSPropertySignature[key.name='ref']",
+          message:
+            '`ref` declared as a regular prop. React 17 and 18 only deliver `ref` to components wrapped in `React.forwardRef` — declare the component with `forwardRef` instead of putting `ref` in the prop type.',
+        },
+        {
+          selector:
+            ":matches(FunctionDeclaration, FunctionExpression, ArrowFunctionExpression) > ObjectPattern > Property[key.name='ref']",
+          message:
+            '`ref` destructured from props. React 17 and 18 only deliver `ref` to components wrapped in `React.forwardRef` — use `React.forwardRef((props, ref) => …)` and take `ref` as the second parameter instead.',
+        },
+      ],
+    },
+  },
   {
     name: 'vitest',
     files: ['src/**/__tests__/**', 'src/mock-builders/**'],

src/components/Attachment/LinkPreview/CardAudio.tsx

@@ -68,7 +68,7 @@ const AudioWidget = ({ mimeType, src }: { src: string; mimeType?: string }) => {
   const { durationSeconds, isPlaying, progress, secondsElapsed } =
     useStateStore(audioPlayer?.state, audioPlayerStateSelector) ?? {};
 
-  if (!audioPlayer) return;
+  if (!audioPlayer) return null;
 
   return (
     <div className='str-chat__message-attachment-card-audio-widget--first-row'>

src/components/ChatView/ChatView.tsx

@@ -4,10 +4,10 @@ import React, {
   createContext,
   useContext,
   useEffect,
-  useId,
   useMemo,
   useState,
 } from 'react';
+import { useStableId } from '../UtilityComponents/useStableId';
 
 import { Button, type ButtonProps } from '../Button';
 import { EmptyStateIndicator as DefaultEmptyStateIndicator } from '../EmptyStateIndicator';
@@ -71,7 +71,7 @@ const useChatViewA11yContext = () => useContext(ChatViewA11yContext);
 
 export const ChatView = ({ children }: PropsWithChildren) => {
   const [activeChatView, setActiveChatView] = useState<ChatView>('channels');
-  const chatViewId = useId().replace(/:/g, '');
+  const chatViewId = useStableId();
 
   const { theme } = useChatContext();
 

src/components/Form/SwitchField.tsx

@@ -7,7 +7,8 @@ import type {
   PropsWithChildren,
   ReactNode,
 } from 'react';
-import React, { isValidElement, useId, useRef, useState } from 'react';
+import React, { isValidElement, useRef, useState } from 'react';
+import { useStableId } from '../UtilityComponents/useStableId';
 
 export type SwitchFieldProps = Omit<
   PropsWithChildren<ComponentProps<'input'>>,
@@ -41,7 +42,7 @@ export const SwitchField = ({
     onKeyDown,
     ...rest
   } = props;
-  const generatedSwitchId = useId();
+  const generatedSwitchId = useStableId();
   const switchId = id ?? `str-chat__switch-field-${generatedSwitchId}`;
   const switchLabelId = `${switchId}-label`;
   const inputRef = useRef<HTMLInputElement | null>(null);

src/components/MediaRecorder/AudioRecorder/AudioRecordingPlayback.tsx

@@ -47,7 +47,7 @@ export const AudioRecordingPlayback = ({
     };
   }, [audioPlayer]);
 
-  if (!audioPlayer) return;
+  if (!audioPlayer) return null;
 
   return (
     <div

src/components/Message/MessageText.tsx

@@ -1,6 +1,7 @@
 import clsx from 'clsx';
-import React, { useId, useMemo } from 'react';
+import React, { useMemo } from 'react';
 import { messageHasAttachments, messageTextHasEmojisOnly } from './utils';
+import { useStableId } from '../UtilityComponents/useStableId';
 
 import type { MessageContextValue } from '../../context';
 import { useMessageContext, useTranslationContext } from '../../context';
@@ -41,8 +42,8 @@ const UnMemoizedMessageTextComponent = (props: MessageTextProps) => {
   const { t, userLanguage } = useTranslationContext('MessageText');
   const message = propMessage || contextMessage;
   const hasAttachment = messageHasAttachments(message);
-  const messageContextId = useId();
-  const messageTextId = useId();
+  const messageContextId = useStableId();
+  const messageTextId = useStableId();
 
   const messageTextToRender =
     translationView === 'original'

src/components/MessageActions/QuickMessageActionButton.tsx

@@ -1,14 +1,19 @@
 import { Button, type ButtonProps } from '../Button';
 import clsx from 'clsx';
-import React from 'react';
+import React, { forwardRef } from 'react';
 
-export const QuickMessageActionsButton = ({ className, ...props }: ButtonProps) => (
-  <Button
-    appearance='ghost'
-    circular
-    className={clsx('str-chat__message-actions-box-button', className)}
-    size='sm'
-    variant='secondary'
-    {...props}
-  />
+export const QuickMessageActionsButton = forwardRef<HTMLButtonElement, ButtonProps>(
+  function QuickMessageActionsButton({ className, ...props }, ref) {
+    return (
+      <Button
+        appearance='ghost'
+        circular
+        className={clsx('str-chat__message-actions-box-button', className)}
+        ref={ref}
+        size='sm'
+        variant='secondary'
+        {...props}
+      />
+    );
+  },
 );

src/components/MessageList/hooks/useReducedMotionPreference.ts

@@ -1,4 +1,4 @@
-import { useSyncExternalStore } from 'react';
+import { useSyncExternalStore } from 'use-sync-external-store/shim';
 
 const REDUCED_MOTION_MEDIA_QUERY = '(prefers-reduced-motion: reduce)';
 

src/components/Poll/PollHeader.tsx

@@ -36,7 +36,7 @@ export const PollHeader = () => {
     return '';
   }, [is_closed, enforce_unique_vote, max_votes_allowed, options.length, t]);
 
-  if (!name) return;
+  if (!name) return null;
 
   return (
     <div className='str-chat__poll-header'>

src/components/Search/SearchBar/SearchBar.tsx

@@ -1,6 +1,7 @@
 import clsx from 'clsx';
 import React, { useEffect, useState } from 'react';
 
+import { useStableId } from '../../UtilityComponents/useStableId';
 import { useSearchContext } from '../SearchContext';
 import { useSearchQueriesInProgress } from '../hooks';
 import { useTranslationContext } from '../../../context';
@@ -25,7 +26,7 @@ export const SearchBar = () => {
   } = useSearchContext();
   const queriesInProgress = useSearchQueriesInProgress(searchController);
   const clearButtonRef = React.useRef<HTMLButtonElement | null>(null);
-  const searchInputId = React.useId();
+  const searchInputId = useStableId();
 
   const [input, setInput] = useState<HTMLInputElement | null>(null);
   const { isActive, searchQuery } = useStateStore(

src/components/Search/SearchResults/SearchResultItem.tsx

@@ -74,7 +74,7 @@ export const MessageSearchResultItem = ({
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
   const getLatestMessagePreview = useCallback(() => item.text!, [item]);
 
-  if (!channel) return;
+  if (!channel) return null;
 
   return (
     <ChannelListItem

src/components/UtilityComponents/__tests__/useStableId.test.ts

@@ -0,0 +1,39 @@
+import { renderHook } from '@testing-library/react';
+
+import { stripUseIdWrappers, useStableId } from '../useStableId';
+
+describe('useStableId', () => {
+  it('returns a non-empty string', () => {
+    const { result } = renderHook(() => useStableId());
+    expect(typeof result.current).toBe('string');
+    expect(result.current.length).toBeGreaterThan(0);
+  });
+
+  it('is stable across re-renders', () => {
+    const { rerender, result } = renderHook(() => useStableId());
+    const initial = result.current;
+    rerender();
+    rerender();
+    expect(result.current).toBe(initial);
+  });
+
+  it('returns distinct values from two hook calls in the same component', () => {
+    const { result } = renderHook(() => [useStableId(), useStableId()] as const);
+    expect(result.current[0]).not.toBe(result.current[1]);
+  });
+
+  it('never contains a colon (so it is safe as an HTML id)', () => {
+    const { result } = renderHook(() => useStableId());
+    expect(result.current).not.toContain(':');
+  });
+});
+
+describe('stripUseIdWrappers', () => {
+  it('strips colons from React 19.0 format (:r0:)', () => {
+    expect(stripUseIdWrappers(':r0:')).toBe('r0');
+  });
+
+  it('strips guillemets from React 19.1 format («r0»)', () => {
+    expect(stripUseIdWrappers('«r0»')).toBe('r0');
+  });
+});

src/components/UtilityComponents/useStableId.ts

@@ -1,13 +1,22 @@
 import { nanoid } from 'nanoid';
-import { useMemo } from 'react';
+import React, { useMemo } from 'react';
+
+const reactUseId = React.useId as (() => string) | undefined;
+
+// Strips React.useId() wrapper characters so the value is safe as an HTML id:
+// from React 19.0 (`:r0:` -> `r0`) and 19.1 (`«r0»` -> `r0`);
+// 19.2+ uses `_r_1_` which is safe and doesn't need stripping
+export const stripUseIdWrappers = (id: string): string => id.replace(/[:«»]/g, '');
 
 /**
- * The ID is generated using the `nanoid` library and is memoized to ensure
- * that it remains the same across renders unless the key changes.
+ * Returns a stable, unique string id.
+ *
+ * On React 18+ this delegates to `React.useId()` (with the surrounding wrapper
+ * characters stripped so the value is safe to use anywhere an HTML id is expected)
+ * and is SSR-stable. On React 17, it falls back to a client-only id generated via `nanoid`.
  */
-export const useStableId = (key?: string) => {
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  const id = useMemo(() => nanoid(), [key]);
-
-  return id;
+export const useStableId = () => {
+  if (reactUseId) return stripUseIdWrappers(reactUseId());
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  return useMemo(() => nanoid(), []);
 };