Custom controls and fields

Use the public state API to build submission controls, surface errors, prefill fields, or coordinate Elements with the rest of your checkout.

Build a submit control

React hooks return current values:

import { useBias } from "@biaspay/react";

function PayButton() {
    const { status, submissionError, submit } = useBias();

    return (
        <>
            {submissionError && <p role="alert">{submissionError.message}</p>}
            <button type="button" disabled={status === "submitting" || status === "succeeded"} onClick={submit}>
                {status === "submitting" ? "Paying…" : "Pay now"}
            </button>
        </>
    );
}

Solid exposes changing values as accessors and actions as plain functions:

import { useBias } from "@biaspay/solid";

function PayButton() {
    const bias = useBias();

    return (
        <>
            {bias.submissionError() && <p role="alert">{bias.submissionError()!.message}</p>}
            <button
                type="button"
                disabled={bias.status() === "submitting" || bias.status() === "succeeded"}
                onClick={bias.submit}
            >
                {bias.status() === "submitting" ? "Paying…" : "Pay now"}
            </button>
        </>
    );
}

For web components, read provider.canSubmit and call provider.submit(). Subscribe to biaschange to update your control whenever state changes.

canSubmit is true when every currently required field is valid. Calling submit() while it is false still runs validation and reveals field errors, so only disable your custom control if validation already appears through another interaction.

Work with host-field state

useBiasField(name) in React and Solid, and provider.getField(name) with web components, return the binding for a non-sensitive field. A binding includes:

• state: value, isFocused, isValid, and error.
• setValue(value) and validate().
• onFocus() and onBlur() for focus state and blur validation.
• An optional custom validator.

For example, prefill the ContactElement email from your application:

import { useEffect } from "react";
import { useBiasField } from "@biaspay/react";

function PrefillEmail({ email }: { email: string }) {
    const field = useBiasField("email");

    useEffect(() => {
        field.setValue(email);
    }, [email, field.setValue]);

    return null;
}

useBiasField and getField bind to provider state; they do not register a contact or address field for collection. Keep the corresponding ContactElement or AddressElement mounted when that value must be required, autosaved, and included in checkout.

Available field names

All values are strings except accountType, which is "checking" | "savings".

Sensitive payment fields

Card number, expiry, CVC, bank routing number, and bank account number are intentionally absent from the field API. They cannot be read or set by host JavaScript. Always collect them with one supported payment surface.