Many teams decide to use Atomico for the development of their design systems thanks to its similarity with React, which greatly facilitates the incorporation of human talent into the development of design systems.

Why use Atomico to create design systems?

1. Atomico offers you Storybook 7 Support with superpowers, thanks to you can create stories without the need to declare the argTypes or args since creates them for you

2. makes it easy for you to build in NPM-friendly ESM format

3. makes it easy for you to export your code by automatically adding the metadata so that it is optimally consumed as a package, @atomico/exports can even automatically create wrappers for React, Preact and Vue

4. makes it easy for you to maintain a token system efficiently and sustainably

Use cases

IBM IX

We thank IBM IX since they have shared their experience in the development of the design system for their client Barmer, you can follow this case through Discord or Github.

Thanks for being here and getting started with Atomico. Let's talk a little about what Atomico offers today:

1. Development agility, Atomico's functional approach simplifies code at all stages of development.

2. Lightweight inside and out, Atomico allows you to create a component with less code and with a low dependency impact. Approximately 3kb.

3. Really fast, Atomico has a in the browser and an agile development experience. Let's understand what a webcomponent created with Atomico looks like:

Let's analyze the code in parts ...

1.0 Imports

What have we imported?

1. c: Function that transforms the functional component into a standard customElement.

2. css: Function that allows creating the CSSStyleSheet (CSS) for our component as long as it declares the shadowDom.

2.0 Creating Our Web Component: Custom Element Definition

2.1 Defining Component Render Function

Our function receives all the props (Properties and Attributes) declared in props, the component function declares all the logic and template of the webcomponent. An important rule within Atomico is "📌 every component created with Atomico must always return the tag".

2.2 Defining Component Properties(props) and Attributes

Atomico detects the prop (Properties and Attributes) of the component thanks to the association of the props object, this through the use of index and value allows you to define:

1. index: Name of the property and attribute.

2. value: type of the prop.

From the example we can infer that Atomico will create in our webcomponent a property and attribute called message and this can only receive values of the String type.

2.3 Defining Encapsulated Styles for the Component

Atomico detects the static styles of your component thanks to the association of the styles property:

styles accepts individual or list CSSStyleSheet (CSS) values, the return from the css function is a standard CSSStyleSheet, so it can be shared outside of Atomico.

Web Component Registration and Definition

To create our standard customElement we will have to deliver our functional component to the c function of the Atomico module, the c function will generate as a return a customElement that can be defined or extended.

Example

import { c } from "atomico";

import { c } from "atomico";

Atomico simplifies learning, workflow and maintenance when creating webcomponents and achieves it with:

1. Scalable and reusable interfaces: with Atomico the code is simpler and you can apply practices that facilitate the reuse of your code.

2. Open communication: with Atomico you can communicate states by events, properties or methods.

3. Agnostic: your custom Element will work in any web-compatible library, eg React, Vue, Svelte or Angular.

4. Performance: Atomico has a comparative performance at Svelte levels, winning the third position in performance according to in a comparison of 55 libraries among which is React, Vue, Stencil and Lit.

API

Props is the Atomico recommended way to declare visible and accessible states at the instance level of your webcomponents, with props you can:

1. Access state via instance, example: document.querySelector("my-component").myStateProp.

2. Dispatch events on prop value change, example: document.querySelector("my-component").addEventListener("myPropChange",console.log)

First let's say that Atomico is light since it has a size close to 3kB vs React + ReactDOM that have a size close to 60kB, now if your project is already written in React I can integrate Atomico progressively since a component created can be instantiated as a component for React thanks to , example:

Magical 🪄, isn't it?... well now let's speed up your Atomico learning path:

How to declare a component?

Syntax

Where:

• dispatchEvent: callback, dispatches the event from the webcomponent and allows defining the detail by receiving a first parameter

Syntax

JSX

Atomico supports jsx-runtime

useProp allows you to work with a prop(property) of the webcomponent in a similar way to useState.

Syntax

Where :

Hooks only for webcomponents

Hooks homogolates of React

Syntax

Example

Special properties

Syntax

Returns the instance of the webcomponent in reference format, this reference allows to extend behaviors when creating customHooks.

Syntax

const [state, setState] = useState(optionalInitialState);

Where:

1. const [state,setState] : Return of useState, the arguments allow reading and updating of the state associated with the hook instance.

   • state : Current state.

   • setState: Current status updater.

2. useState( optionalInitialState ): Function that associates the state to the webcomponent:

   • optionalInitialState: Optional parameter that defines the initial state associated to the hook instance, If optionalInitialState is a function it will be executed in order to obtain the initial state only at the moment of the hook instance for the first time.

Example

Syntax

const memoValue = useMemo(callback, optionalArgumentList);

Where :

1. memoValue : Return memorized by useMemo.

