Atomico Hooks Forms

Note: attachInternals() is called once per element instance and cached.

useFormProps — Bidirectional Form Value

Combines useProp for both name and value props with automatic FormData submission and form reset handling.

API

const [value, setValue] = useFormProps(propName?, propValue?);
// Defaults: propName = "name", propValue = "value"

Usage

import { c, useFormProps, useFormValidity, useRef, css } from "atomico";
import { delegateValidity } from "atomico/utils";

const MyInput = c(
    ({ name }) => {
        const [value = "", setValue] = useFormProps();
        const inputRef = useRef<HTMLInputElement>();

        const [, validity] = useFormValidity(
            () => delegateValidity(inputRef.current),
            [value]
        );

        return (
            <host shadowDom={{ delegatesFocus: true }}>
                <label>
                    <span>
                        {!validity.valid && "🔴"}
                        {name}
                    </span>
                    <input
                        value={value}
                        ref={inputRef}
                        oninput={({ currentTarget }) => {
                            setValue(currentTarget.value);
                        }}
                        required
                        minLength={3}
                    />
                </label>
            </host>
        );
    },
    {
        form: true,
        props: {
            name: String,
            value: String
        },
        styles: css`
            :host { display: block; }
            label { display: grid; padding: 0.5rem 0; }
        `
    }
);

What it Does

1. Reads name and value via useProp
2. On value change, calls internals.setFormValue() with the name/value pair
3. On form reset, clears the value to null

useFormValidity — Form Validation

Integrates with the browser's native constraint validation API through ElementInternals.setValidity().

API

const [message, validity] = useFormValidity(callback, args);

Parameters

• callback: Returns { message, report?, ...ValidityStateFlags }
• args: Dependency array — validation re-runs when these change

With delegateValidity Utility

The delegateValidity utility (from atomico/utils) reads validation state from a native input and formats it for useFormValidity:

import { delegateValidity } from "atomico/utils";

const [message, validity] = useFormValidity(
    () => delegateValidity(inputRef.current),
    [value]
);

// validity.valid — boolean
// message — current validation message

Custom Validation

const [message, validity] = useFormValidity(
    () => ({
        message: value.length < 3 ? "Minimum 3 characters" : "",
        customError: value.length < 3,
        report: true  // Auto-report on invalid
    }),
    [value]
);

Validation on Submit

useFormValidity automatically hooks into form submit events. When the form is submitted:

1. state.report is set to true
2. The validation callback re-runs
3. If invalid, event.preventDefault() is called
4. reportValidity() shows the native validation UI

useFormValue — Manual FormData Control

Lower-level hook for manually managing form data submission values.

API

const [value, setValue] = useFormValue(propName: string);

Usage

const [value, setValue] = useFormValue("rating");

// Sets both the display state and the FormData value
setValue(5);

useFormSubmit — Listen to Form Submit

Attaches a listener to the associated form's submit event.

import { c, useFormSubmit } from "atomico";

const MyInput = c(
    () => {
        useFormSubmit((event) => {
            console.log("Form submitted!", event);
        });
        return <host />;
    },
    { form: true }
);

useFormReset — Handle Form Reset

Registers a callback for when the form is reset.

import { c, useFormReset, useProp } from "atomico";

const MyInput = c(
    () => {
        const [value, setValue] = useProp<string>("value");

        useFormReset(() => {
            setValue(null);  // Clear on reset
        });

        return <host />;
    },
    { form: true, props: { value: String } }
);

useFormAssociated — Form Association Callback

Fires when the component is associated with a form element.

useFormAssociated((form) => {
    console.log("Associated with form:", form);
});

useFormDisabled — Disabled State Callback

Fires when the component's disabled state changes via <fieldset disabled>.

useFormDisabled((disabled) => {
    console.log("Disabled:", disabled);
});

Complete Login Form Example

import { c, useFormProps, useFormValidity, useRef, useState, css } from "atomico";
import { delegateValidity } from "atomico/utils";

const MyInput = c(
    ({ name }) => {
        const [value = "", setValue] = useFormProps();
        const ref = useRef<HTMLInputElement>();
        const [, validity] = useFormValidity(
            () => delegateValidity(ref.current),
            [value]
        );

        return (
            <host shadowDom={{ delegatesFocus: true }}>
                <label>
                    <span>{!validity.valid && "🔴"} {name}</span>
                    <input
                        value={value}
                        ref={ref}
                        oninput={({ currentTarget }) => setValue(currentTarget.value)}
                        required
                        minLength={3}
                    />
                </label>
            </host>
        );
    },
    {
        form: true,
        props: { name: String, value: String },
        styles: css`
            :host { display: block; }
            label { display: grid; padding: 0.5rem 0; }
        `
    }
);

const MyLogin = c(
    () => {
        const [data, setData] = useState();
        return (
            <host shadowDom>
                <form oninput={({ currentTarget }) => {
                    setData(Object.fromEntries(
                        new FormData(currentTarget as HTMLFormElement)
                    ));
                }}>
                    <MyInput name="user" />
                    <MyInput name="password" />
                    <button type="submit">Login</button>
                </form>
                <code>{JSON.stringify(data)}</code>
            </host>
        );
    },
    { styles: css`:host { display: grid; }` }
);