1 of 100

English

Atomico

A micro library inspired by React Hooks, designed and optimized for the creation of webcomponents.

import { c } from "atomico"; // 2.5kB

const MyComponent = c(
  ()=><host shadowDom>Hello, {name}</host>,
  {
    props: { name: String }
  }
);

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

import { Props, c } from "atomico"; // 2.5kB

function component({ name }:Props<typeof component.props>) {
  return <host shadowDom>Hello, {name}</host>;
}

component.props = {
  name: String,
};

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

import { c, html } from "atomico"; // 3.0kB


function component({ name }) {
  return html`<host shadowDom>Hello, ${name}</host>`;
}

component.props = {
  name: String,
};

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

import { c, html } from "https://unpkg.com/atomico"; // 4.0kB


function component({ name }) {
  return html`<host shadowDom>Hello, ${name}</host>`;
}

component.props = {
  name: String,
};

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

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

Scalable and reusable interfaces: with Atomico the code is simpler and you can apply practices that facilitate the reuse of your code.
Open communication: with Atomico you can communicate states by events, properties or methods.
Agnostic: your custom Element will work in any web-compatible library, eg React, Vue, Svelte or Angular.
Performance: Atomico has a comparative performance at Svelte levels, winning the third position in performance according to webcomponents.dev in a comparison of 55 libraries among which is React, Vue, Stencil and Lit.

API

Getting started with Atomico

This guide will know the essentials to start developing webcomponents with Atomico

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

Development agility, Atomico's functional approach simplifies code at all stages of development.
Lightweight inside and out, Atomico allows you to create a component with less code and with a low dependency impact. Approximately 3kb.
Really fast, Atomico has a good performance in the browser and an agile development experience. Let's understand what a webcomponent created with Atomico looks like:

// IMPORT
import { c, html, css } from "atomico";

// WEBCOMPONENT
function component({ message }) {
  return <host shadowDom>${message}</host>;
}

// WEBCOMPONENT PROPERTIES AND ATTRIBUTES
component.props = {
  message: String,
};

// WEBCOMPONENT APPEARANCE
component.styles = css`
  :host {
    font-size: 30px;
  }
`;

// DEFINITION OF THE WEBCOMPONENT AS A TAG
customElements.define("my-component", c(component));

// IMPORT
import { c, html, css } from "atomico";

// WEBCOMPONENT
function component({ message }) {
  return html`<host shadowDom>${message}</host>`;
}

// WEBCOMPONENT PROPERTIES AND ATTRIBUTES
component.props = {
  message: String,
};

// WEBCOMPONENT APPEARANCE
component.styles = css`
  :host {
    font-size: 30px;
  }
`;

// DEFINITION OF THE WEBCOMPONENT AS A TAG
customElements.define("my-component", c(component));

Let's analyze the code in parts ...

Import

import { c, html, css } from "atomico";

What have we imported?

c: Function that transforms the functional component into a standard customElement.
html: Function to declare the template of our component, you can also use JSX.
css: Function that allows creating the CSSStyleSheet (CSS) for our component as long as it declares the shadowDom.

Webcomponent

function component({ message }) {
  return <host shadowDom>${message}</host>;
}

function component({ message }) {
  return html`<host shadowDom>${message}</host>`;
}

Our component function receives all the props (Properties and Attributes) declared in component.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".

Reactive properties and attributes of the webcomponent

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:

index: Name of the property and attribute.
value: type of the prop.

component.props = {
  message: String,
};

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.

Appearance of the webcomponent.

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

component.styles = css`
  :host {
    font-size: 30px;
  }
`;

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.

Definition of your webcomponent

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

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

Getting started with Atomico for React users

Hi, I'm Atomico js and I bring you the React syntax for webcomponents, I think you and I get along very well 😊.

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?

Atomico, like React, allows a declaration of components using only functions, example:

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.

Now I want to invite you to learn how to declare a style using Atomico.

How do you declare styles using Atomico?

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.

Instances, children and slots

It is normal for React to create components that you then instantiate within other components, for example:

with Atomico there are certain differences:

1. With Atomico you can instantiate CustomElements using its constructor

The constructor in Atomic is the product of the c function and is the one you will use to register your webcomponent, example:

According to the previous example, you can instantiate MyComponent as a JSX Component, example:

This instance type allows autocompletion at the JSX level and type validation at the Typescript level.

2. With Atomico you can instantiate components as functions as long as these are only stateless functions

This will be useful for reusing templates, but always remember stateless.

What can you do with Atomico?

With Atomico you can do this and more

You can create design systems

Today Atomico is used in the development of design systems for various industries such as Banking, Pledge Systems, Insurance, Clinical, Government and more.

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?

Atomico offers you Storybook 7 Support with superpowers, thanks to @atomico/storybook you can create stories without the need to declare the argTypes or args since @Atomico/storybook creates them for you
@atomico/vite makes it easy for you to build in NPM-friendly ESM format
@atomico/exports 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
@atomico/potscss-tokens 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.

https://github.com/atomicojs/atomico/discussions/92

You can create websites

Creating sites with Atomico is really easy and SEO friendly because:

With Atomico you can perform SSR and SSG thanks to tools like Astro build, with Astro + Atomico you can send previously rendered components to the client, thus giving a result at the HTML level that is really friendly with search engines.
Atomico being really small (3kB) your sites will load fast, especially if you only apply SSG with Atomico.
Atomico not only supports SSR through Astro, you can SSR today with Atomico in Next.js, Express or any environment that supports ESM modules.
(Coming soon) Yes, with Atomico soon you will be able to create blocks for Gutenberg easily

We recommend the use of Astro build with the @atomico/astro plugin, with this you can create sites like atomicojs.dev

Preferably we recommend Astro + React + Atomico, but in case your project inherits the use of Next.js you can do SSR with Atomico in Next.js using @atomico/react.

You can create mobile applications

working on this documentation...

You can create web applications

working on this documentation...

API

Props(Properties)

The props in Atomico are the way to associate the webcomponent properties and reactive attributes that trigger the logic or interface of the webcomponent.

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

