Let's create a polymorphic as prop API standard

[rafgraph]

cc: @radix-ui, @jjenzz, @benoitgrelard as this idea applies to the Radix primitive components as well.

I'm a fan of the polymorphic as prop. I've been using it in React Interactive since 2016 (I think this was the first occurrence), and since then it's seen wide spread use with Styled Components helping to popularize it. With multiple libraries implementing the polymorphic as prop, I think composability needs to be added to polymorphism (the lack of composability has already caused multiple issues, for example #448). A standardized polymorphic API that libraries and components can implement would accomplish this, and would allow multiple polymorphic components to work together seamlessly.

The idea for this is something that I've been thinking about on and off for a bit, and was inspired by this clever styled function PoC by @jjenzz.

---

⚡️ API ideas (below) ⚡️ Proof of concept npm package

Try out the proof of concept in CodeSandbox

---

API ideas

The API needs to define a standardized way to:

• Determine at runtime if a component implements the polymorphic API
• Create multilevel polymorphism when the polymorphic API is implemented by both components
• Merge two lines of polymorphism with a create polymorphic function (for example a styled function)

---

Determine at runtime if the API is implemented

In @jjenzz's styled PoC she calls the component function with a dummy as prop, and then checks the returned React Element's type to accomplish this. This is some quality hacking 😄 but I don't believe it will scale (there are too many edge cases, e.g. side effects when calling the function component, React components in the form of forwarded ref and memo objects, etc).

The simplest solution is probably to add a property to the component indicating support for the API (the polymorphicAsArray name will be explained in the next section).

const MyPolymorphicComponent = (/*...*/) => {
  /*...*/
};

MyPolymorphicComponent.polymorphicAsArray = true;

// then at runtime in some other component we can do
if (SomeComponent.polymorphicAsArray === true) {
  // SomeComponent implements the polymorphic API
}

---

Create multilevel polymorphism

Polymorphic components can support multilevel polymorphism by accepting an array for the as prop.

• A component that implements the polymorphicAsArray API would need to:
  • Accept an array for the as prop
  • Remove the first item from the as array and check if it supports the polymorphicAsArray API, if yes render it and pass through the remaining as array. If it doesn't implement the API, discard it, and check the next item. Repeat until either it finds a component that supports the polymorphicAsArray API, or it gets to the last item in the array, then always render it.
  • Or render a predefined component that supports the polymorphicAsArray API and pass through the as prop to that component untouched.
  • Set the polymorphicAsArray property on the component to true.
  • Implement additional requirements of the API like ref forwarding (not done in the below example).

Note that the PoC npm package exports a helper function polymorphicAsArrayUtil that implements the as array logic.

const PolymorphicComponent = ({ as = 'div', ...props }) => {
  let As;
  let asArray = [];

  if (!Array.isArray(as)) {
    As = as;
  } else {
    asArray = [...as];

    while (asArray.length > 0) {
      const item = asArray.shift();
      if (
        // item implements polymorphicAsArray API
        item?.polymorphicAsArray === true ||
        // item is the last item in the `as` array
        asArray.length === 0
      ) {
        As = item;
        break;
      }
    }
  }

  // component logic...

  // if the asArray is empty, don't pass it through
  const passThroughAsProp = asArray.length === 0 ? undefined : asArray;

  return <As {...props} as={passThroughAsProp} />;
};

PolymorphicComponent.polymorphicAsArray = true;

// usage
// note that ButtonBase is also a polymorphic component
const App = () => (
  <MyPolymorphicComponent as={[ButtonBase, 'a']} href="#polymorphic">
    This renders MyPolymorphicComponent as a ButtonBase as an anchor tag
  </MyPolymorphicComponent>
);

---

Merge two lines of polymorphism with a create function

A create polymorphic function can come in different flavors for different use cases with additional functionality. For example, a styled function that implements the polymorphicAsArray API would be a create function. Also, a create function can optionally support a default props argument (using composition, not the to-be-deprecated defaultProps property).

