atomico-hooks-props

name	atomico-hooks-props
description	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.
license	MIT
compatibility	Atomico >=1.79
metadata	{"category":"hooks","priority":"high"}

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 }
});

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