Access state via instance, example: document.querySelector("my-component").myStateProp.
Dispatch events on prop value change, example: document.querySelector("my-component").addEventListener("myPropChange",console.log).
Reflect attributes as prop, example: <my-component my-prop="...."> to document.querySelector("my-component").myProp.
define strict input types for props.

Syntax

Any function that represents the webcomponent will be able to associate the static object props for the declaration of reactive properties and attributes, for example:

Consider that:

The prop names in Camel Case format will be translated to for use as an attribute to the Kebab Case format, this behavior can be modified through the "attr" property when using a structured declaration.
Structured declarations require the "type" property minimally.
Not all types can use the "reflect" properties.
The declaration of the "value" property can vary depending on the type.

Simple statements

Simple statements allow setting just type validations.

Structured declaration

Improve the definition by adding utility declarations, allowing for example to reflect the property's value as attributes, automatically emit events or associate default values. Remember these types of declarations minimally require the use of the type property.

Prop.type

Prop.reflect

If the "reflect" property is set to true, its value is reflected as an attribute of the webcomponent, this is useful for the declaration of CSS states, example:

Prop.event

It allows dispatching an automatic event before the prop value change, example:

Where:

event.type: String - optional, name of the event to be emitted when the prop is changed
event.bubbles: Boolean - optional, indicates that the event can be listened to by containers.
event.detail: Any - optional, allows to attach a custom detail for the event
event.cancelable: Boolean - optional, indicates that the event can be canceled by any listener
event.composed: Boolean - optional, allows the event to exceed the shadow-root limit

Prop.value

Atomico allows the definition of default values of the props.

The association of callback as value allows generating unique values for each instance of the webcomponent, this is useful with the Object and Array types since it eliminates the references between instances.

Reactivity in the scope of the webcomponent

Atomico removes the use of "this" given its functional approach, but adds the hook [useProp] (hooks / useprop.md) which allows to reference a prop for use with a functional syntax, eg:

Advanced

Special properties

Property

Type

Effect

render

By default, the render is configured to be used within the webcomponent by reading the return of the function, but it can be used outside of Atomico, example:

Render rule "The first node of the render must always be the host tag".

Constructor with custom element

This technique allows you to use any registered custom element without the need to know its tag-name for its use, example:

Advantage :

Remove leverage from tag-name
Infer the types of the props and autocomplete only if you use JSX and Atomico.

Constructor with DOM

Atomico allows the use of the DOM, for this it establishes its created or recovered node as a constructor, example:

Dynamic constructor

Atomico associates the variable associated with the instance as a constructor, example:

staticNode

allows to declare a node within the scope of the function as static, this will optimize the diff process between render, achieving better performance in cases of high stress of the UI, example:

the biggest advantage of this is that the node accesses the scope of the webcomponent

cloneNode

Allows to clone a node from the virtualDOM, example:

The objective of this feature is to retrieve slot and use it as a template from the webcomponent.

SSR hydration

Atomico allows reusing existing DOM in the document. This is done during the webcomponent instatiation, by setting a special property in the tag to mark it for hydration.

This can be done for shadowDom too:

Class name inheritance

Atomic creates a customElement from a function, Atomico will take the name of the function and associate it as the name of the CustomElement in CamelCase format, example:

This results in the class name being equal to Button. This feature is useful for tools like Storybook, when serializing the JSX.

Hooks

Improves the experience of reusing logic between webcomponents based on Atomico

Hooks only for webcomponents

Hooks homogolates of React

@atomico/hooks

Atomico today offers more Hooks external to the core, we invite you to visit @atomico/hooks with more than 50 hooks to enhance the use of webcomponents 😎

useProp

Reactivity in the scope of the webcomponent without the use of context(this)

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

Syntax

const [value, setValue] = useProp(myProp);

Where :

value: Current value of the prop.
setValue: Callback to update the value of the prop.
myProp: string, defines the name of the prop to be used by the hook.

Example

import { useProp } from "atomico";

function useCounter(prop) {
  const [value, setValue] = useProp(prop);
  return {
    value,
    increment: () => setValue((value) => value + 1),
    decrement: () => setValue((value) => value - 1),
  };
}

function component() {
  const counter = useCounter("value");
  return (
    <host>
      <button onClick={counter.increment}>+</button>
      <strong>{counter.value}</strong>
      <button onClick={counter.decrement}>-</button>
    </host>
  );
}

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

import { useProp } from "atomico";

function useCounter(prop) {
  //                                 👇 type for prop
  const [value, setValue] = useProp<number>(prop);
  return {
    value,
    increment: () => setValue((value) => value + 1),
    decrement: () => setValue((value) => value - 1),
  };
}

function component() {
  const counter = useCounter("value");
  return (
    <host>
      <button onClick={counter.increment}>+</button>
      <strong>{counter.value}</strong>
      <button onClick={counter.decrement}>-</button>
    </host>
  );
}

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

Where:

useCounter is a customHook and that it can work with any property of the webcomponent of type Number.
useCounter returns 2 methods increment and decrement that modify the value of the prop.
useCounter can be instantiated multiple times for different properties.

useRef

Create a persistent object between renders to capture from a node from VirtualDOM

Syntax

const ref = useRef(optionalCurrent);

Example

import { useRef, useEffect, useState } from "atomico";

function component() {
  const ref = useRef();
  const [message, setMessage] = useState();
  useEffect(() => {
    const { current } = ref;
    current.addEventListener("input", () => {
      if (current.validity.typeMismatch) {
        setMessage("Invalid!");
      }
      current.setCustomValidity("");
    });
  }, []);
  return (
    <host>
      <input type="email" ref={ref} />
      {message && <h1>{message}</h1>}
    </host>
  );
}

Observation

The reference object is useful for referencing nodes between customHooks.

useHost

Hook that creates a reference that curren is the instance of the webcomponent.

Syntax

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

Example

From the example we can highlight that useListener is a customHook that allows listening to an event from the webcomponent without the need to link said event to the VirtualDOM.

useReducer

