React

@biaspay/react provides React components and hooks for Bias Elements. It requires React 19 or later and the matching React DOM major.

Install

npm install @biaspay/react

@biaspay/elements and @biaspay/sdk are installed as runtime dependencies. React 18 is not supported because the wrappers use React 19’s native custom-element property and event handling.

Basic checkout

import { BiasProvider, ContactElement, PaymentElement, SubmitButton } from "@biaspay/react";

export function Checkout({ clientSecret }: { clientSecret: string }) {
    return (
        <BiasProvider
            clientSecret={clientSecret}
            appearance={{ variables: { colorPrimary: "#4f46e5" } }}
            onComplete={() => location.assign("/complete")}
        >
            <ContactElement />
            <PaymentElement paymentMethodLayout="tabs" />
            <SubmitButton label="Pay now" />
        </BiasProvider>
    );
}

Create the checkout session on your server. See the Elements quickstart for the complete server and client flow.

BiasProvider

type BiasProviderProps = {
    clientSecret: string;
    initialCheckoutSession?: CheckoutSession;
    appearance?: Appearance;
    onComplete?: () => void;
    children: React.ReactNode;
};

initialCheckoutSession is a one-time hydration seed. Its client_secret must match clientSecret. The provider shows a matching seed after browser activation and refreshes it from the API; later seed changes for the same client secret are ignored.

Changing clientSecret starts a new session and resets session-owned state. Changes to appearance and onComplete apply in place.

Components

Use exactly one of the three payment components under a provider. paymentMethodLayout defaults to "tabs"; AddressElement.scope defaults to "billing". SubmitButton inherits the provider appearance and derives its default label and amount from the checkout session.

See components and appearance for composition, address behavior, and theme variables.

useBias

useBias() reads checkout state and returns actions. It must be called under BiasProvider.

const { sessionState, paymentMethod, setPaymentMethod, status, canSubmit, submissionError, submit, refreshSession } =
    useBias();

setPaymentMethod(method), submit(), and refreshSession() are actions. submit() runs validation and creates the payment when validation passes; duplicate calls during submission or after success are ignored.

useBiasField

useBiasField(name, options?) binds to a non-sensitive provider field:

const email = useBiasField("email", {
    validate: (value) => ({
        isValid: value.includes("@"),
        error: value.includes("@") ? null : "Enter a valid email.",
    }),
});

email.state; // { value, isFocused, isValid, error }
email.setValue("shopper@example.com");
email.validate();
email.onFocus();
email.onBlur();

The hook does not register a field for collection. Keep the matching ContactElement or AddressElement mounted when the field must be required, autosaved, and submitted. Sensitive card and bank account fields are never exposed. See custom controls and fields.

Errors and retries

BiasElementsError extends Error with a code and retryable boolean. Codes are:

• authentication_failed
• session_load_failed
• session_update_failed
• payment_failed
• frame_failed
• configuration_error

Submission errors remain in submissionError and can be shown inline. A refresh error that retains a usable session appears in sessionState with both error and session; call refreshSession() to retry. A terminal load or configuration error is thrown to the nearest React error boundary. Reset the boundary and remount the provider to retry.

Server rendering

The package entry is safe to import during SSR. BiasProvider renders no Elements UI on the server or during the first hydration pass, then activates in the browser. Place any loading skeleton outside the provider if the checkout must reserve space before activation.

Exports

The package exports BiasProvider, useBias, useBiasField, and the six child components above. It also exports named prop types, UseBiasResult, and shared types for appearance, checkout state, errors, fields, and address metadata. CheckoutSession remains owned by @biaspay/sdk and is not re-exported.