@react-aria: forwardRef support

[jlarmstrongiv]

🙋‍♂️ Feature Request

Support for React.forwardRef on custom form elements to accommodate:

• The uncontrolled components pattern
• Third party libraries, such as react-hook-form

🤔 Expected Behavior

• Having an optional ref on my custom form component.

😯 Current Behavior

• I can use React.forwardRef, but then I would always need to pass in a ref
• I can go without refs, forgoing their benefits

💁‍♂️ Possible Solution / 💻 Examples

Implement a utility to share / combine refs. Several similar implementations already exist:

• https://gist.github.com/pie6k/b4717f392d773a71f67e110b42927fea
• https://itnext.io/reusing-the-ref-from-forwardref-with-react-hooks-4ce9df693dd
• https://gist.github.com/ray851107/b97a0e240d6b9262d1d04d85c63ecada
• https://github.com/smooth-code/react-merge-refs/blob/master/src/index.js

🔦 Context

I would like to build robust and accessible custom form components that support both controlled and uncontrolled component patterns.

[devongovett]

One pattern we've used is something like this:

const Button = React.forwardRef((props, ref) => {
  let fallbackRef = React.useRef();
  let domRef = ref || fallbackRef;

  return (
    <button ref={domRef}>button</button>
  );
});

This uses the passed ref if available, but falls back to a ref created by useRef. Is that what you were thinking? Seems like a nice util to have potentially.

[jlarmstrongiv]

Yes, that’s exactly what I was thinking! Thank you for the example 👍 either a utility hook or a mention in the docs would be a nice addition

[devongovett]

Sounds good! We could add a useOptionalRef hook to the @react-aria/utils package.

[Andarist]

Just keep in mind that you might often need access to the ref.current, but the provided ref can be a function - so instead of a simple ref || fallbackRef; you might need to implement a more complex solution of composing refs. I see that @jlarmstrongiv has already linked to such solutions - so you can take inspiration there. None of them behaves like regular refs though (the update timing is different, refs are not cleared with null etc) - I believe that the hook I've created in the past for my own usage gets pretty close to the regular semantics of refs: https://github.com/Andarist/use-composed-ref/blob/1cafdd6123d7e7aa4f3c8e6a74950c761524329a/src/index.ts#L20 .

[jherr]

@devongovett I'm not sure how to use your advice here on making a new version of, something like TextField with React.forwardRef. What React-Hook-Form is looking for is a ref for the underlying input. Other component toolkits have something like inputRef or innerRef as a property to handle this case. Is there something like that in Spectrum that I'm just not finding? I've scoured all the type definitions and the code.

[Andarist]

Other component toolkits have something like inputRef or innerRef as a property to handle this case

Those props only exist because in the past there was no React.forwardRef so a different prop name than ref had to be used to account for this issue.

The thing here gets complicated because TextFieldBase is using useImperativeHandle. Ideally TextFieldBase would use React.forwardRef as well and reuse the received ref when possible, but not sure how to best handle this here - given the API choice to expose extra imperative methods on the external ref rather than exposing the raw DOM node.

[jherr]

@Andarist Thanks for the reply. I'm down with using ref but that doesn't work in this case either. If it should work then I'd be happy to try to put together a PR that would make it work. I'm just not sure what the intention is.

[devongovett]

It was an intentional choice to not expose the raw DOM node from our refs, but wrap in an API we control. This allows us to swap out the underlying implementation when needed, e.g. switch element types. Also allows us to reuse the same API across multiple platforms, e.g. native, where the internal elements are different. Sometimes it's also unclear where the ref prop that's forwarded should go – does it go on the outer most element or on something inside?

There is a ref.current.UNSAFE_getDOMNode() method to get the outer-most element of any component in React Spectrum. This is unsafe because we don't guarantee stability of the element type that is returned. For textfield, there's also ref.current.getInputElement(), which returns the <input> element specifically.

If you need a ref object to pass the native input to something else, you could do something like this:

let textfieldRef = useRef();
let inputRef = {
  get current() {
    return textFieldRef.current.getInputElement();
  }
};

// Pass inputRef to whatever you like...

<TextField ref={textFieldRef} />

Perhaps there could be a util function to do this...

[jherr]

Gotcha. Thanks! Turns out that at least for react-hook-form you can us a Controller and manage it without a ref.

[bogdansoare]

Also having trouble with React's forwardRef and useTextField from @react-aria. My use case is the same, using react-hook-form. I think an utility should be baked in @react-aria since this is pretty common usage

[bluebill1049]

One of the benefits of exposing ref to third-party lib like react-hook-form is so we can focus on that input when an error occurred to improve accessibility. looking forward to the potential update.

[devongovett]

The ref exposed by the TextField component does have a focus() method already...

[reminjp]

I'm having trouble with the type error that the ref from React.forwardRef is React.Ref but @react-aria hooks accept only React.RefObject. Is there any recommended solution? Should we import @react-spectrum to use useDOMRef? Does anyone plan to add a hook like useDOMRef or useComposedRef (mentioned in #834 (comment)) to @react-aria?

[skywinston]