useEffect, useLayoutEffect and useInsertionEffect

Allows to run side effects after rendering

Syntax

useEffect(effectCallback, optionalArgumentList);

Where :

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

const listenerClickWindow = () => {
  const handlerClick = () => {
    console.log("Click window!");
  };

  window.addEventListener("click", handlerClick);

  const unlistenerClickWindow = () =>
    window.removeEventListener("click", handlerClick);

  return unlistenerClickWindow;
};

useEffect(listenerClickWindow, []);

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.

useId

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

Syntax

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.

useContext

Since version Atomico@1.62.0 has introduced a context api as part of the core.

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

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:

It is highly recommended to always use custom properties to expose the appearance configuration of your component at the static CSS level, since useContext is designed to share information between components in a unidirectional way.

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:

Synchronize states or private methods between components.
Share a value or states inherited from the parent regardless of DOM depth.

useProvider

Allows the host that instantiates this useProvider to become the context.

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:

Objective

Avoid creating an instantiable context node in the DOM.

usePromise

Easily observe asynchronous processes

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: boolean, defines if the promise has been fulfilled
- result: result of the promise.
- rejected: boolean, defines if the promise has been rejected.

Note: When using Typescript Do not force the types for the second argument of usePromise, as usePromise will infer them from your callback.

It is preferable to use ternary or if to condition the reading of states, since this will help the definition of result

Example

import { usePromise } from "atomico";

const getUsers = (id: number) => Promise.resolve({ id, name: "Atomico" });

function component() {
  const promise = usePromise(getUsers, [1]);

  return (
    <host>
      {promise.fulfilled ? (
        <h1>Done {promise.result.name}!</h1>
      ) : promise.pending ? (
        <h1>Loading...</h1>
      ) : (
        <h1>Error!</h1>
      )}
    </host>
  );
}

Note: At the type level, autocompletion is conditional on the state you are looking to observe.

useAsync and useSuspense

suspend the execution of a render until the resolution of an asynchronous process

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:

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.

Rendering will be suspended until the promise is resolved or rejected, the resolution of the promises can be observed with useSuspense

useSuspense

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

useAbortController

Atomico now introduces a new hook called useAbortController, which allows aborting the execution of asynchronous calls, example:

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

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

Testing

We recommend the 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 .

Advanced (Documentation in progress)

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

: allows you to automate interactions and evaluate interactions of your interface.
: Allows you to evaluate the appearance changes of your component or application between versions.

Render cycle

Atomico optimizes the execution of your script by minimizing resources through the rendering control.

Atomico's render cycle works like this:

First, when the component is instantiated, 3 promises will be created pending resolution:

componentInstance.mounted: resolved once the connectedCallback has been executed by the customElement.
componentInstance.updated: the render cycle for first mount or update is encapsulated in componentInstance.updated.
componentInstance.unmounted: resolved once the disconnectedCallback has been executed by the customElement.

Render or rerender cases are:

First render.
Updating a property or attribute.
Update dispatched by a hook

Remember all updates are stacked into a single big loop of componentInstance.updated.

This improves the testing experience since to observe the changes you only have to wait for the resolution of componentInstance.updated , example:

Webcomponent as function

The first rendering as the update of a prop will call to execute again the function that defines our component, Atomico internally stores the references to support the Hooks api and will render the virtualDOM returned by said function, this is encapsulated within componentInstance.updated

SSR

Atomico allows modifying its life cycle in cases of SSR, improving the rendering of the CSS in case of SSR and avoiding the effects of useEffect and useLayoutEffect

Hydration

Technique to reuse the DOM generated by the SSR, Atomico only in the first render of the component that declares date-hydrate will retrieve the existing DOM in the DOM not created by Atomico to relate it to the virtualDOM, avoiding creating the node again.

Optimization

Atomico by default has a good performance, but it can be further optimized if certain techniques are applied.

Render optimization with static nodes

A static node is equivalent to using node.cloneNode(true)

render optimization with renderOnce

The renderOnce property renders the node only once, one of the advantages of this technique is that the virtualDOM can access the scope of the function.

atomico/test-hooks

Build test to custom hooks created with Atomico with an isolated instance and predictable

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.

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.

atomico/test-dom

fixture

function that allows to keep the render on a single node for each execution of it, the container will be unmounted at the end of each execution of it.

This allows each fixture execution inside it to be related to the container used for the test, allowing you to fily test external DOM changes, example:

Guides

Frequent questions

Is it advisable to declare events using the props API?

It is not recommended to use the props API to create an event, as this callback associated as props will have the following limitations:

Its name cannot have the on prefix since, if it does, Atomico will recognize it as a property expecting to listen to the event.
It can only have one listener, limiting others from observing the event.

Using the hook to dispatch component-level events or any custom hook.
Using the API to dispatch events when the observed prop changes.

Always prefer the two previously mentioned methods, as they allow you to:

Define if the event bubbles.
Define if the event is cancelable.
Define if the bubbling event can penetrate the shadow DOM.
Define a custom constructor for the event.
Having multiple listeners for the event

When is it recommended to use a callback as a prop?

Cuando se busca comunicar parametros o leer el retorno de este, ejemplo:

When and why to use shadowDom?

When to use the shadow Dom?

By creating a UI solution that coexists in the web ecosystem such as HTML, libraries and frameworks, since the shadowDOM allows you to:

Protect your UI from libraries like React, Vue and others
Associate styles natively, efficiently and safely
Reference lightDOM content in the shadowDOM

Webcomponents with Shadow DOM are ideal for creating cross UI solutions as they coexist without conflict with the entire web ecosystem.

Why use shadowDOM?

To protect our component at the DOM manipulation level and take advantage of some of the benefits of the shadowDOM such as:

Slot management
CSS appearance of web component.
The shadowDOM is ideal for creating components that interact with libraries like React, Vue or others. The ShadowDOM protects the DOM it contains from manipulations generated by other libraries.

Slot management

Slots allow us to reflect existing nodes in the lightDOM into the shadowDOM, example:

This is really useful, since we can group slots according to their name in a specific place of the webcomponent.

We invite you to learn more about slots through the following guide:

CSS appearance of web component.

The shadowDOM allows you to do something fantastic, protect your CSS from global styles, this has 2 great advantages:

The appearance of our component will not be affected by global CSS declarations.
Customization protected by CSS custom Properties

We invite you to learn more about handling styles in atomic through the following guide:

Can I use Atomico in browsers without ESM support?

Yes, but Atomico doesn't only depend on ESM, it also depends on the following api's that you will have to cover with Polyfill or some bundle tool.

ESM modules: documentation - caniuse
CustomElements: documentation - caniuse
ShadowRoot: documentation - caniuse
Map: documentation - caniuse
Symbol and Symbol.for: documentation - caniuse
append and prepend: documentation - caniuse
Declarative Shadow DOM: Only for using SSR with webcomponents that use shadowDOM. documentation

Let's understand that today Atomico covers 94% of existing browsers without the need for polyfills or packers, the 6% not covered are usually browsers like ie11 or others.

If you depend on the uncovered segment of browsers you can use the following tools to support the apis necessary for Atomico to work.

polyfill-fastly.io to associate Map, Symbol, append and prepend.

https://github.com/Rich-Harris/shimport to associate esm.

https://github.com/ungap/custom-elements to associate customElements apis.

Component

Working on this documentation...

Naming

Simple but useful

If you are a React user, it is common for you to make component declarations like these:

export function MyComponent(){
    return <>My component in react</>
}

Thanks to the previous code in React we can:

Instantiate your component through its function, example <MyComponent>
Friendly export component as module

In Atomico there are some small differences 👇

Export the return of the c function, since it is instantiable at the JSX level or when using the new operator, example:

function myComponent(){
    return <host>My component in Atomico</host>
}

export const MyComponent = c(myComponent);

customElements.define("my-component", MyComponent);

import { MyComponent } from "./my-component";

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

Instance with operator new: The new operator allows the instance to associate at the TS level the types declared using Atomico

import { MyComponent } from "./my-component";

const component = new MyComponen;

Instance with document.createElement

import "./my-component";

const component = document.createElement("my-component");

<my-component></my-component>

Gracias a lo anterior podemos:

Instantiate your component with TS-level type validation either by using JSX or the new operator with, but remember that to get this type of instances you must first have registered your customElement in the same file or another.
Export the useful component to instantiate.

Prefer this export format because tools like @atomico/exports take advantage of this format to automatically create wrappers for React, Preact, and Vue.

Atomico with Typescript

Atomico with Typescript will improve the scalability of your project thanks to a really productive type system when creating, distributing and maintaining webcomponents

With Atomico and Typescript you will be able to:

Construct the props parameter of your functional component.
Check the correct declaration of your component.
Check the correct use of hooks.
Declare meta-types to the component.

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

JSX runtime, Typescript will automatically import Atomico upon detecting the use of TSX.
Autocompletion and validation of attributes, properties and events of tags and webcomponents.
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.

import { Props } from "atomico";

const props = {
  value: { type: Number, value: 0 },
};

function myComponent({ value }: Props<typeof props>) {
  return <host>{value * 10}</host>;
}

myComponent.props = props;

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

import { Props } from "atomico";

function myComponent({ value }: Props<typeof myComponent>) {
  return <host>{value * 10}</host>;
}

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

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

import { Props, c } from "atomico";
import { MyOtherComponent } from "./my-other-component";

function myComponent({ value }: Props<typeof MyOtherComponent>) {
  return <host>{value * 10}</host>;
}

export const MyComponent = c(myComponent, MyOtherComponent);

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.

import { Props, c, css } from "atomico";

function component(props: Props<typeof component>) {
  return <host>{props.value}</host>;
}

component.props = {
  value: Number,
};

component.styles = css`
  :host {
    color: tomato;
  }
`;

const MyComponent = c(component);

customElements.define("my-component", MyComponent);

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

const myComponent = new MyComponent();

myComponent.value = "abc";

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.

<MyComponent value="abc"></MyComponent>

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.

Props

The Props type allows you to infer the types of props already declared in the props object, example:

The main difference with the Component type is that Props does not generate stricture rules for the component, it only infers the props object to be used as an argument.

At the Typescript Props level, it does evaluate the structure of the component, in order to correctly infer the props, so if the component has a writing error, a warning about this type will be displayed.

Type

Although the props today offer strict rules, Type allows them to be complemented with a direct definition of the types to accept, example:

import { Props } from "atomico";

function component(){
    return <host/>
}

component.props = {
    value: String as Type<"A"|"B"|"C">
}

The above is equivalent to using value as a function, example:

import { Props } from "atomico";

function component(){
    return <host/>
}

component.props = {
    value: {
        type: String,
        value: ():"A"|"B"|"C"=>"A"
    }
}

This is also valid for the null type that in Atomic translates as Any, example:

component.props = {
    src: null as Type<string | Promise<any>>
}

Event declaration

Atomico supports through the use of the Host type, the declaration of events and methods, this is useful for associating meta-types to the customElement instance when using JSX or TSX.

Host to declare events

Host will be useful for you to declare your event using JSX or TSX regardless of its origin, example:

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

function myComponent(): Host<{
  onMyCustomEvent: Event
}> {
  const dispatch = useEvent("MyCustomEvent");
  return <host>
      <button onclick={dispatch}>click</button>
  </host>;
}

export const MyComponent = c(myComponent);

The use of Host allows that when using JSX or TSX your event is validated through Typescript, this also applies when using @atomico/react, example:

import { MyComponent } from "my-componnet";

<MyComponent
  onMyCustomEvent={(event) => {
    event.currentTarget; //  < MyComponent
  }}
></MyComponent>;

Note event.currentTarget accesses the CustomElement, example properties and more.

That has another benefit, capturing the event as a type to be used in an external handler, example:

function handlerMyCustomEvent(
  event: DOMEvent<"MyCustomEvent", typeof MyComponent>
) {
  event.currentTarget; //  < MyComponent
}

