refs in v3

1. refs are not included in the API documentation on material-ui.com
2. type declarations forbid ref e.g. <Button ref={handleRef} /> but allow innerRef for every component
   • The latter is wrong in some cases. E.g. The inner components of Paper or Backdrop are function components and can therefore not hold refs. It will trigger a runtime warning.
3. withStyles from @material-ui/core does not forward refs from ref but innerRef.
   • named props for refs can be problematic if multiple HOCs are used. E.g. Using styled-components to style material-ui components will prevent innerRef from being passed to the inner material-ui component.

Proposal

explicitly document ref

Couple of alternatives:

1. We could start by collecting what components allow this at the moment (basically every component wrapped in withStyles). This will break in v4 if [styles] Improve ref forwarding #13676 is accepted
2. Disallow ref on all of our components. If the DOM node is required RootRef should be used.

The type declarations follow from the documentation.

ref in v4

With #13676 and the replacement of @material-ui/core/styles with @material-ui/styles as our internal styling solution <Button ref /> would return the ref to the inner component by default. In it's current state some components would loose the ability to hold ref (e.g. AppBar).

There is an argument to be made that ref inherently cause all sorts of problems in general. However I would argue that all of our components return some html element. Interfacing our components so that they only return a ref to an abstract HTMLElement should therefore cause no problems in the future. It doesn't bind us to any specific implementation (other than a html element). This allows e.g. layout computations if necessary or imperative focus which is what we use internally.

I'm in favor of enabling refs on all of our existing components. It allows for a simpler API where one doesn't have to look at the API docs for every single component and check if it allows ref (and then be annoyed because we didn't have your use case in mind). (Although TS users can be lazy and don't have to check API docs).

Summary

1. Add explicit documentation
2. Fix typescript declarations
3. One of
   1. Disallow ref on all components i.e. use ref at your own risk. Prefer RootRef if you need the DOM node
      • RootRef will trigger findDOMNode deprecation warnings
   2. Don't change ref behavior for inner components. ref behavior on actual component will change though with [styles] Improve ref forwarding #13676.
      • users are stuck with findDOMNode
   3. Allow ref on all components. Interface it as a abstract HTMLElement
      • strict and concurrent mode viable for all current use cases

Confirmed

• add explicit documentation
• fix typescript declarations
• add migration guide [docs] Document ref forwarding (requirements) #15298
• add prop-type if we require refs in the component
• forward refs for every component (started in [core] forward innerRef for certain components #14536)

Resources

• Refs and the DOM
• RootRef
• issue: Warnings in strict mode #13394
• issue: Use forwardRef #10825

/cc @mui-org/core-contributors