2. callback: Function that is executed one or more times according to optionalArgumentList.

3. optionalArgumentList: Array of arguments that controls the execution of callback, if an argument of optionalArgumentList changes it will trigger that callback is executed again.

useCallback

Hook that allows you to memorize a callback so that it keeps its scope

Where:

1. memoCallback : Return memorized by useCallback.

Syntax

useEffect(effectCallback, optionalArgumentList);

Where :

1. effectCallback : Function that is executed one or more times according to optionalArgumentList,effectCallback can return a function that will be executed only if effectCallback is executed again or the webcomponent is unmounted.

2. optionalArgumentList: Array of arguments that controls the execution of effectCallback, if an argument ofoptionalArgumentList changes it will trigger that effectCallback is executed again without first cleaning the effects subscribed by the previous execution.

Example

useLayoutEffect

useLayoutEffect replicates the logic of useEffect but with synchronous execution after rendering.

useInsertionEffect

useLayoutEffect replicates the logic of useEffect but with synchronous execution before rendering.

It is normal that the state of your component depends on the references of a slot, this hook facilitates the process of observing these references without the need to associate the changes to a state.

Syntax

Where:

useId is a Atomico Hook for generating unique IDs that can be passed to accessibility attributes.

Syntax

import { useId } from "atomico";

const stringId = useId();

Example

Use ID generate a unique ID for each component, this id can be useful for referencing CSS selectors or creating names for inputs that only the component knows about.

This hook enables you to take control of the context from the component that instantiates useProvider, thus avoiding the need to instantiate the context node in the DOM.

Example of the useProvider hook:

import { createContext, useProvider, c } from "atomico";

export const Theme = createContext({
    color: "white",
    background: "black"
});

export const App = c(()=>{
    useProvider(Theme,{
        color: "red",
        background: "yellow"
    });
    
    return <host shadowDom><slot/></host>
});

Objective

Avoid creating an instantiable context node in the DOM.

With the new contexts API you will be able to easily communicate components without the need to handle events, by default the communication is top down, but through it you can share anything as long as it is defined as an object.

Atomico's api is similar to React's Context api, let's explore the behavior of Atomico's context api:

createContext

create a custom Element as a context, this will serve to synchronize all the components nested within it, you must always remember to declare the tagname of this customElement, example

import { createContext } from "atomico";

export const Theme = createContext({
    color: "white",
    background: "black"
});

customElements.define( "my-theme", Theme  );

useContext

It allows to consume the return of createContext, let's go back to the previous example and suppose that we want to consume the customElement Theme created by createContext, the code for this would be the following:

In this way useContext captures the value of the parent component or reuses the value given by default to createContext.

Custom context values

By setting the value prop on the context, you can pass custom values down the sub-tree:

When to use the Context API?

It is ideal to always prioritize a conversation between parent and child through events or props api, but sometimes the depth of the DOM makes this process difficult, for this the context api has been introduced. To remove DOM depth limitations and ensure synchronization based on a unique identifier, some ideal cases to solve with the context api are:

1. Synchronize states or private methods between components.

2. Share a value or states inherited from the parent regardless of DOM depth.

The idea is to create an instance of AbortController every time the hook's parameters change. Each parameter change will abort the previously generated controller, thus cancelling any subscribed promises.

Example

import { useAsync, useAbortController } from 'atomico';

async function getUser(id: number, signal: AbortSignal) {
  return fetch(`/id/${id}`, { signal });
}

function myComponent({ userId }: Props<typeof myComponent>) {
  const { signal } = useAbortController([userId]);

  const user = useAsync(getUser, [userId, signal]);

  return <host>{user.name}</host>;
}

myComponent.props = { userId: { type: Number, value: 0 } };

The significant advantage of using useAbortController is the automatic cancellation of asynchronous processes that depend on it when modifying the arguments provided to useAbortController (similar to useEffect).

useAsync

with a similar approach to React's use hook, but with scope approach.

scope approach? yes, this hook seeks to resolve a promise from a callback return, this allows you to regenerate the promise according to the scope, example:

import { useAsync } from "atomico";

where:

• getUser: async callback.

• [ userId ]: arguments that if changed regenerate the promise.

• user : promise return

Like useEffect, the promise will be executed every time the arguments to the second parameter of useAsync change.

useSuspense

allows to listen to all useAsync executions nested in the component, example:

The purpose of this hook is to facilitate the consumption of promises.

Syntax

import { usePromise } from "atomico";

const callback = (id: number) => Promise.resolve(id);
const args: Parameters<typeof callback> = [1];
const autorun = true;

const promise = usePromise( callback, args, autorun );

where:

• callback : asynchronous function.

• args: arguments that callback requires.

• autorun: by default true, it automatically executes the promise, if it is false the execution of the promise is suspended.

