Fix hydration mismatch error in OneTimePasswordField and add opt-in index prop

Author: chaance

.changeset/stupid-bananas-talk.md

@@ -0,0 +1,6 @@
+---
+'@radix-ui/react-one-time-password-field': patch
+'@radix-ui/react-roving-focus': patch
+---
+
+Fix hydration mismatch error in `OneTimePasswordField` and add opt-in `index` prop

apps/ssr-testing/app/one-time-password-field/page.tsx

@@ -3,14 +3,26 @@ import { unstable_OneTimePasswordField as OneTimePasswordField } from 'radix-ui'
 
 export default function Page() {
   return (
-    <OneTimePasswordField.Root>
-      <OneTimePasswordField.Input />
-      <OneTimePasswordField.Input />
-      <OneTimePasswordField.Input />
-      <OneTimePasswordField.Input />
-      <OneTimePasswordField.Input />
-      <OneTimePasswordField.Input />
-      <OneTimePasswordField.HiddenInput />
-    </OneTimePasswordField.Root>
+    <div>
+      <OneTimePasswordField.Root placeholder="123456">
+        <OneTimePasswordField.Input />
+        <OneTimePasswordField.Input />
+        <OneTimePasswordField.Input />
+        <OneTimePasswordField.Input />
+        <OneTimePasswordField.Input />
+        <OneTimePasswordField.Input />
+        <OneTimePasswordField.HiddenInput />
+      </OneTimePasswordField.Root>
+      <h2>With indices</h2>
+      <OneTimePasswordField.Root placeholder="123456">
+        <OneTimePasswordField.Input index={0} />
+        <OneTimePasswordField.Input index={1} />
+        <OneTimePasswordField.Input index={2} />
+        <OneTimePasswordField.Input index={3} />
+        <OneTimePasswordField.Input index={4} />
+        <OneTimePasswordField.Input index={5} />
+        <OneTimePasswordField.HiddenInput />
+      </OneTimePasswordField.Root>
+    </div>
   );
 }

packages/react/one-time-password-field/src/one-time-password-field.tsx

@@ -56,7 +56,6 @@ interface OneTimePasswordFieldContextValue {
   name: string | undefined;
   orientation: Exclude<RovingFocusGroupProps['orientation'], undefined>;
   placeholder: string | undefined;
-  preHydrationIndexTracker: React.RefObject<number>;
   readOnly: boolean;
   type: InputType;
   userActionRef: React.RefObject<KeyboardActionDetails | null>;
@@ -429,13 +428,6 @@ const OneTimePasswordField = React.forwardRef<HTMLDivElement, OneTimePasswordFie
         attemptSubmit();
       }
     }, [attemptSubmit, autoSubmit, currentValue, length, onAutoSubmit, value]);
-
-    // Before hydration (and in SSR) we can track the index of an input during
-    // render, as indices calculated by the collection package should almost
-    // always align with render order anyway. This ensures that index-dependent
-    // attributes are immediately rendered, in case browser extensions rely on
-    // those for auto-complete functionality and JS has not hydrated.
-    const preHydrationIndexTracker = React.useRef<number>(0);
     const isHydrated = useIsHydrated();
 
     return (
@@ -456,7 +448,6 @@ const OneTimePasswordField = React.forwardRef<HTMLDivElement, OneTimePasswordFie
         dispatch={dispatch}
         validationType={validationType}
         orientation={orientation}
-        preHydrationIndexTracker={preHydrationIndexTracker}
         isHydrated={isHydrated}
         sanitizeValue={sanitizeValue}
       >
@@ -560,6 +551,12 @@ interface OneTimePasswordFieldInputProps
    * Callback fired when the user input fails native HTML input validation.
    */
   onInvalidChange?: (character: string) => void;
+  /**
+   * User-provided index to determine the order of the inputs. This is useful if
+   * you need certain index-based attributes to be set on the initial render,
+   * often to prevent flickering after hydration.
+   */
+  index?: number;
 }
 
 const OneTimePasswordFieldInput = React.forwardRef<