Similar situation: I'm attempting to forward a ref to a component using the useButton hook, and it does not like the ref:

import React from "react";
import { useButton } from "@react-aria/button";

const Button = React.forwardRef((props, forwardedRef) => {
  let internalRef = React.useRef();
  let ref = forwardedRef || internalRef;

  let { buttonProps } = useButton(props, ref);

  return (
    <button {...buttonProps} ref={ref}>
      {props.children}
    </button>
  );
});

export default Button;

The ref in the useButton hook displays this error:

No overload matches this call.
  The last overload gave the following error.
    Argument of type '((instance: unknown) => void) | MutableRefObject<unknown>' is not assignable to parameter of type 'RefObject<HTMLElement>'.
      Property 'current' is missing in type '(instance: unknown) => void' but required in type 'RefObject<HTMLElement>'.ts(2769)

Codesandbox here

[chrishoage]

We are trying to build a component library using react-aria and are running into trouble due to the types from TypeScript.

Being unable to wrap this hook inside forwardRef is becoming quite a challenge.

Like skywinston the "workaround" doesn't satisfy the types for useButton.

Is the React.forwardRef pattern supported by react-aria? If so is there an accepted way to achieve this behavior?

Edit: I was able to make this "work" by asserting that the ref is a mutable object ref

function assertOnlyObjectRef<RefType>(
  ref: ForwardedRef<RefType>
): asserts ref is MutableRefObject<RefType | null> | null {
  if (typeof ref === 'function') {
    throw new Error('This component may only be used with an object ref');
  }
}

export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  (
    { children, size = Size.M, style = Style.Default, ...buttonHookProps },
    forwardRef
  ) => {
    assertOnlyObjectRef(forwardRef);

    const internalRef = useRef<HTMLButtonElement>(null);
    const ref = forwardRef ?? internalRef;

    const { buttonProps } = useButton(buttonHookProps, ref);

    return (
      <button
        className={clsx(styles.button, styles[size], styles[style])}
        ref={ref}
        {...buttonProps}
      >
          {children}
      </button>
    );
  }
);

Is this the expected way to use useButton inside forwardRef with TypeScript?

[snowystinger]

I'm curious, we use it just fine in our own component without that assertion
https://github.com/adobe/react-spectrum/blob/main/packages/%40react-spectrum/button/src/Button.tsx

I'm no typescript expert though, really just a user, so maybe we've made some error in our own?

[allforabit]

@snowystinger I'd say it's due to strict mode being enabled in the tsconfig.json

[chrishoage]

I think it could also be due to this hook

react-spectrum/packages/@react-spectrum/utils/src/useDOMRef.ts

Line 41 in e066b67

