If you develop with React, you will know 80% Atomico ... now why use Atomico?:

1. Atomico will not limit your React learning curve, what you learned in Atomico is applicable in React, for example hooks and virtualDOM.

2. Atomico is 3kB in size which is 7% of React + React-dom.

3. 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.

4. 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.

5. 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.

Counter example

import { useState } from "react";
import ReactDOM from 'react-dom'

function Counter({initialCount}) {
  const [count, setCount] = useState(initialCount);
  return (
    <>
      Count: {count}
      <button onClick={() => setCount(initialCount)}>Reset</button>
      <button onClick={() => setCount(prevCount => prevCount - 1)}>-</button>
      <button onClick={() => setCount(prevCount => prevCount + 1)}>+</button>
    </>
  );
}


render(
  <Counter initialCount={1}/>, 
  document.querySelector("#counter")
);

import { c, useProp } from "atomico";

function counter() {
  const [count, setCount] = useProp("count");
  return (
    <host>
      Count: {count}
      <button onClick={() => setCount(prevCount => prevCount - 1)}>-</button>
      <button onClick={() => setCount(prevCount => prevCount + 1)}>+</button>
    </host>
  );
}

counter.props = { count: { type: Number, value: 0 } }

const Counter = c(counter);

customElements.define(
  "my-counter",
  Counter  
);

From the example we will highlight the following differences:

1. In Atomico you only use one import.

2. useProp is like useState, but with the difference that useProp references the state from the webcomponent property defined in counter.props.

3. 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;

4. 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.

5. 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

6. 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.

CustomHooks example

import { useEffect, useState } from "react";

function useJsonPlaceholder(path) {
  const [state, setState] = useState();
  useEffect(() => {
    let cancel;
    setState(null);
    fetch(`https://jsonplaceholder.typicode.com/${path}`)
      .then(() => res.json())
      .then((data) => !cancel && setState( data ));
    return () => (cancel = true);
  }, [path]);
}

function Component() {
  const posts = useJsonPlaceholder("posts");
  return (
    <>
      {posts 
        ? posts.map(({ title }) => <h1>{title}</h1>)
        : "Loading..."}
    </>
  );
}

import { useEffect, useState } from "atomico";

function useJsonPlaceholder(path) {
  const [state, setState] = useState();
  useEffect(() => {
    let cancel;
    setState(null);
    fetch(`https://jsonplaceholder.typicode.com/${path}`)
      .then(() => res.json())
      .then((data) => !cancel && setState( data ));
    return () => (cancel = true);
  }, [path]);
}

function component() {
  const posts = useJsonPlaceholder("posts");
  return (
    <host>
      {posts 
        ? posts.map(({ title }) => <h1>{title}</h1>)
        : "Loading..."}
    </host>
  );
}

From the example we will highlight the following differences:

1. The hook api is the same.

2. the component in Atomico returns the `<host/> tag.

Supported hooks

In Atomico you will have the most useful React hooks such as:

1. useRef

2. useState

3. useReducer

4. useLayoutEffect

5. useEffect

6. useMemo

7. useCallback

8. useContext : Not supported, event api is better practice than context when using webcomponents, example useChannel****

CSS-in-JS

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.

const Button = styled.a`
  /* This renders the buttons above... Edit me! */
  display: inline-block;
  border-radius: 3px;
  padding: 0.5rem 0;
  margin: 0.5rem 1rem;
  width: 11rem;
  background: transparent;
  color: white;
  border: 2px solid white;

  /* The GitHub button is a primary button
   * edit this to target it specifically! */
  ${props => props.primary && css`
    background: white;
    color: black;
  `}
`

render(
  <div>
    <Button
      href="https://github.com/styled-components/styled-components"
      target="_blank"
      rel="noopener"
      primary
    >
      GitHub
    </Button>

    <Button as={Link} href="/docs">
      Documentation
    </Button>
  </div>
)

import { c, css } from "atomico";

function button() {
  return <host shadowDom><slot/></host>;
}

button.props = { primary: { type: Boolean, relfect: true } };

button.styles = css`
  :host {
    display: inline-block;
    border-radius: 3px;
    padding: 0.5rem 0;
    margin: 0.5rem 1rem;
    width: 11rem;
    background: transparent;
    color: white;
    border: 2px solid white;
  }

  :host([primary]) {
    background: white;
    color: black;
  }
`;

export const Button = c(button);

React and webcomponents

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:

import React from "react";
import "@formilk/components";

export default function App() {
  return (
    <fm-button>Click!<fm-button>
  );
}

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 wrapper for React

Atomico the package @atomic/react allows:

1. Create a Wrapper component for the custom Element

2. Avoid react conflicts with webcomponents, such as association of events, attributes, properties and children.

3. 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.

Atomico inside Next.js

All webcomponents work in Next if it escapes from SSR

Example of custom tag usage

import  "@formilk/components/button";

export default function Home() {
  return (
    <div>
      <fm-button name="Matias">
        <h1>Hello Next.js</h1>
      </fm-button>
    </div>
  );
}

Example of use of the wrapper.

import dynamic from "next/dynamic";

const Button = dynamic(() => import("./wrapper-button.js"), {
  ssr: false,
});

export default function Home() {
  return (
    <div>
      <Button  name="Matias">
        <h1>Hello Next.js</h1>
      </Button>
    </div>
  );
}

import { auto } from "@atomico/react/auto";
import { Button } from "@formilk/components/button";

export default auto(Button);

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

const [ value, setValue ] = useState("init"); // you can also use useProp

<host>
    <my-component 
        value={value} 
        onchange={({target})=>setValue(target.value)}
    ></my-component>
</host>

Force a fixed value

const update = useUpdate();

<host>
    <my-component 
        value={value} 
        onchange={update}></my-component>
</host>

the update function forces an update on the component, in order to redefine value according to the scope

Atomico's virtualDOM is:

1. Close to standard DOM .

2. Additional coverage to webcomponents.

Components as constructors

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.

function Component(){
    const [ state, setState ] = useState();
    return <host></host>
}

function App(){
    return <host>
        <Component/>
    </host>
}

// ⚠️ stateless component
function Component(){ 
    return <host></host>
}

function App(){
    return <host>
        <Component/>
    </host>
}

function component(){
    return <host></host>
}

const Component = c(component);
customElements.define("my-component",Component)

function app(){
    return <host>
        <Component/>
    </host>
}

function app(){
    const Div = document.createElement("div");
    return <host>
        <Image/>
        <Div/>
    </host>
}

Event Association

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.

<div>
    <button onclick={console.log}>click</button>
    <button onMyCustomEvent={console.log}>click</button>
    <button onmy-event={console.log}>click</button>
    <button onmouseover={console.log}>click</button>
</div>

Keyes

the key property in Atomicoo can be of type String, Number, Symbol or other immutable reference.

<div>
    <div key={1}>1</div>
    <div key={symbol}>1</div>
    <div key={immutable}>1</div>
</div>

dangerouslySetInnerHTML

<div innerHTML={`<h1>html!</h1>`}/>

Atomico integrates very easily into React, either using or .

@atomico/exports

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 in the following guide:

@atomico/react

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 in the following guide: