OpenParable
Skip to content
← Back to skills

Atomico Component

Development
atomico-component

Atomico Component is an Agent Skill for development published in the atomicojs/atomico repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Create Atomico web components using the `c()` function. Triggers when the user needs to create a new custom element, define reactive props, attach styles, or register a component with `customElements.define`. Do NOT trigger for React, Vue, or Angular component creation. Atomico components are functional web components that return JSX with a mandatory `<host>` root element.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/atomicojs/atomico/blob/HEAD/.agents/skills/atomico-component/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/atomico-component, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Atomico Component Creation — c()

Overview

c() is the core function to create web components in Atomico. It receives a render function and an optional configuration object with props, styles, and form.

import { c, css } from "atomico";

const MyComponent = c(
    (props) => (
        <host shadowDom>
            <h1>{props.message}</h1>
        </host>
    ),
    {
        props: {
            message: { type: String, value: () => "Hello" }
        },
        styles: css`:host { display: block; }`
    }
);

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

Critical Rules

1. Always return <host> as root

Every Atomico component MUST return <host> as the outermost JSX element. <host> maps to the custom element itself.

// ✅ Correct
const MyComponent = c(() => <host><h1>Hello</h1></host>);

// ❌ Wrong — never return a div or fragment as root
const MyComponent = c(() => <div>Hello</div>);

2. Prefer Constructor Instances in JSX

Always use the constructor reference (e.g., <MyChild />) instead of the tag-name string (<my-child />) when composing components in JSX. This enables:

  • Full type inference for props, events, and methods
  • Instance dependency tracking — the bundler knows about the relationship
  • Autocompletion in IDEs for all declared props and events
// ✅ Preferred — types are inferred, props are validated
<TodoTask message="Do laundry" checked={false} onchangeTask={handler} />

// ⚠️ Avoid — no type inference, no prop validation
<todo-task message="Do laundry"></todo-task>

3. Props Declaration Patterns

Props can be declared in shorthand or detailed form:

{
    props: {
        // Shorthand — type only, value is undefined until set
        name: String,
        count: Number,
        active: Boolean,
        items: Array,
        config: Object,

        // Detailed — with default value, reflection, etc.
        message: {
            type: String,
            value: () => "default",  // Factory function for default
            reflect: true,           // Mirrors to HTML attribute
            attr: "custom-attr"      // Custom attribute name
        },

        // Custom type (e.g., another component constructor)
        child: {
            type: MyOtherComponent,
            value: () => new MyOtherComponent()
        },

        // Promise type with typed return
        data: {
            type: Promise,
            value: async (): Promise<number[]> => []
        }
    }
}

4. Supported Prop Types

TypeJS TypeAttribute Parsing
StringstringDirect string
NumbernumberNumber(value)
BooleanbooleanPresence = true
Arrayany[]JSON.parse
ObjectobjectJSON.parse
DateDatenew Date(value)
MapMapnew Map(value)
PromisePromiseN/A
FunctionfunctionN/A
Custom Classinstancenew Type(value)
null (Any)anyNo validation

5. Styles with css Tagged Template

import { c, css } from "atomico";

const MyComponent = c(
    () => (
        <host shadowDom>
            <slot />
        </host>
    ),
    {
        styles: css`
            :host {
                display: block;
                padding: 1rem;
            }
            ::slotted(*) {
                margin: 0.5rem;
            }
        `
    }
);

Note: Styles use adoptedStyleSheets and are cached by CSS text. They require shadowDom to be enabled on <host>.

6. Events with event() and callback()

import { c, event, callback } from "atomico";

const MyComponent = c(
    (props) => (
        <host shadowDom>
            <button onclick={() => props.change({ id: 1 })}>
                Dispatch event
            </button>
        </host>
    ),
    {
        props: {
            // Dispatches a CustomEvent — listen with `onchange` in JSX
            change: event<{ id: number }>({ bubbles: true, composed: true }),
            // Function prop — parent provides logic, child invokes it
            processMarkdown: callback<() => Promise<string>>()
        }
    }
);

// Consuming with JSX (constructor instance):
<MyComponent
    onchange={({ detail }) => console.log(detail.id)}
    processMarkdown={() => Promise.resolve("# Hello")}
/>;

7. Form-Associated Components

const MyInput = c(
    ({ name }) => {
        const [value, setValue] = useFormProps();
        return (
            <host shadowDom={{ delegatesFocus: true }}>
                <input
                    value={value}
                    oninput={({ currentTarget }) => setValue(currentTarget.value)}
                />
            </host>
        );
    },
    {
        form: true,          // Enables formAssociated
        props: {
            name: String,
            value: String
        }
    }
);

8. Component without Props

const SimpleComponent = c(() => <host><p>No props needed</p></host>);
customElements.define("simple-component", SimpleComponent);

9. ShadowDOM Options

// Simple shadowDom
<host shadowDom>...</host>

// With options
<host shadowDom={{ slotAssignment: "manual", delegatesFocus: true }}>...</host>

Anti-Patterns

  • ❌ Using document.createElement instead of JSX constructors
  • ❌ Returning anything other than <host> from the render function
  • ❌ Mutating props directly — props are read-only in the render function
  • ❌ Using string tag names in JSX when the constructor is available in scope
  • ❌ Defining value as a plain value instead of a factory function