Check the correct use of hooks

By default most hooks infer types automatically, however here are some typing tips:

useState

useState infers the type according to its initial state, if you don't define that state you can define the type manually, example:

The above statement will define that:

message is of type string.
setMessage only accepts values of type string or functions that return a string.

useProp

useProp will not infer the type from the prop, you must define it, example:

Let's remember that useProp has a return api similar to useState, so the previous declaration will define that:

message is of type string.
setMessage only accepts values of type string or functions that return a string.

useMemo and useCallback

both useMemo vs useCallback infer its type based on the callback that builds the memo state, but for certain conditions you may need to force the type return, example:

Although useMemo infers that its type is string, you can change the return rules via the first type parameter.

The above statement will define that:

message is of type string.

This applies equally to useCallback.

useEvent

useEvent allows defining the detail structure through the type parameter, example:

The above statement will define that:

The dispatch callback expects an object of type {id: string} as a parameter.

useRef

useRef allows to define through the type parameter the expected value of current in the reference.

The above statement defines:

refForm?.current is of the type HTMLFormElement.

useHost

useHost defines that current always exists, so the optional selector is not necessary, the type parameter of useHost allows to define the source Element, example:

All hooks in Atomico have Type declarations, explore them when importing each hook as a documentation source.

Integrating Atomico in React

Atomico integrates very easily into React, either using @atomico/exports or @atomico/react.

@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 @atomico/exports 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 @atomico/react in the following guide:

From React to Atomico

Atomico inherits part of the React syntax and applies it to webcomponents, with a closer to standard approach.

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

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.

Counter example

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.

CustomHooks example

From the example we will highlight the following differences:

The hook api is the same.
the component in Atomico returns the `<host/> tag.

Supported hooks

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

useRef
useState
useReducer
useLayoutEffect
useEffect
useMemo
useCallback

CSS-in-JS

Rendering Differences

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 or , 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 design patterns

Atomico has been designed to be simple even in complex situations, in this guide you will know some patterns that Atomico offers to create webcomponents at an advanced level.

Webcomponents with hybrid rendering

Improve the interaction of your inputs with forms using hybrid rendering (LightDOM and ShadowDOM)

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

With atomico you can go further thanks to the hook which allows you to execute renders independent of the main one, example:

What are the benefits of using useRender?

Encapsulate DOM fragments within custom Hooks and then render to any webcomponent.
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.

Slot as templates

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:

useSlot(refSlotSlides).filter(
  (childNode) => childNode instanceof HTMLDivElement
);

⚠️ 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:

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

function userFetch() {
  const refSlotTemplateUser = useRef();
  const [Template] = useSlot(refSlotTemplateUser);
  const promise = usePromise(
    () =>
      fetch("https://jsonplaceholder.typicode.com/users").then((res) =>
        res.json()
      ),
    [],
    true
  );

  return (
    <host shadowDom>
      <slot name="template" ref={refSlotTemplateUser} />
      <div class="list">
        {promise.fulfilled
          ? !!Template &&
            promise.result.map((props) => <Template {...props} cloneNode />)
          : "Pending..."}
      </div>
    </host>
  );
}

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

Slot

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:

The use of slot is thanks to the use of the ShadowDOM api, to make use of the shadowDom you must declare it as a property of the host tag, example:

<host shadowDom>I exist inside the shadowDOM</host>

::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:

<my-component>
    <my-component-header></my-component-header>
    <my-component-footer></my-component-footer>
</my-component>

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

myComponentHeader.props = {
    slot: { type: String, value: "header" }
}

myComponentFooter.props = {
    slot: { type: String, value: "footer" }
}

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 @atomico/hooks/use-slot that appends the slotchange event to a reference, this will allow you to hide slots if they do not declare content, example:

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

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

Atomico and Storybook

Status

Decorator, Atomico's decorator extends atomico's rendering capabilities to storybook.
Monorepo, We invite you to use the recipe through the CLI npm init atomico, you can also find this configuration on Github
Decorator for Storybook, Easily render webcomponents created with Atomico inside storytbook stories.
storybook 7 and storybook + Vite
MDX.

@Atomico/storybook

decorador

Easily render webcomponents created with Atomico inside storytbook stories.

.storybook/preview.js

import { decorator } from "@atomico/storybook";

export const decorators = [decorator];

define

It facilitates the creation of stories, analyzing the components created with Atomico to automatically define the argTypes and args.

import { define } from "@atomico/storybook";
import { ColorPicker } from "./color-picker";

export default {
  title: "components/brand",
  ...define(ColorPicker)
};

export const Default = (props: any) => <ColorPicker {...props}></ColorPicker>;

define also improves the declaration of stories by improving the autocompletion of these.

@atomico/vite

@atomico/vite has exclusive storybook utilities, with these it seeks to facilitate the use of Atomico's JSX /TSX and live reload.

Config storybook 7

import { mergeConfig } from "vite";

export default {
    stories: [
        // 📌 remember to define the path according to your configuration
        "../../components/**/*.stories.mdx",
        "../../components/**/*.stories.@(js|jsx|ts|tsx)",
        "../../components/*.stories.mdx",
        "../../components/*.stories.@(js|jsx|ts|tsx)",
    ],
    addons: ["@storybook/addon-links", "@storybook/addon-essentials"],
    framework: {
        name: "@storybook/web-components-vite",
        options: {},
    },
    async viteFinal(config, { configType }) {
        // 📌 return the customized config
        return mergeConfig(config, {
            plugins: [
                ...(await import("@atomico/vite")).default({
                    // 📌 needed to define files that use JSX/TSX
                    storybook: ["components/**/*"],
                }),
            ],
        });
    },
};
v

{
  "type": "module",
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
  },
  "dependencies": {
    "atomico": "^1.68.0"
  },
  "devDependencies": {
    "@atomico/storybook": "^1.5.0",
    "@atomico/tsconfig": "^1.1.2",
    "@atomico/vite": "^2.3.2",
    "@storybook/addon-actions": "^7.0.0-alpha.47",
    "@storybook/addon-essentials": "^7.0.0-alpha.47",
    "@storybook/addon-links": "^7.0.0-alpha.47",
    "@storybook/web-components": "^7.0.0-alpha.47",
    "@storybook/web-components-vite": "^7.0.0-alpha.47",
    "lit-html": "^2.4.0",
    "storybook": "^7.0.0-alpha.47",
    "vite": "^3.2.2"
  }
}

Frequent questions

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.

Using @atomico/react requires the following script to be imported into the .storybook/preview.js file

import "@atomico/react/proxy";

SSR / SSG

Implement SSR and SST without friction

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'; 
import { html } from 'atomico';
import { Component } from './static/component.js';
import express from 'express';

const app = express();
const port = 3010;

app.use(express.static('static'));

app.get('/', (req, res) => {
  res.send(`
    <script type="importmap">
    {
      "imports": {
        "atomico": "https://unpkg.com/atomico"
      }
    }
    </script>
    <script src="./component.js" type="module"></script>
    ${html`<${Component} value=${100}>
      <h1>Message from server!</h1>
     </${Component}>`.render()}
  `);
});

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`);
});

