|
1 | | - |
| 1 | +This package is forked from [ReactShadow](https://github.com/Wildhoney/ReactShadow)@19.0.3, with only one modification to the original project: adding react 18 to the peer dependency. |
2 | 2 |
|
3 | | -> Utilise Shadow DOM in React with all the benefits of style encapsulation. |
4 | | -
|
5 | | - |
6 | | - |
7 | | - |
8 | | - |
9 | | - |
10 | | - |
11 | | - |
12 | | - |
13 | | -- **npm**: `npm i react-shadow` |
14 | | -- **yarn**: `yarn add react-shadow` |
15 | | -- **Heroku**: [https://react-shadow.herokuapp.com/](https://react-shadow.herokuapp.com) ([alternative](https://react-shadow-2.herokuapp.com)) |
16 | | - |
17 | | - |
18 | | - |
19 | | ---- |
20 | | - |
21 | | -## Getting Started |
22 | | - |
23 | | -Creating the [shadow root](https://www.w3.org/TR/shadow-dom/) is as simple as using the default export to construct a shadow root using the node name provided – for example `root.div` would create a `div` as the host element, and a shadow root as its immediate descendant — all of the child elements would then be descendants of the shadow boundary. |
24 | | - |
25 | | -```jsx |
26 | | -import root from 'react-shadow'; |
27 | | -import styles from './styles.css'; |
28 | | - |
29 | | -export default function Quote() { |
30 | | - return ( |
31 | | - <root.div className="quote"> |
32 | | - <q>There is strong shadow where there is much light.</q> |
33 | | - <span className="author">― Johann Wolfgang von Goethe.</span> |
34 | | - <style type="text/css">{styles}</style> |
35 | | - </root.div> |
36 | | - ); |
37 | | -} |
38 | | -``` |
39 | | - |
40 | | -[](https://codesandbox.io/s/react-shadow-by6bo?fontsize=14) |
41 | | - |
42 | | -Applying styles requires either applying the styles directly to the component as a string, or importing the CSS documents as a string as part of your build process. You can then append the `style` component directly to your shadow boundary via your component's tree. In [the example](https://github.com/Wildhoney/ReactShadow/tree/master/example) we use the following Webpack configuration to import CSS documents as strings. |
43 | | - |
44 | | -```javascript |
45 | | -{ |
46 | | - test: /\.css$/, |
47 | | - loader: ['to-string-loader', 'css-loader'] |
48 | | -} |
49 | | -``` |
50 | | - |
51 | | -Alternatively you can use [`styled-components`](https://www.styled-components.com/) normally, as each time a shadow boundary is created, a new `StyleSheetManager` context is also created which will encapsulate all related styles in their corresponding shadow root — to use this `import react-shadow/styled-components` instead of `import react-shadow`, likewise if you'd like to use [`emotion`](https://emotion.sh/docs/styled) you can `import react-shadow/emotion`. |
52 | | - |
53 | | -```javascript |
54 | | -import root from 'react-shadow/styled-components'; |
55 | | -import root from 'react-shadow/emotion'; |
56 | | - |
57 | | -// ... |
58 | | - |
59 | | -<root.section />; |
60 | | -``` |
61 | | - |
62 | | -You may pass any props you like to the `root.*` component which will be applied directly to the host element, including event handlers and class names. There are also a handful of options that are used for the `attachShadow` invocation. |
63 | | - |
64 | | -```javascript |
65 | | -ShadowRoot.propTypes = { |
66 | | - mode: PropTypes.oneOf(['open', 'closed']), |
67 | | - delegatesFocus: PropTypes.bool, |
68 | | - styleSheets: PropTypes.arrayOf( |
69 | | - PropTypes.instanceOf(globalThis.CSSStyleSheet), |
70 | | - ), |
71 | | - children: PropTypes.node, |
72 | | -}; |
73 | | - |
74 | | -ShadowRoot.defaultProps = { |
75 | | - mode: 'open', |
76 | | - delegatesFocus: false, |
77 | | - styleSheets: [], |
78 | | - children: null, |
79 | | -}; |
80 | | -``` |
81 | | - |
82 | | -In cases where you need the underlying element and its associated shadow boundary, you can use a standard `ref` which will be invoked with the host element – from that you can use `shadowRoot` to access its shadow root if the `mode` has been set to the default `open` value. |
83 | | - |
84 | | -```javascript |
85 | | -const node = useRef(null); |
86 | | - |
87 | | -// ... |
88 | | - |
89 | | -<root.section ref={node} />; |
90 | | -``` |
91 | | - |
92 | | -Recently and at long last there has been some movement in introducing a [declarative shadow DOM](https://tomalec.github.io/declarative-shadow-dom/) which `react-shadow` _tentatively_ supports – as it's experimental, open to sudden spec changes, and React finds it difficult to rehydrate – by using the `ssr` prop. |
93 | | - |
94 | | -```javascript |
95 | | -const node = useRef(null); |
96 | | - |
97 | | -// ... |
98 | | - |
99 | | -<root.section ssr />; |
100 | | -``` |
| 3 | +If, like me, you [get an `ERESOLVE unable to resolve dependency tree error` when installing react-shadow using npm](https://github.com/Wildhoney/ReactShadow/pull/140#issuecomment-1326663553), then you can install this package instead. |
0 commit comments