With Polymorphic

With Polymorphic (with-polymorphic) is a Higher Order Component for React that enables polymorphic prop patterns. This library is written in TypeScript to provide a well-typed experience.

Table of Contents

• Why Use With Polymorphic?
• Installation
• Usage
• Examples
• Usage with ForwardRef
• Bug Report
• Contributing
• License

Why Use With Polymorphic?

• Type Safety: The library is written in TypeScript, ensuring a well-typed usage.
• Flexibility: With polymorphic prop patterns, you can create versatile components that can behave differently based on the passed props.
• Easy Integration: It's a Higher Order Component that can be easily wrapped around your existing components.

Installation

You can install With Polymorphic (with-polymorphic) in your project using npm:

npm install with-polymorphic

Alternatively, you can use yarn:

yarn add with-polymorphic

Usage

Here's an example illustrating how withPolymorphic can be used:

import React from 'react';
import withPolymorphic from 'with-polymorphic';

interface PolymorphicComponentProps {
  children: React.ReactNode;
  as?: React.ElementType;
}

const PolymorphicComponent = withPolymorphic<'div', PolymorphicComponentProps>(
  ({ as: Component = 'div', children, ...restProps }) => (
    <Component {...restProps}>{children}</Component>
  )
);

Examples

Here are some examples demonstrating both correct and incorrect prop assignments.

Correct Prop Assignment

No additional props assigned. Component will render as expected.

export function CorrectComponent() {
  return <PolymorphicComponent>Polymorphic Component</PolymorphicComponent>;
}

"as" prop set to "a" and "href" prop set to "/example" to render the component as a link.

export function CorrectComponent() {
  return (
    <PolymorphicComponent as="a" href="/example">
      Polymorphic Component
    </PolymorphicComponent>
  );
}

Incorrect Prop Assignment

The component does not handle or recognize the "href" prop, leading to unexpected behavior or errors.

export function IncorrectComponent() {
  return (
    <PolymorphicComponent href="/example">
      Polymorphic Component
    </PolymorphicComponent>
  );
}

The component does not expect the "foo" prop, which may be ignored or cause errors.

export function IncorrectComponent() {
  return (
    <PolymorphicComponent foo="bar">Polymorphic Component</PolymorphicComponent>
  );
}

Usage with ForwardRef

Here's an example demonstrating the usage of withPolymorphic with forwardRef:

import React, { forwardRef } from 'react';
import withPolymorphic from 'with-polymorphic';

interface PolymorphicComponentProps {
  children: React.ReactNode;
  as?: React.ElementType;
}

const PolymorphicComponentWithRef = withPolymorphic<'div', PolymorphicComponentProps>(
  forwardRef<HTMLDivElement, PolymorphicComponentProps>(
    ({ as: Component = 'div', children, ...restProps }, ref) => (
      <Component ref={ref} {...restProps}>{children}</Component>
    )
  )
);

Bug Report

If you encounter any bugs or issues, please report them through the Issues section of our GitHub repository. When reporting an issue, please include as much information as possible, such as the version of the library you're using, what you expected to happen, what actually happened, and steps to reproduce the issue.

Contributing

We welcome contributions to With Polymorphic (with-polymorphic)! If you're interested in contributing, please fork the repository and submit a pull request. If you're not sure where to start, take a look at the open Issues or feel free to submit new ones.

Before submitting a pull request, please make sure that your changes are well-documented and include appropriate test coverage. For more detailed information on contributing, see the CONTRIBUTING.md file.

License

With Polymorphic (with-polymorphic) is licensed under the MIT License.