For this case we are using a JS-only component to avoid compilation in the example. you can achieve the same with JSX or TSX.

import { c, html, css, useProp } from 'atomico';

function component() {
  const [value, setValue] = useProp('value');
  return html`<host shadowDom>
    <h1>Atomico webcomponent</h1>    
    <button onclick=${() => setValue(value + 1)}>${value} Increment</button>
    <slot/>
  </host>`;
}

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

component.styles = css`
  :host{
    font-size: 32px;
    font-family: arial;
  }
`;

export const Component = c(component);

customElements.define('my-element', Component);

You will not need any additional package, atomic internally understands that the component must be hydrated

{
  "name": "node-starter",
  "type": "module",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "@atomico/site": "^0.1.0",
    "atomico": "^1.61.1",
    "express": "^4.17.1"
  }
}

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

To use SSR in Node without tools like Next.js, Fresh or Astro you should import the path atomico/ssr/load from the server

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:

Next.js:
- Example: https://example-next-js-mocha.vercel.app/
- Repo: https://github.com/atomicojs/example-next-js
Fresh:
- Example: https://atomico-webcomponents-tgd58wd8ntcg.deno.dev/
- Repo: https://github.com/atomicojs/example-fresh-deno

Astro build

@atomico/astro allows to integrate SSR and SSG support to Astro build, We have used this integration to create the atomicojs.dev site.

Forms and shadowDOM

Improve the interaction with the forms and accessibility of your components.

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.

Design systems

I will show you a series of useful techniques to start programming your design systems with Atomico, analyzing the recommended structure and its files.

Recommended structure

src/
	# Import, export and declare all our components
	components.js 
  # Group all the tokens in our system
	tokens.js
	# Structure example for our component
	/button
		button.{js,jsx,ts,tsx}
		button.md
		button.test.js

We will analyze the above.

src/components.js

File that imports, exports and declares all the components of our design system, example:

import { Button } from "./button/button";
export { Button } from "./button/button";

customElements.define("my-button", Button);

the utilities of this are to centralize everything in components.js are:

Clarity of the definition of customElements in a single file for our entire design system
Export of all customElements to be extended or redefined.

src/tokens.js

File that centralizes the custom-properties of our design system, example:

import { css } from "atomico";

export const tokensInput = css`
  :host {
    --background: var(--my-ds-input--background, #fff);
    --border-width: var(--my-ds-input--border-width, 1px);
    --border-color: var(--my-ds-input--border-color, black);
    --radius: var(--my-ds-input--radius, 0.5rem);
    --min-height: var(--my-ds-input--min-height, 40px);
  }
`;

export const tokenColors = css`
  :host {
    --primary: var(--my-ds--primary);
    --secondary: var(--my-ds--secondary);
    --success: var(--my-ds--warning);
    --warning: var(--my-ds--warning);
    --danger: var(--my-ds--warning);
    --info: var(--my-ds--warning);
  }
`;

From the example above I highlight the custom property declaration pattern

