Atomico Component
Developmentatomico-componentAtomico 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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
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
| Type | JS Type | Attribute Parsing |
|---|---|---|
String | string | Direct string |
Number | number | Number(value) |
Boolean | boolean | Presence = true |
Array | any[] | JSON.parse |
Object | object | JSON.parse |
Date | Date | new Date(value) |
Map | Map | new Map(value) |
Promise | Promise | N/A |
Function | function | N/A |
| Custom Class | instance | new Type(value) |
null (Any) | any | No 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
adoptedStyleSheetsand are cached by CSS text. They requireshadowDomto 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.createElementinstead 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
valueas a plain value instead of a factory function