10000 GitHub - ahutchings/react-polymorphic-box: Building blocks for strongly typed polymorphic components in React.
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Building blocks for strongly typed polymorphic components in React.

License

Notifications You must be signed in to change notification settings

ahutchings/react-polymorphic-box

 
 

Repository files navigation

react-polymorphic-box

Building blocks for strongly typed polymorphic components in React.

npm Language grade: JavaScript Travis (.com) Commitizen friendly

Animated demonstration of package capabilities

💡 Motivation

Popularized by Styled Components v4, the as prop allows changing the HTML tag rendered by a component, e.g.:

import { Box } from 'react-polymorphic-box';
import { Link } from 'react-router-dom';

<Box as="a" href="https://github.com/kripod">GitHub</Box>
<Box as={Link} to="/about">About</Box>

While this pattern has been encouraged by several libraries, typings had lacked support for polymorphism, missing benefits like:

  • Automatic code completion, based on the value of the as prop
  • Static type checking against the associated component's inferred props
  • HTML element name validation

📚 Usage

A Heading component can demonstrate the effectiveness of polymorphism:

<Heading color="rebeccapurple">Heading</Heading>
<Heading as="h3">Subheading</Heading>

Custom components like the previous one may utilize the package as shown below.

import * as React from 'react';
import { Box, PolymorphicComponentProps } from 'react-polymorphic-box';

// Component-specific props should be specified separately
export interface HeadingOwnProps {
  color?: string;
}

// Merge own props with others inherited from the underlying element type
export type HeadingProps<
  E extends React.ElementType
> = PolymorphicComponentProps<E, HeadingOwnProps>;

// An HTML tag or a different React component can be rendered by default
const defaultElement = 'h2';

export function Heading<E extends React.ElementType = typeof defaultElement>({
  color,
  style,
  ...restProps
}: HeadingProps<E>): JSX.Element {
  // The `as` prop may be overridden by the passed props
  return <Box as={defaultElement} style={{ color, ...style }} {...restProps} />;
}

Typing external components

Alternatively, you can also type your custom components by using the PolymorphicComponent type. This is especially handy when working with external libraries that already expose polymorphic components. Here's an example implementing the Heading component from above using styled-components:

import { PolymorphicComponent } from 'react-polymorphic-box';
import styled from 'styled-components';

// Component-specific props
interface HeadingProps {
  color?: string;
}

// An HTML tag or a different React component can be rendered by default
const defaultElement = 'h2';

const Heading: PolymorphicComponent<
  HeadingProps, // Merged with props from the underlying element type
  typeof defaultElement // Default element type (optional, defaults to 'div')
> = styled(defaultElement)<HeadingProps>`
  color: ${(props) => props.color};
`;

Forwarding Refs

Library authors should consider encapsulating reusable components, passing a ref through each of them:

import * as React from 'react';
import { Box } from 'react-polymorphic-box';

export const Heading = React.forwardRef(
  <E extends React.ElementType = typeof defaultElement>(
    { ref, color, style, ...restProps }: HeadingProps<E>,
    innerRef: typeof ref,
  ) => {
    return (
      <Box
        ref={innerRef}
        as={defaultElement}
        style={{ color, ...style }}
        {...restProps}
      />
    );
  },
) as <E extends React.ElementType = typeof defaultElement>(
  props: HeadingProps<E>,
) => JSX.Element;

About

Building blocks for strongly typed polymorphic components in React.

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published

Languages

  • TypeScript 100.0%
0