export function useFocusableRef<T extends HTMLElement = HTMLElement>(ref: FocusableRef<T>, focusableRef?: RefObject<HTMLElement>): RefObject<T> {

It returns a mutable object ref from useRef and the ref from forwardRef is consumed by useImperativeHandle

The other issue I see is that Button.tsx casts React.forwardRef(Button) as a function that doesn't match the signature of forwardRef

Basically that Button.tsx is instructing typescript that it has a different signature that React.forwardRef actually defined

The crux of the issue useButton has types which can't accept a ref function which the type signature of React.forwardRef allows for.

My assertion narrows the type of the forward ref to only be a RefObject which satisfies the types of useButton

I imagine if the casting was removed from the Button.tsx example you shared it would expose a similar type error as described by myself and skywinston

[chrishoage]

@snowystinger I have modified Button.tsx to be a more typical / common usage of forwardRef and it exposes the same problem

I will be clear I understand that the casting is to support a generic button ElemenType which otherwise can't be supported with React.forwardRef however the type signature that it is cast to is not honest to the actual types that React.forwardRef will return in normal usage of React.

Passing a ref function is a normal and supported way of retereving a ref from a component, one which useButton (and I presume a lot of other hooks in the react-aria codebase) don't support.

I hope this diff illustates the issue clearly in the react-spectum codebase.

Please let me know if you have further questions or there is anything that I may clearify!

diff --git a/packages/@react-spectrum/button/src/Button.tsx b/packages/@react-spectrum/button/src/Button.tsx
index 6dea9cde..ed2f3ff3 100644
--- a/packages/@react-spectrum/button/src/Button.tsx
+++ b/packages/@react-spectrum/button/src/Button.tsx
@@ -10,24 +10,30 @@
  * governing permissions and limitations under the License.
  */
 
-import {classNames, SlotProvider, useFocusableRef, useSlotProps, useStyleProps} from '@react-spectrum/utils';
-import {FocusableRef} from '@react-types/shared';
-import {FocusRing} from '@react-aria/focus';
-import {mergeProps} from '@react-aria/utils';
-import React, {ElementType, ReactElement} from 'react';
-import {SpectrumButtonProps} from '@react-types/button';
+import { classNames, SlotProvider, useFocusableRef, useSlotProps, useStyleProps } from '@react-spectrum/utils';
+import { FocusableRef } from '@react-types/shared';
+import { FocusRing } from '@react-aria/focus';
+import { mergeProps } from '@react-aria/utils';
+import React, { ElementType, ReactElement } from 'react';
+import { SpectrumButtonProps } from '@react-types/button';
 import styles from '@adobe/spectrum-css-temp/components/button/vars.css';
-import {Text} from '@react-spectrum/text';
-import {useButton} from '@react-aria/button';
-import {useHover} from '@react-aria/interactions';
-import {useProviderProps} from '@react-spectrum/provider';
+import { Text } from '@react-spectrum/text';
+import { useButton } from '@react-aria/button';
+import { useHover } from '@react-aria/interactions';
+import { useProviderProps } from '@react-spectrum/provider';
 
 // todo: CSS hasn't caught up yet, map
 let VARIANT_MAPPING = {
   negative: 'warning'
 };
 
-function Button<T extends ElementType = 'button'>(props: SpectrumButtonProps<T>, ref: FocusableRef<HTMLElement>) {
+
+/**
+ * Buttons allow users to perform an action or to navigate to another page.
+ * They have multiple styles for various needs, and are ideal for calling attention to
+ * where a user needs to do something in order to move forward in a flow.
+ */
+let _Button = React.forwardRef<HTMLElement, SpectrumButtonProps<'button'>>((props, ref) => {
   props = useProviderProps(props);
   props = useSlotProps(props, 'button');
   let {
@@ -39,10 +45,10 @@ function Button<T extends ElementType = 'button'>(props: SpectrumButtonProps<T>,
     autoFocus,
     ...otherProps
   } = props;
-  let domRef = useFocusableRef(ref);
-  let {buttonProps, isPressed} = useButton(props, domRef);
-  let {hoverProps, isHovered} = useHover({isDisabled});
-  let {styleProps} = useStyleProps(otherProps);
+  // let domRef = useFocusableRef(ref);
+  let { buttonProps, isPressed } = useButton(props, ref);
+  let { hoverProps, isHovered } = useHover({ isDisabled });
+  let { styleProps } = useStyleProps(otherProps);
 
   let buttonVariant = variant;
   if (VARIANT_MAPPING[variant]) {
@@ -86,12 +92,5 @@ function Button<T extends ElementType = 'button'>(props: SpectrumButtonProps<T>,
       </ElementType>
     </FocusRing>
   );
-}
-
-/**
- * Buttons allow users to perform an action or to navigate to another page.
- * They have multiple styles for various needs, and are ideal for calling attention to
- * where a user needs to do something in order to move forward in a flow.
- */
-let _Button = React.forwardRef(Button) as <T extends ElementType = 'button'>(props: SpectrumButtonProps<T> & {ref?: FocusableRef<HTMLElement>}) => ReactElement;
-export {_Button as Button};
+});
+export { _Button as Button };

[Newbie012]

What's the status of this issue? not to be rude, but it gets impossible to integrate @react-aria with a strictly typed app 😟

[Newbie012]

I managed to find a solution via useImperativeHandle:

const Checkbox = React.forwardRef(
  (props: PropsWithChildren<CheckboxProps>, ref: React.ForwardedRef<HTMLInputElement>) => {
    const inputRef = React.useRef<HTMLInputElement>(null);

    const { inputProps } = useCheckbox(props, state, inputRef);

    React.useImperativeHandle(ref, getCurrentRef(inputRef));

    return (
      <CheckboxWrapper isValid={isValid} isDisabled={isDisabled}>
        <VisuallyHidden>
          <input {...inputProps} {...focusProps} ref={inputRef} />
        </VisuallyHidden>
        ...
      </CheckboxWrapper>
    );
  }
);

export function getCurrentRef<T>(ref: React.RefObject<T>) {
  return () => {
    if (ref.current === null) {
      throw new Error("getCurrentRef should only be used when ref is certainly defined");
    }

    return ref.current;
  };
}

[LFDanLu]

Handled in #2293, should go out in the next release

[devongovett]

Did we do this yet? #2293 (comment)

[LFDanLu]

Ah my bad, reopening. For others in the thread, useObjectRef will be available in the next release in react-aria/utils but we are planning on calling that util hook to our aria hooks so that you won't need to do so yourselves.

[solimant]

@devongovett, @LFDanLu - I've created #2503 to track the ask in #2293 (comment). I think we can close this since we have a way to address the original ask, albeit not ideal.

[jlarmstrongiv]

• To confirm, is useObjectRef is available in the latest release?
• Was this issue addressed?
• So an example of current usage would be something like this?

    const TextField = React.forwardRef((props, forwardedRef) => {
      const ref = useObjectRef(forwardedRef);

      return <input {...props} ref={ref} />;
    });

[bstro]

@jlarmstrongiv I can't speak to the question in your second bullet point, but I don't think it has been released yet. I've been copying the file at this commit and pasting it into my projects until it is published properly. Not ideal, but I don't mind using it as a stop-gap until the next release of react-aria. Your usage example is how I've been using it.

[LFDanLu]

@jlarmstrongiv It is not currently available in the current release but it will be with the next release (3.15). For now you can access it via a the @react-aria/util nightlies. The usage looks good to me, I'll have @solimant answer the second bullet point.

[devongovett]

Followup task tracked in #2503. Closing this ticket.