|
1 | | -# poly |
| 1 | +# @polymorphic-factory/react |
| 2 | + |
| 3 | +Create polymorphic React components with a customizable `styled` function. |
| 4 | + |
| 5 | +A polymorphic component is a component that can be rendered with a different element. |
| 6 | + |
| 7 | +> **Known drawbacks for the type definitions:** |
| 8 | +> |
| 9 | +> Event handlers are not typed correctly when using the `as` prop. |
| 10 | +> |
| 11 | +> This is a deliberate decision to keep the usage as simple as possible. |
| 12 | +
|
| 13 | +## Installation |
| 14 | + |
| 15 | +```bash |
| 16 | +npm install @polymorphic-factory/react |
| 17 | +``` |
| 18 | + |
| 19 | +or |
| 20 | + |
| 21 | +```bash |
| 22 | +yarn add @polymorphic-factory/react |
| 23 | +``` |
| 24 | + |
| 25 | +or |
| 26 | + |
| 27 | +```bash |
| 28 | +pnpm install @polymorphic-factory/react |
| 29 | +``` |
| 30 | + |
| 31 | +## Usage |
| 32 | + |
| 33 | +Import the polymorphic factory and create your element factory. |
| 34 | + |
| 35 | +```ts |
| 36 | +import { polymorphicFactory } from '@polymorphic-factory/react' |
| 37 | +const poly = polymorphicFactory() |
| 38 | +``` |
| 39 | + |
| 40 | +### Custom `styled` function |
| 41 | + |
| 42 | +You can override the default implementation by passing `styled` function in the options. |
| 43 | + |
| 44 | +```tsx |
| 45 | +const poly = polymorphicFactory({ |
| 46 | + styled: (component, options) => (props) => { |
| 47 | + const Component = props.as || component |
| 48 | + return <Component data-custom-styled data-options={JSON.stringify(options)} {...props} /> |
| 49 | + }, |
| 50 | +}) |
| 51 | + |
| 52 | +const App = () => { |
| 53 | + return <poly.div hello="world" /> |
| 54 | + // renders <div data-custom-styled data-options="{ \"hello\": \"world\" }" /> |
| 55 | +} |
| 56 | +``` |
| 57 | + |
| 58 | +### Inline |
| 59 | + |
| 60 | +Use the element factory to create elements inline. |
| 61 | +Every JSX element is supported `div`, `main`, `aside`, etc. |
| 62 | + |
| 63 | +```tsx |
| 64 | +<> |
| 65 | + <poly.div /> |
| 66 | + <poly.main> |
| 67 | + <poly.section> |
| 68 | + <poly.div as="p">This is rendered as a p element</poly.div> |
| 69 | + </poly.section> |
| 70 | + </poly.main> |
| 71 | +</> |
| 72 | +``` |
| 73 | + |
| 74 | +### Factory |
| 75 | + |
| 76 | +Use the factory to wrap custom components. |
| 77 | + |
| 78 | +```tsx |
| 79 | +const OriginalComponent = (props) => <div data-original="true" {...props}></div> |
| 80 | +const MyComponent = poly(OriginalComponent) |
| 81 | + |
| 82 | +const App = () => <MyComponent /> |
| 83 | +// render <div data-original="true" /> |
| 84 | +``` |
| 85 | + |
| 86 | +It still supports the `as` prop, which would replace the `OriginalComponent`. |
| 87 | + |
| 88 | +```tsx |
| 89 | +<MyComponent as="div" /> |
| 90 | +// renders <div /> |
| 91 | +``` |
| 92 | + |
| 93 | +## Types |
| 94 | + |
| 95 | +```ts |
| 96 | +import type { HTMLPolymorphicComponents, HTMLPolymorphicProps } from '@polymorphic-factory/react' |
| 97 | + |
| 98 | +type PolymorphicDiv = HTMLPolymorphicComponents['div'] |
| 99 | +type DivProps = HTMLPolymorphicProps<'div'> |
| 100 | +``` |
| 101 | +
|
| 102 | +## License |
| 103 | +
|
| 104 | +MIT © [Tim Kolberger](https://github.com/timkolberger) |
0 commit comments