React has begun to support the use of webcomponents in an experimental way, this will allow to use custom tag with association of events and more, example:
Advantages: The react team will take care of the coverage of this characteristic.
Disadvantages: (Optional) The maintainer of the component must declare the types of the custom tag.
Although the use of the custom tag is a way of instantiating the component, many times it does not define the import path at the time of its use, complicating the resolution of the component's origin, to avoid this we recommend the use of the Atomico wrapper for React.
Atomico the package @atomic/react allows:
Create a Wrapper component for the custom Element
Avoid react conflicts with webcomponents, such as association of events, attributes, properties and children.
Reflect the types declared in Atomic to React, valid for JSX or TSX
Coverage is automatic if you decide to share your package using @atomico/exports under the following export conditions.
All webcomponents work in Next if it escapes from SSR
Remember if you use the auto
module, it should always be imported first than the customElement to use, otherwise auto
will generate an id as a custom tag to instantiate the component within react
Atomico escapes React DOM immutability logic and moves closer to the native DOM API, this means that Atomico at the scope level is only responsible for receiving the props and rendering the DOM, but it does not observe the internal mutations of the DOM automatically, this is because the native level mutations can come from anywhere, for example other libraries. Now for ensure state synchronization it is convenient that every webcomponent that wants to be observed has the obligation to dispatch a change event
You can easily achieve this by using useEvent or #prop.event, applying that you can:
capture change as event
Force a fixed value
the update
function forces an update on the component, in order to redefine value according to the scope
Atomico inherits part of the React syntax and applies it to webcomponents, with a closer to standard approach.
Atomico will not limit your React learning curve, what you learned in Atomico is applicable in React, for example hooks and virtualDOM.
Atomico is 3kB in size which is 7% of React + React-dom.
Better component abstraction, for example the use of the ShadowDOM will avoid the need to use css-in-js like styles-components or emotion, reducing dependencies.
Agnostic Components, what you create with React only works within React, what you create with Atomico works on the web, so you can use your components within React, Vue, Svelte or Html.
Exclusive component for React, the CLI @ atomico / exports automatically generates a wrapper component of your webcomponent for React, improving backward compatibility with React.
The following examples show some differences between React and Atomico.
From the example we will highlight the following differences:
In Atomico you only use one import.
useProp
is like useState
, but with the difference that useProp references the state from the webcomponent property defined in counter.props
.
counter.props
allows us to create the properties of our webcomponent, these are like React's propTypes, but with a big difference they are associated with the instance and can be read and modified by referencing the node, example document.querySelector("my-counter").count = 10;
ReactDom.render
needs a reference to mount the component, in Atomico you only need to create the my-counter
tag to create a new instance of the component.
The <host/>
tag is similar to <> </>
for React, but <host/>
represents the webcomponent instance and every component created with Atomico must return the host tag
This is only readability, but in Atomico by convention we do not use capital letters when naming our component, these are only used when creating the customElement as in line 16, since Counter
is instantiable.
From the example we will highlight the following differences:
The hook api is the same.
the component in Atomico returns the `<host/>
tag.
In Atomico you will have the most useful React hooks such as:
useRef
useState
useReducer
useLayoutEffect
useEffect
useMemo
useCallback
useContext : Not supported, event api is better practice than context when using webcomponents, example useChannel****
It is common to see the use of libraries such as Emotion or styled-components to encapsulate styles in React, but these add an additional cost, be it for performance or bundle, in Atomico there is no such cost.
Atomico integrates very easily into React, either using @atomico/exports or @atomico/react.
CLI that decorates the package.json according to the code to be exported in order to share your code optimally. By using the --wrappers flag the CLI will detect the export of webcomponents and automatically create a wrapper for React, Preact and Vue.
You can learn more about @atomico/exports in the following guide:
With this package you will be able to create wrappers for your Webcomponents in React, even managing to make SSR of your webcomponents in environments like Next.js with these wrappers.
You can learn more about @atomico/react in the following guide:
Guide that defines some differences that exist between Atomico and React when working with the DOM.
Atomico's virtualDOM is:
Close to standard DOM .
Additional coverage to webcomponents.
Atomico does not support the use of functions to instantiate the component as we traditionally do in React, so that the component can be instantiated as a constructor it must be a webcomponent or a real Node.
Like React in Atomico you need to use the prefix on to announce an event, but there is a difference Atomico does not manipulate the name of the event so onClick
is different from onclick
, the purpose of this difference is to support custom events.
the key
property in Atomicoo can be of type String, Number, Symbol or other immutable reference.