react-shadow
v20.5.0
Published
Utilise Shadow DOM in React with all the benefits of style encapsulation.
Downloads
309,104
Readme
Utilise Shadow DOM in React with all the benefits of style encapsulation.
- npm:
npm i react-shadow
- yarn:
yarn add react-shadow
- Heroku: https://react-shadow.herokuapp.com/ (alternative)
Getting Started
Creating the shadow root 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.
import root from 'react-shadow';
import styles from './styles.css';
export default function Quote() {
return (
<root.div className="quote">
<q>There is strong shadow where there is much light.</q>
<span className="author">― Johann Wolfgang von Goethe.</span>
<style type="text/css">{styles}</style>
</root.div>
);
}
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 we use the following Webpack configuration to import CSS documents as strings.
{
test: /\.css$/,
loader: ['to-string-loader', 'css-loader']
}
Alternatively you can use styled-components
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
you can import react-shadow/emotion
.
import root from 'react-shadow/styled-components';
import root from 'react-shadow/emotion';
// ...
<root.section />;
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.
ShadowRoot.propTypes = {
mode: PropTypes.oneOf(['open', 'closed']),
delegatesFocus: PropTypes.bool,
styleSheets: PropTypes.arrayOf(
PropTypes.instanceOf(globalThis.CSSStyleSheet),
),
children: PropTypes.node,
};
ShadowRoot.defaultProps = {
mode: 'open',
delegatesFocus: false,
styleSheets: [],
children: null,
};
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.
const node = useRef(null);
// ...
<root.section ref={node} />;
Recently and at long last there has been some movement in introducing a 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.
const node = useRef(null);
// ...
<root.section ssr />;