• promise : return object, at the type level it defines the following properties:

  • pending: boolean, defines if the promise is executed but pending resolution.

  • fulfilled

Example

The "atomico/test-hooks" submodule is a direct part of Atomico's core and will allow you to run the customHook in a controlled way without the need for webcomponents.

import { createHooks } from "atomico/test-hooks";

createHooks

function that creates an isolated context that is shared globally with Atomico hooks when executing the load method

Instance

Where:

• optionalRender: Callback that allows restarting the hook's life cycle, this callback will be executed every time a hook like or requests the scope update, Atomico uses it to render the webcomponent again.

• opcionalHost: allows to share an object for the hook , Atomico uses it to share the instance of the webcomponent.

Return of the instance

Where:

• load: Function that allows to load the hooks to the temporary global context of Atomico.

• clearEffect: Function that activates the collector of useLayoutEffect, when executing clear Effect a callback will be returned that allows ending the collector for useEffect, closing the cycle of secondary effects.

  If clear Effect receives true as parameter, it communicates the unmounted.

Example:

./use-counter.js: customHook to test.

./use-counter.test.js: The example is based on the test environment from .

We recommend the @web/test-runner tool, if your project was created with the command npm init @atomico the test environment will be preconfigured, you can see this pre-configuration at https://github.com/atomicojs/base/tree/2-started.

Advanced (Documentation in progress)

To scale the test environment you can complement with tools such as:

1. : allows you to automate interactions and evaluate interactions of your interface.

2. : Allows you to evaluate the appearance changes of your component or application between versions.

Atomico makes it easy to declare events at the type level using the Host type.

Example

import { Host, c, useEvent } from "atomico";

type CustomDetail = { timestamp: number };

const MyComponent = c(
  (): Host<{ onMyCustomEvent: CustomEvent<CustomDetail> }> => {
    const dispatch = useEvent<CustomDetail>("MyCustomEvent");
    return (
      <host>
        <button
          onclick={() => {
            dispatch({ timestamp: Date.now() });
          }}
        >Click</button>
      </host>
    );
  }
);

In the previous code, we have declared the onMyCustomEvent event at the type level. According to the template logic, this event will be dispatched every time the button is clicked, and the detail attached to this event will be of type CustomDetail.

With Atomico and Typescript you will be able to:

1. Construct the props parameter of your functional component.

2. Check the correct declaration of your component.

📌 If you are a Typescript user I recommend using TSX vs the template-string, as you will benefit from:

1. JSX runtime, Typescript will automatically import Atomico upon detecting the use of TSX.

2. Autocompletion and validation of attributes, properties and events of tags and webcomponents.

3. Webcomponent instance validation using constructors.

Construct the props parameter of your functional component.

Your component as a function does not infer the props, to help infer the props you should use the Props type, example:

From an object: Construct props directly from the declaring object.

From the component: Build the props from the component, internally Atomico captures the property component.props.

From another customElement component: It's unusal, but when you extend another component you can infer the props from its constructor.

Check the correct declaration of your component.

Typescript checks the structure of your component by using the c function on it, thus validating which props and styles have been attached.

The return of c is a CustomElement with the types of the associated props, example:

It will report an error to Typescript since this component's props define that value is of type number, this validation also applies when instantiating your CustromElement in JSX or TSX.

Both TSX or JSX will help you to build better applications since it verifies the types according to the definition of its component, this verification is Free, it does not need plugins, only a tsconfig.json file and Typescript to automate the revision.

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 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 under the following

Atomico inside Next.js

All webcomponents work in Next if it escapes from SSR

Example of custom tag usage

Example of use of the wrapper.

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 has 3 great hooks to solve asynchronous tasks:

1. usePromise: Processes asynchronous tasks and shows the status and resolution of these

2. useAsync: Allows you to pause rendering until a promise is resolved

3. : Allows to know the paused states product of the use of useAsync nested in the component

Normally we create webcomponents that only work with lightDOM or shadowDOM, example:

function componentWithLightDom() {
  return (
    <host>
      <h1>I am in the lightDOM</h1>
    </host>
  );
}

function componentWithShadowDom() {
  return (
    <host shadowDom>
      <h1>I am inside the shadowDOM</h1>
    </host>
  );
}

With atomico you can go further thanks to the hook @atomico/hooks/use-render which allows you to execute renders independent of the main one, example:

import { useRender } from "@atomico/hooks/use-render";

function componentWithLightDomAndShadowDom() {
  useRender(() => <h1>I am in the lightDOM</h1>);
  return (
    <host shadowDom>
      <h1>I am inside the shadowDOM</h1>
    </host>
  );
}

What are the benefits of using useRender?

1. Encapsulate DOM fragments within custom Hooks and then render to any webcomponent.