• A create polymorphic function that implements the polymorphicAsArray API and merges two lines of polymorphism would need to:
  • Accept an as array as the first argument (additional arguments can be supported for specific functionality, e.g. a styles object, default props object, etc).
  • Return a component that:
    • Accepts an array for the as prop.
    • Appends the as prop to the end of the as array argument passed to the create function.
    • Renders the merged as array as describe above in Create multilevel polymorphism (render the first item that supports the polymorphicAsArray API and pass through the remaining array).
    • Has the polymorphicAsArray property set to true.
    • Implements additional requirements of the API like ref forwarding (not done in below example).

Note that the PoC npm package exports a helper function polymorphicAsArrayUtil that implements the as array logic.

const createPolymorphic = (defaultAs = 'div') => {
  const asArray = Array.isArray(defaultAs) ? [...defaultAs] : [defaultAs];

  // polymorphic component that's returned from the create function
  const PolymorphicComponent = ({ as, ...props }) => {
    if (as !== undefined) {
      // append the `as` prop to the end of the `defaultAs` argument
      Array.isArray(as) ? asArray.push(...as) : asArray.push(as);
    }

    // same logic as in the above "Create multilevel polymorphism" example
    let As;
    while (asArray.length > 0) {
      const item = asArray.shift();
      if (
        // item implements polymorphicAsArray API
        item?.polymorphicAsArray === true ||
        // item is the last item in the `as` array
        asArray.length === 0
      ) {
        As = item;
        break;
      }
    }

    const passThroughAsProp = asArray.length === 0 ? undefined : asArray;

    return <As {...props} as={passThroughAsProp} />;
  };

  PolymorphicComponent.polymorphicAsArray = true;
  return PolymorphicComponent;
};

// usage
// note that Interactive is also a polymorphic component
const ButtonBase = createPolymorphic([Interactive, 'button']);

const ButtonLink = createPolymorphic([ButtonBase, 'a']);

const ButtonLinkWithClosedApi = ({ disabled = false, href }) => (
  <ButtonLink
    as={disabled ? 'span' : undefined}
    href={disabled ? undefined : href}
  />
);

---

Related to

• default 'as' in composite component. #444
• How to handle as prop on styled(Component) components #448 (and dupes Wrapping Radix DropdownMenu.Item with styled breaks keyboard navigation #479, Issue composing down as prop #561)
• Enable `as` specification at declaration for composed components #507
• Props is not being passed forward when using composition #583
• Specify props with the `styled` function #590

[jjenzz]

Wow, this is some write up! Thank you 🚀

I'm all for standardising this and coincidentally had also considered exposing a createPolymorphic utility from Radix Primitives. We're having trouble with TS performance and it is starting to seem a bit silly making every single part polymorphic out of the box when consumers might rarely take advantage of it.

This is some quality hacking 😄 but I don't believe it will scale

Haha, it definitely won't! That was just to show how I expected as forwarding to behave but do not recommend anyone puts that into production. It falls over pretty instantly 😅

Accepts an array for the as prop.

I'm intrigued how this idea would be typed with TS. I'm not sure my TS experience stretches far enough to know how to grab prop types of an undefined tuple length.

I'd love to hear some thoughts on the TS side to this all because we have also been discussing this part internally. Performance for polymorphism is not great. Things we have discussed are typing the as prop as string and allowing people to narrow this when needed via an exposed TS utility.

[rafgraph]

Unfortunately I'm not a TS expert, maybe someone in the TS community can help with this? The TypeScript discord has some experts. I'm starting a new project this week, so won't have much time to dedicate to this.

[jonathantneal]

I really like this idea. I think the symbol should be specific to React while unspecific to Radix or Stitches.

A symbol like Symbol.for('react.polymorphic') would fit nicely into the React symbol ecosystem.

Creating a polymorphic symbol:

let polymorphic = Symbol.for('react.polymorphic')

Creating a polymorphic component:

function PolymorphicComponent() {}

PolymorphicComponent[polymorphic] = true

Testing whether a component is polymorphic:

if (PolymorphicComponent[polymorphic]) {
  // component is polymorphic
}

if (polymorphic in PolymorphicComponent) {
  // component is polymorphic
}

Why a symbol? Because symbols are far less likely to collide with keys any other code might add to the object, and because symbols are hidden from mechanisms other code will typically use to access the object, like for-in loops or Object.keys.

[rafgraph]

This looks great to me! I agree a symbol makes more sense than a common property.