Provides an enhanced version of "React.forwardRef" to polymorph using the "as" prop.
npm install react-polymorphic-forwardrefThis package is heavily inspired by react-polymorphed and addresses changes introduced in TypeScript version 5.x.x.
In addition to supporting polymorphism with native HTML elements, it also enables polymorphing into existing polymorphic components.
- Basic Usage
- Automatically receive native HTML prop typings
- Polymorphing into Another Polymorphic Component
``tsx
import { forwardRefAs } from 'react-polymorphic-forwardref'
interface MyPolymorphicComponentProps {
text: string
}
const MyPolymorphicComponent = forwardRefAs<'div', MyPolymorphicComponentProps>((props, ref) => {
const {as, text} = props;
const Component = as || 'div';
return
});
export const App = () => {
return (
text='Click me'
onClick={(e) => alert('The type of "e" is automatically recognized as "React.MouseEvent
/>
);
}
App();
`
On the above example, MyPolymorphicComponent uses div element by default for render, inheriting all native HTML attributes for a div.
Let's consider onClick method and its typing. onClick method provides an e parameter, which is typed based on the HTML element it is assigned to. If the polymorped component is a div element,Typescript
then recognizes the default type of e as React.MouseEvent.
`tsx
// "e" receives its typing automatically as "React.MouseEvent
onClick={(e) => alert('"e" typing is "React.MouseEvent
/>
// ERROR: HTMLAnchorElement is not valid, since by default, it needs to be HTMLDivElement
onClick={(e: React.MouseEvent
/>
`
Since this is a polymorphic component, its HTML element render can be modified based on where the component is consumed.
Let's say that we would like to polymorph this component into an Anchor (a) tag. We can accomplish this by simply providing the as prop to the component. Once we provide as="a", we expect 2
things to happen:
- The e parameter of onClick should now be redefined based on the HTMLAnchorElement, effectively typing it as React.MouseEvent.HTMLAnchorElement
- Native properties should be immediately available, such as href and target.
`tsx`
text='I am an "a" element now'
// Typescript will recognize the typings for "href" and "target"
href="#"
target="_blank"
onClick={(e) => alert('Yeap, you guessed it right, "e" typing is "React.MouseEvent
/>
What if we were polymorphing into another polymorphic component? In this case, the polymorphed component should inherit all the props of the polymorphed component, including the native properties of
the default HTML element and the explicitly defined props.
Let's build another polymorphic component, to be later polymorphed into MyPolymorphicComponent
`tsx
import { forwardRefAs } from 'react-polymorphic-forwardref'
interface AnotherPolymorphicComponentProps {
anotherText: string
}
const AnotherPolymorphicComponent = forwardRefAs<'a', AnotherPolymorphicComponentProps>((props, ref) => {
const {anotherText} = props
return
If this component is rendered without polymorphing, it would automatically receive the
Anchor element related native HTML props, as well as anotherText prop, which is required.`tsx
// "anotherText" is an explicity defined prop
anotherText='I am a prop of "AnotherPolymorphicComponent'
// "e" typing will inherit the default HTML element of "AnotherPolymorphicComponent", which is an "a" tag.
// Hence, its type will be "React.MouseEvent"
onClick={(e) => alert('"e" type is React.MouseEvent')}
/>
`Now let's polymorph
AnotherPolymorphicComponent into MyPolymorphicComponent.-
AnotherPolymorphicComponent is going to inherit all the properties of MyPolymorphicComponent, including the text prop and the native HTML attributes for the default HTML element of
MyPolymorphicComponent.
- anotherText prop that is required for AnotherPolymorphicComponent will be added on top of the inherited props.`tsx
as={MyPolymorphicComponent}
// "text" prop is enherited, since it is a required prop of MyPolymorphicComponent
text='I am a prop that is automatically inherited'
anotherText='I am a prop of "AnotherPolymorphicComponent'
// "e" typing will inherit the default HTML element of "MyPolymorphicComponent", which is a "div" tag.
// Hence, its type will be "React.MouseEvent"
onClick={(e) => alert('"e" type is React.MouseEvent')}
/>
``