2. patch the limitations of webcomponents that use shadowDOM, to improve communication with forms.

Patch the limitations of web components that use shadow DOM, to improve communication with forms

With the useRender(...) fragment we are managing to render an input in the lightDOM, thanks to this we will be able to control said input from inside the webcomponent.

Conclucion

Thanks to useRender you will be able to work together with LightDOM and shadowDOM from the scope of the webcomponent created with Atomico.

Introduction

Slots are a powerful feature when working with webcomponents that use the shadowDOM. And thanks to the hook @atomico/hooks/use-slot you will be able to observe the state of the slot and know the childNodes of this to manage the logic of the template. For example:

import { useRef } from "atomico";
import { useSlot } from "@atomico/hooks/use-slot";

function component() {
  const refSlotIcon = useRef();
  const slotIcon = useSlot(refSlotIcon);
  return (
    <host shadowDom>
      <slot
        name="icon"
        ref={refSlotIcon}
        style={slotIcon.length ? null : "display: none"}
      />
      <slot />
    </host>
  );
}

Thus managing to easily condition parts of our template to define the slots.

Another trick that useSlot allows us is the interaction at the DOM level, example:

import { useRef, useEffect } from "atomico";
import { useSlot } from "@atomico/hooks/use-slot";

function component() {
  const refSlotSlides = useRef();
  const slotSlides = useSlot(refSlotSlides);

  slotSlides.forEach((slide) => {
    slide.style.width = "100%";
    slide.style.height = "300px";
  });

  return (
    <host shadowDom>
      <slot name="slides" />
    </host>
  );
}

We can even apply filters per instance for a better identification of the node, example:

⚠️ In case of high ui computation use prefer to use slot modifiers inside a useEffect.

Slot pattern as a template

Slots are not only limited to a static definition, you can use them to identify a node and use it to create new nodes according to the logic of the webcomponent, example:

Thanks to useSlot(refSlotTemplateUser) we get the first node of the Template slot to be used in the iteration of the results obtained by fetch, with this we have eliminated the leverage of the webcomponent in charge of rendering the user at the level of our webcomponent userFetch

Example

⚠️ the cloneNode property is available from version atomico@1.37.0

How to render a webcomponent in Storybook with React

The following error is the most common when using Atomico in Storybook with React.

localhost/:1 Uncaught DOMException: Failed to execute 'define' on 'CustomElementRegistry': this constructor has already been used with this registry

We recommend using @atomico/react, this package creates a friendly wrapper for React.

The use of slots improves the composition allowing to reflect the content exposed in the lightDOM of the component in the shadowDOM of this, example:

::slotted(<selector>)

The slotted selector allows the manipulation of the content exposed as a lightDOM slot from the shadowDOM, example:

Auto slot

With Atomico you can define a default slot for your components, this is useful if you want to maintain some compositional consistency without the need to declare the use of slot, example:

To define a default slot, you only have to declare slot in the props, example:

Consider this practical only if the composition is leveraged to the container, this does not prevent you from modifying the slot property from the component instance.

Conditional slot

Atomico has the hook that appends the slotchange event to a reference, this will allow you to hide slots if they do not declare content, example:

Node

Atomico and automatic SSR support, you will not need additional packages, example:

// If your version of node accepts top-level await just point to 'atomico/ssr'
import 'atomico/ssr/load'; 

Unlike other libraries, Atomico automatically hydrates when mounting the component in the DOM, so no additional client configuration is required.

SSR/SSG via @atomico/react

The @atomico/react package allows you to take advantage of support for SSR or SSG designed for React/Preact, example:

1. Next.js:

   • Example:

   • Repo:

Astro build

allows to integrate SSR and SSG support to Astro build, We have used this integration to create the site.

It is normal that we use the technique of dispatching events from the component to communicate states and more, but when using forms this changes since the events inside the shadowDOM do not interact with the form outside of it, example:

<form>
    <my-input>
        #shador-root
            <input/>
    </my-input>
</form>

To solve this we will have to nest an input tag in the lightDOM of our component, in order to reflect the logic of this to the form. Atomico facilitates this hybrid interaction between lightDOM and shadowDOM with the @atomico/hooks/use-render hook that allows executing a second render that works from the lightDOM, example:

import { useRender } from "@atomico/hooks/use-render";

function myInput(){
    // render LightDOM
    useRender(()=><input/>);
    
    // render ShadowDOM
    return <host shadowDom>
        <slot/>
    </host>
}

With this you have gained full control over the existing input tag in the lightDOM, allowing you to apply styles using the ::slotted selector, example:

myInput.styles = css`
    :slotted(input){
        border: 1px solid black;
        height: 40px;
    }
`;

We have created an input tag that allows you to interact directly with the form, this technique is applicable with all the tags that interact with the form, such as button, input, textarea and others.