@@ -569,6 +566,7 @@ const OneTimePasswordFieldInput = React.forwardRef<
   {
     __scopeOneTimePasswordField,
     onInvalidChange,
+    index: indexProp,
     ...props
   }: ScopedProps<OneTimePasswordFieldInputProps>,
   forwardedRef
@@ -592,25 +590,20 @@ const OneTimePasswordFieldInput = React.forwardRef<
     'OneTimePasswordFieldInput',
     __scopeOneTimePasswordField
   );
-  const { dispatch, userActionRef, validationType, preHydrationIndexTracker, isHydrated } = context;
+  const { dispatch, userActionRef, validationType, isHydrated } = context;
   const collection = useCollection(__scopeOneTimePasswordField);
   const rovingFocusGroupScope = useRovingFocusGroupScope(__scopeOneTimePasswordField);
 
   const inputRef = React.useRef<HTMLInputElement>(null);
   const [element, setElement] = React.useState<HTMLInputElement | null>(null);
 
+  const index = indexProp ?? (element ? collection.indexOf(element) : -1);
+  const canSetPlaceholder = indexProp != null || isHydrated;
   let placeholder: string | undefined;
-  let index: number;
-  if (!isHydrated) {
-    index = preHydrationIndexTracker.current;
-    preHydrationIndexTracker.current++;
-  } else {
-    index = element ? collection.indexOf(element) : -1;
-    if (context.placeholder && context.value.length === 0) {
-      // only set placeholder after hydration to prevent flickering when indices
-      // are re-calculated
-      placeholder = context.placeholder[index];
-    }
+  if (canSetPlaceholder && context.placeholder && context.value.length === 0) {
+    // only set placeholder after hydration to prevent flickering when indices
+    // are re-calculated
+    placeholder = context.placeholder[index];
   }
 
   const composedInputRef = useComposedRefs(forwardedRef, inputRef, setElement);
@@ -640,8 +633,8 @@ const OneTimePasswordFieldInput = React.forwardRef<
         focusable={!context.disabled && isFocusable}
         active={index === lastSelectableIndex}
       >
-        {({ isCurrentTabStop }) => {
-          const supportsAutoComplete = isHydrated ? isCurrentTabStop : index === 0;
+        {({ hasTabStop, isCurrentTabStop }) => {
+          const supportsAutoComplete = hasTabStop ? isCurrentTabStop : index === 0;
           return (
             <Primitive.Root.input
               ref={composedInputRef}

packages/react/roving-focus/src/roving-focus-group.tsx

@@ -206,7 +206,9 @@ interface RovingFocusItemProps extends Omit<PrimitiveSpanProps, 'children'> {
   tabStopId?: string;
   focusable?: boolean;
   active?: boolean;
-  children?: React.ReactNode | ((props: { isCurrentTabStop: boolean }) => React.ReactNode);
+  children?:
+    | React.ReactNode
+    | ((props: { hasTabStop: boolean; isCurrentTabStop: boolean }) => React.ReactNode);
 }
 
 const RovingFocusGroupItem = React.forwardRef<RovingFocusItemElement, RovingFocusItemProps>(
@@ -225,7 +227,7 @@ const RovingFocusGroupItem = React.forwardRef<RovingFocusItemElement, RovingFocu
     const isCurrentTabStop = context.currentTabStopId === id;
     const getItems = useCollection(__scopeRovingFocusGroup);
 
-    const { onFocusableItemAdd, onFocusableItemRemove } = context;
+    const { onFocusableItemAdd, onFocusableItemRemove, currentTabStopId } = context;
 
     React.useEffect(() => {
       if (focusable) {
@@ -287,7 +289,9 @@ const RovingFocusGroupItem = React.forwardRef<RovingFocusItemElement, RovingFocu
             }
           })}
         >
-          {typeof children === 'function' ? children({ isCurrentTabStop }) : children}
+          {typeof children === 'function'
+            ? children({ isCurrentTabStop, hasTabStop: currentTabStopId != null })
+            : children}
         </Primitive.span>
       </Collection.ItemSlot>
     );