OpenParable
Skip to content
← Back to skills

Atomico Hooks Props

Development
atomico-hooks-props

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

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

  1. 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 isolated event(). Instead, use useProp("propName"). By using the setValue(newValue) setter from useProp, 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.

  2. Prop must exist: The prop name passed to useProp MUST be declared in the component's props configuration. Otherwise, a PropError is thrown.

  3. useProp vs props parameter: Use useProp when you need to write prop values from inside the component. Use the props function 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 }
});
  1. External visibility: When useProp updates a value, the change is reflected on the custom element instance (element.myProp = newValue), and if reflect: true, on the HTML attribute as well.