Atomico Hooks Props
Developmentatomico-hooks-propsAtomico Hooks Props 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 useProp hook to create bidirectional bindings to component props. Triggers when the user needs to read AND write a component prop reactively from within the component, especially for two-way data flow or controlled input patterns. Do NOT confuse with regular props access via the render function parameter — useProp provides a setter.
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-props/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/atomico-hooks-props, 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.
useProp — Bidirectional Prop Binding
Overview
useProp provides a [value, setter] tuple for a declared prop, similar to
useState but synced with the component's public prop API. When you set a value
via useProp, it updates the actual property on the custom element instance,
making it visible to external consumers.
API
const [value, setValue] = useProp<T>(propName: string);
Usage
Basic Pattern
import { c, useProp } from "atomico";
const Toggle = c(
() => {
const [active, setActive] = useProp<boolean>("active");
return (
<host shadowDom>
<button onclick={() => setActive(!active)}>
{active ? "ON" : "OFF"}
</button>
</host>
);
},
{
props: {
active: {
type: Boolean,
reflect: true // Mirrors to HTML attribute
}
}
}
);
Controlled Input
const MyInput = c(
() => {
const [value = "", setValue] = useProp<string>("value");
return (
<host shadowDom>
<input
value={value}
oninput={({ currentTarget }) => {
setValue(currentTarget.value);
}}
/>
</host>
);
},
{
props: {
value: String
}
}
);
With Default Value Destructuring
When a prop may be undefined initially, use a default in destructuring:
const [value = 0, setValue] = useProp<number>("value");
Setter Variants
// Direct value
setValue(42);
// Functional update (receives current value)
setValue((prev = 0) => prev + 1);
// Reset to null/undefined
setValue(null);
setValue(undefined);
Multiple Prop Types
// Number
const [count = 0, setCount] = useProp<number>("count");
// Boolean
const [expanded, setExpanded] = useProp<boolean>("expanded");
setExpanded((prev) => !prev);
// Date
const [date, setDate] = useProp<Date>("date");
// Object
const [config, setConfig] = useProp<{ id: number }>("config");
setConfig({ id: config?.id || 0 });
// Callback
const [handler, setHandler] = useProp<(value: number) => number>("handler");
handler && handler(10);
// String with handler
const [, setValueFromHandler] = useProp<string>("value");
const handleChange = (event: Event) => {
setValueFromHandler(
(event.currentTarget as HTMLElement).getAttribute("value")
);
};
⚠️ Important Rules
-
useProp vs
event()for Component State: If you are emitting a change that represents the component's internal state (e.g. text value, open/close status, search query), do NOT use an isolatedevent(). Instead, useuseProp("propName"). By using thesetValue(newValue)setter fromuseProp, Atomico writes the value directly to the host element's property and natively fires an observer event. This allows consumers to write<Component onPropName={({currentTarget}) => console.log(currentTarget.propName)} />, leveraging full TypeScript inference. -
Prop must exist: The prop name passed to
usePropMUST be declared in the component'spropsconfiguration. Otherwise, aPropErroris thrown. -
useProp vs props parameter: Use
usePropwhen you need to write prop values from inside the component. Use thepropsfunction parameter when you only need to read.
// ✅ Read-only access — use props parameter
const MyComponent = c((props) => <host>{props.message}</host>, {
props: { message: String }
});
// ✅ Read/write access — use useProp
const MyComponent = c(() => {
const [message, setMessage] = useProp<string>("message");
return <host>{message}</host>;
}, {
props: { message: String }
});
- External visibility: When
usePropupdates a value, the change is reflected on the custom element instance (element.myProp = newValue), and ifreflect: true, on the HTML attribute as well.