volland/reactshadow

:beginner: Utilise Shadow DOM in React with all the benefits of style encapsulation.

Utilise Shadow DOM in React with all the benefits of style encapsulation.

     

• npm: npm i react-shadow
• yarn: yarn add react-shadow
• Heroku: http://react-shadow.herokuapp.com/

---

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']
}

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.string),
    children: PropTypes.node.isRequired,
};

ShadowRoot.defaultProps = {
    mode: 'open',
    delegatesFocus: false,
    styleSheets: [],
};

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} />