Atomico Hooks Core
Developmentatomico-hooks-coreAtomico Hooks Core 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.
Use core Atomico hooks: useState, useMemo, useCallback, useRef, useHost, useUpdate, useId, useHook. Triggers when the user needs local state management, memoization, DOM references, or access to the host element in Atomico components. Do NOT trigger for React hooks — Atomico hooks have the same API but run in a web component context with different lifecycle semantics.
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-hooks-core/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/atomico-hooks-core, 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.
Core Hooks
useState — Local Reactive State
Works identically to React's useState. Accepts an initial value or a factory
function. Returns [value, setter].
import { c, useState } from "atomico";
const Counter = c(() => {
const [count, setCount] = useState(0);
return (
<host>
<span>{count}</span>
<button onclick={() => setCount(count + 1)}>+</button>
<button onclick={() => setCount((prev) => prev - 1)}>-</button>
</host>
);
});
Type Inference
// Inferred as number
const [count, setCount] = useState(0);
// Explicit generic for undefined initial state
const [active, setActive] = useState<boolean>();
// Factory function — type inferred from return
const [items, setItems] = useState<string>(() => "welcome");
// Complex types
const [values, setValues] = useState<[number, number, number, number]>([1, 2, 3, 4]);
Setter Behavior
The setter only triggers an update if the new value is strictly different
(!==) from the current value.
setCount(5); // Direct value
setCount((prev) => prev + 1); // Functional update
useMemo — Memoized Computation
Caches the return of a callback. Only recomputes when dependencies change.
import { useMemo } from "atomico";
const expensive = useMemo(() => computeHeavyValue(data), [data]);
Type Inference
// Type inferred from callback return
const result = useMemo(() => 42, []); // number
const isValid = useMemo(() => {
return dateToValidate.getFullYear() === 2022;
}, [dateToValidate]); // boolean
useCallback — Memoized Function Reference
Shorthand for useMemo(() => callback, args). Returns the same function
reference until dependencies change.
import { useCallback } from "atomico";
const handler = useCallback(
(param: boolean) => param ? 10 : 0,
[dependency]
);
useRef — Persistent Mutable Reference
Creates a persistent reference object { current } that survives re-renders.
Commonly used for DOM element references.
import { c, useRef } from "atomico";
const MyComponent = c(() => {
const inputRef = useRef<HTMLInputElement>();
return (
<host shadowDom>
<input ref={inputRef} />
<button onclick={() => inputRef.current?.focus()}>
Focus
</button>
</host>
);
});
Typed Refs for Atomico Components
import { useRef } from "atomico";
import { MyChild } from "./my-child.js";
// Use typeof to get the constructor type
const childRef = useRef<typeof MyChild>();
childRef.current?.myProp; // Full type inference on component props
useHost — Access the Host Element
Returns a ref to the host custom element. Essential for accessing the DOM node, dispatching events, or manipulating the element itself.
import { c, useHost } from "atomico";
const MyComponent = c(() => {
const host = useHost();
// Access the host element
host.current.updated.then(() => {
console.log("Component rendered!");
});
return <host><p>Hello</p></host>;
});
Note:
useHost()returns{ current: HTMLElement }— thecurrentproperty always points to the web component instance.
useUpdate — Force Re-render
Returns the component's update function. Calling it triggers a re-render without changing any state.
import { c, useUpdate } from "atomico";
const MyComponent = c(() => {
const update = useUpdate();
return (
<host>
<button onclick={() => update()}>Force re-render</button>
</host>
);
});
useId — Stable Unique Identifier
Generates a unique, stable ID for the current hook position. Useful for accessibility attributes.
import { c, useId } from "atomico";
const MyComponent = c(() => {
const id = useId();
return (
<host shadowDom>
<label for={id}>Name</label>
<input id={id} />
</host>
);
});
useHook — Low-Level Custom Hook Primitive
The foundational hook for building custom hooks. Manages persistent state across renders using a callback pattern.
import { useHook } from "atomico";
const useMyCustomHook = () => {
return useHook((state = { count: 0 }) => {
state.count++;
return state;
});
};
Advanced:
useHookis the building block foruseState,useMemo, and all other hooks. Use it when none of the built-in hooks fit your needs.