:host {
    --background: var(--my-ds-input--background, #fff);
}

--background will be a token that can be modified at the instance level and this inherits a global token from our system called --my-ds-input--background, I want you to notice that the global name of our custom property has a pattern, example:

---my-ds-input--background
---<prefix>-<namespace>--<property>

Where:

prefix: Prefix of our global design system
namespace: group independent of our design system
property: property associated with the system, such as color, size, or other value.

Why use the recommended pattern? To individualize the configuration at the group level and separate the property definition from it thanks to the use of double hyphens (--), internally everything is simplified since the tokens only capture the global configuration global to reflect it to a simpler variable accessible only from the component instance level.

Instance level

It is the instance of the component either in HTML or JS, example:

<my-component style="--background: red;"></my-component>;

const component = document.createElement("my-component");

component.style = "--background: red";

src/button.js

import { c, html, css } from "atomico";
import { tokensColor, tokensInput } from "../tokens";

function button(props) {

  return html`<host shadowDom>
    <button ...${props} class="input-box">
      <slot name="icon"></slot>
      <slot></slot>
    </button>
  </host>`;
}

button.props = {
  name: String,
  value: String,
  disabled: Boolean,
};

button.styles = [
  tokensColor,
  tokensInput,
  css`
    .input-box {
      display: flex;
      gap: 1rem;
    }
  `,
];

import { c, css } from "atomico";
import { tokensColor, tokensInput } from "../tokens";

function button(props) {
  return (
    <host shadowDom>
      <button {...props} class="input-box input-box--use-border">
        <slot name="icon"></slot>
        <slot></slot>
      </button>
    </host>
  );
}

button.props = {
  name: String,
  value: String,
  disabled: Boolean,
};

button.styles = [
  tokensColor,
  tokensInput,
  css`
    .input-box {
      display: flex;
      gap: 1rem;
    }
  `,
];

export const Button = c(button);

From the previous code I highlight:

import of "../tokens" and the destructuring of the module that declares the use of tokensColor and tokensInput.
button.styles: Atomico allows to associate multiple styles through the use of an array.
Button export.

Atomico style guide

First thanks for using Atomico 😉, in this guide you will find some useful tips when developing with Atomico, all with the aim that your webcomponents are sustainable and scalable over time.

Monorepo

The following format is friendly when sharing a webcomponent to NPM using @atomico/exports

├── src
│   ├── define.{js,ts,jsx,tsx}
│   ├── elements.{js,ts,jsx,tsx}
│   ├── define.test.{js,ts,jsx,tsx}
│   └── slots
│       ├── my-sub-element-1.{js,jsx,ts,tsx}
│       └── my-sub-element-2.{js,jsx,ts,tsx}
├── README.md
├── index.html
├── .npmignore
├── package.json
└── tsconfig.json

From the previous structure we highlight:

src/define: import the components from src/elements and declare them as customElements
src/elements: groups and export components as CustomElements

Why separate the export of the element from the declaration?

since it improves the customElements definition experience, example:

import "my-component"; // internalmente define el customTag
import { MyElement } from "my-component/elements"; // no define el customTag

Thanks to @atomico/exports this is really easy, example:

exports src/{define,elements}.{ts,tsx} --exports --types

You can see a use case of this structure in @atomico/components

Design systems

Distribution and consumption

When creating design systems or component systems, we recommend that you maintain a centralized distribution structure in a single export package with multiple import paths, example:

What are the benefits of this type of distribution?

Aesthetic coherence, the entire design system leverages itself and thanks to this we gain aesthetic coherence.

While a monorepo might seem like an ideal path, it actually increases the complexity of maintenance, whether it be component versioning and dependency maintenance.

We move faster and reduce implementation errors if you don't rely on individual versioning at the component level and leave this only defined at the design system level.

This has its pros and cons:

Pros:

It speeds up the creation of components, since it avoids the individual publication process and centralizes all this at the design system level.

Cons

you will not be able to update a component individually, since it is leveraged at the design system level.

Recommended file structure for webcomponents

you always prefer to keep each component isolated in a directory with names associative to the same component, example:

packages

@atomico/hooks

series of useful hooks for creating webcomponents

Hooks

use-current-value

useCurrentValue

The useCurrentValue hook allows associating a value with current based on its parameter, equivalent to:

With the useCurrentValue hook

use-intersection-observer

Create an IntersectionObserver instance to observe the intersection of the webcomponent or a reference.

Remember that to detect any intercept, a minimum height and width of the reference to be observed is required.

useIntersectionObserver

useRefIntersectionObserver

use-attributes

capture all attributes that are defined in the webcomponent but are not props

Syntax

Where:

attrs: all the attributes defined on the webcomponent but that are not props, to facilitate reading this hook transforms the index to camelCase

Example

use-prop-proxy

Share values from the scope via setter and getters

allows to create a setter and getter for a property of the webcomponent, this is useful for:

Reflect elements internal to the scope as part of the instance, example references.
Observe from the scope the mutations external to Atomico.

Example

use-click-press

The useClickPress hook will allow you to execute a callback with acceleration according to the click time, for example in the input type number we have 2 buttons by default, an up arrow and a down arrow, these allow us to modify the input value, either:

Increase the value before a click in a unit.
Increase the value by more than one unit according to the click pressure time.

Example

Live example

use-reflect-event

the useReflectEvent hook reflects the event from the reference origin to the reference destination

the useReflectEvent hook reflects the event from the reference origin to the reference destination, the captured event will be canceled

One of the possibilities of this hook is to reflect the events inside shadowDOM to lightDOM, example when using forms

module

import { 
    useReflectEvent, 
    reflectEvent  
} from "@atomico/hooks/use-reflect-event";

Syntax useReflectEvent

useReflectEvent(
    refFrom: Ref<Element>,
    refTo: Ref<Element>,
    eventType: string
);

useRefectEvent will listen for the eventType of refFrom, to reflect it on refTo

Syntax reflectEvent

reflectEvent( target: Element, event: Event );

Reflects on an element the given event

use-click-coordinates

The usesClickCoordinates hook is for capturing click coordinates, this is useful when positioning a tooptip or creating visual effects

Module

import { useClickCoordinates } from "@atomico/hooks/use-click-coordinates";

Syntax

useClickCoordinates(ref, handlerClick);

where:

ref: node reference to observe the click event.
handlerClick: Callback that receives the coordinates of the click event.

Coordinates

interface Coordinates {
  x: number;
  y: number;
  offset: {
    x: number;
    y: number;
  };
}

Where :

x: MouseEvent.clientX
y: MouseEvent.clientY
offset.x : MouseEvent.offsetX
offset.Y : MouseEvent.offsetY

Example

use-debounce-state

creates a bottleneck to the definition of a state, limits concurrency.

Module

import { useDebounceState } from "@atomico/hooks/use-debounce-state";

Syntax

this hook is similar to useState, but the purpose of this hook is to bottleneck the state at update time

const [state, setState] = useDebounceState(
    delay:number, 
    initialState: any,
    mode?: "fps" | "timeout" | "idle"
);

mode differences

fps:
1. if delay is set to 1, the update is executed for each cycle of requestAnimationFrame(60fps),
2. if delay is defined as 2, the update is executed for every 2 cycle of requestAnimationFrame(30fps)
timeout: the delay will be the milliseconds for setTimeout
idle : the delay will be the milliseconds for requestIdleCallback

Example

use-form

Communicate the component with external forms.

Module

import { 
    useForm, 
    useFormListener, 
    useFormInputHidden, 
    useFormInputRadio 
} from "@atomico/hooks/use-form";

useForm syntax

If the webcomponent is nested within a form tag, this hook will return that form tag as a reference.

const ref = useForm()

useFormListener syntax

If the webcomponent is nested within a form tag, you will be able to listen to events from that tag through useFormListener.

useFormListener("reset",handler);

useFormInputHidden syntax

el hook renderiza un input hidden en el lightDOM cuyo name y value del input seran los parametros que el hook resiva

useFormInputHidden("my-field","my-value");

useFormInputRadio

One of the difficult inputs to standardize when working with shadowDOM is the radio input, thanks to this hook you will be able to create and observe a radio input synchronized with the form and its webcomponent.

This hook requires the definition of the properties in its webcomponent:

myComponent.props = { name: String, checked: Boolean }

You can work with the input from the component logic, example:

const refInput = useFormInputRadio(<input slot="input" value="my-value"/>);

return <host>
    <slot name="input"/>
</host>;

Your component will automatically be reactive to the change of the states of the radio input

Example

use-responsive-state

Declare a state based on a responsive expression similar to using the tag img[srcset].

Module

import { useResponsiveState } from "@atomico/hooks/use-responsive-state";

Syntax

const expression = "phone, tablet 720px, destop 1080px";
const state = useResponsiveState(expression);

const state = useResponsiveState`
    phone, tablet 720px, destop 1080px
`;

Where:

state: String, Current state according to the comparison between experiment and matchMedia.
expression: String, An expression that declares the serialized states.

Expressions

"<defaultState>, <caseState> <size>"

Where:

defaultState: Default state this cannot contain the use of commas ", ".
caseState: Status to show if matchMedia match.
- size: size expression to observe, example:
  - "1080px": (min-width: 1080px)
  - "1080x720px": (min-width: 1080px) and (min-height: 720px)
  - "50rem": (min-width: 50rem)
  - "50em": (min-width: 50em)

Example

The following example shows the use of useResponsiveState, to display a message based on the mediaquery.

use-slot

Retrieves the nodes assigned to a slot.

useProxySlot

useProxySlot allows you to observe the nodes assigned to a slot and reassign them to another slot dynamically, example:

Input: Suppose we have a component that observe the slot[name="slide"] node

<my-component>
    <img slot="slide" src="slide-1"/>
    <img slot="slide" src="slide-1"/>
    <img slot="slide" src="slide-1"/>
</my-component>

output: thanks to useProxySlot you will be able to modify the assignment of the list nodes without losing the nodes in the process as normally happens with useSlot, example:

<my-component>
    <img slot="slide-1" src="slide-1"/>
    <img slot="slide-2" src="slide-1"/>
    <img slot="slide-3" src="slide-1"/>
</my-component>

Syntax and example

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

function component() {
  const ref = useRef();
  const children = useProxySlot(ref);

  return (
    <host shadowDom>
      <slot name="slide" ref={ref} />
      {children.map((child, index) => (
        <slot name={(child.slot = "slide-" + index)} />
      ))}
    </host>
  );
}

All redirected hooks must exist under a slot

Live example

useEvent

Dispatch events from the webcomponent without referencing the context(this)

Syntax

const dispatchEvent = useEvent(myEvent, eventInit);

Where:

dispatchEvent: callback, dispatches the event from the webcomponent and allows defining the detail by receiving a first parameter
myEvent: string, name of the event to dispatch.
eventInit: optional object, event configuration.

Examples

import { useEvent } from "atomico";

function component() {
  const dispatchEvent = useEvent("clickButton", {
    bubbles: true,
    composed: true,
  });
  return (
    <host>
      <button onclick={() => dispatchEvent()}>button</button>
    </host>
  );
}

import { useEvent } from "atomico";

function component() {
  const dispatchEvent = useEvent("clickButton", {
    bubbles: true,
    composed: true,
  });
  return (
    <host>
      <button onclick={() => {
        const detail = "my-component"; // 👈
        dispatchEvent(detail);         // 👈
      }}>button</button>
    </host>
  )c

import { Host, useEvent } from "atomico";

type DetailClickButton = {id: number};
//                             👇 declaration to associate event to JSX/TSX
function component():Host<{onclickButton: CustomEvent<DetailClickButton>}> {
//                             👇 type for detail
  const dispatchEvent = useEvent<DetailClickButton >("clickButton", {
    bubbles: true,
    composed: true,
  });
  return (
    <host>
      <button onclick={() => {
        //            👇 Detail
        dispatchEvent({id:100});
      }}>button</button>
    </host>
  );
}

Event customization

The second parameter of useEvent allows customizing the behavior of the even:

interface EventInit {
  // Allows the event to be dispatched upstream to the node's containers.
  bubbles?: boolean;
  // Allows the event to traverse the shadowDOM event capture.
  composed?: boolean;
  // Allows the event to be canceled.
  cancelable?: boolean;
  // Allows customizing the event builder, ideal for event instance-based communication.
  base?: Event | CustomEvent;
}

English

Atomico

API

Getting started with Atomico

Import

Webcomponent

Reactive properties and attributes of the webcomponent

Appearance of the webcomponent.

Definition of your webcomponent

Example

Getting started with Atomico for React users

How to declare a component?

How do you declare styles using Atomico?

Instances, children and slots

1. With Atomico you can instantiate CustomElements using its constructor

2. With Atomico you can instantiate components as functions as long as these are only stateless functions

What can you do with Atomico?

You can create design systems

Why use Atomico to create design systems?

Use cases

IBM IX

You can create websites

We recommend for SSR or SSG based sites

we recommend you for new projects

we recommend you for projects based on React

You can create mobile applications

You can create web applications

API

Props(Properties)

Syntax

Consider that:

Simple statements

Structured declaration

Prop.type

Prop.reflect

Prop.event

Prop.value

Reactivity in the scope of the webcomponent

Recommended articles

Advanced

Special properties

render

Constructor with custom element

Constructor with DOM

Dynamic constructor

staticNode

cloneNode

SSR hydration

Class name inheritance

Hooks

Hooks only for webcomponents

Hooks homogolates of React

@atomico/hooks

useProp

Syntax

Example

useRef

Syntax

Example

Observation

useHost

Syntax

Example

useReducer

useEffect, useLayoutEffect and useInsertionEffect

Syntax

Example

useLayoutEffect

useInsertionEffect

useId

Syntax

Example

useContext

createContext

useContext

Custom context values

When to use the Context API?

useProvider

Example of the useProvider hook:

Objective