Components

AddressForm

The AddressForm component provides a pre-built UI for collecting billing address details. It includes fields for address line 1, city, state, postal code, and country, with built-in validation that adapts based on the selected country.
This component must be used within a FormProvider from react-hook-form.
Props#Prop
Type
Description
Required
mode
string
Determines the form's behavior. Set to 'required' to display the full address form.
Yes
stripe
boolean
If true and mode is not 'required', it displays a simplified form with only postal code and country.
Yes
sx
SxProps
Custom MUI styles to be applied to the root Stack component.
No
fieldValidation
Record<string, any>
An object for providing custom validation rules, such as regex patterns, for specific fields.
No
errorPosition
'right' | 'bottom'
Specifies the position of validation error messages relative to the input fields. Defaults to 'right'.
No
Integration with React Hook Form#Since AddressForm uses useFormContext, it must be a child of a FormProvider component. You need to set up the form methods and wrap your form content, including the AddressForm, with the provider.
import { FormProvider, useForm } from 'react-hook-form';
import { AddressForm } from '@blocklet/payment-react';

function MyCheckoutPage() {
  const methods = useForm({
    defaultValues: {
      billing_address: {
        line1: '',
        city: '',
        state: '',
        postal_code: '',
        country: 'US', // Default country
      },
    },
  });

  const onSubmit = (data) => {
    console.log(data);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <AddressForm mode="required" stripe={false} />
        <button type="submit">Submit</button>
      </form>
    </FormProvider>
  );
}Usage Scenarios#Complete Address Form#To collect a full billing address, set the mode prop to 'required'. This will render all address fields, and each field will be mandatory.
import { FormProvider, useForm } from 'react-hook-form';
import { AddressForm } from '@blocklet/payment-react';
import { Button, Stack } from '@mui/material';

export default function FullAddressFormExample() {
  const methods = useForm({
    mode: 'onTouched',
    defaultValues: {
      billing_address: {
        line1: '',
        city: '',
        state: '',
        postal_code: '',
        country: 'US',
      },
    },
  });

  const onSubmit = (data) => {
    alert('Form Submitted! Check console for data.');
    console.log('Billing Address:', data.billing_address);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <Stack spacing={2}>
          <AddressForm mode="required" stripe={false} errorPosition="bottom" />
          <Button type="submit" variant="contained">
            Submit Address
          </Button>
        </Stack>
      </form>
    </FormProvider>
  );
}Simplified Stripe Form#In some payment flows, particularly with Stripe, only the postal code and country are required for verification. To render this simplified version, ensure mode is not 'required' and set the stripe prop to true.
import { FormProvider, useForm } from 'react-hook-form';
import { AddressForm } from '@blocklet/payment-react';
import { Button, Stack } from '@mui/material';

export default function StripeAddressFormExample() {
  const methods = useForm({
    mode: 'onTouched',
    defaultValues: {
      billing_address: {
        postal_code: '',
        country: 'US',
      },
    },
  });

  const onSubmit = (data) => {
    alert('Form Submitted! Check console for data.');
    console.log('Billing Info:', data.billing_address);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <Stack spacing={2}>
          <AddressForm mode="optional" stripe={true} errorPosition="bottom" />
          <Button type="submit" variant="contained">
            Submit
          </Button>
        </Stack>
      </form>
    </FormProvider>
  );
}Validation#AddressForm handles validation for required fields automatically. It also includes special validation logic for postal codes.
Postal Code Validation#The postal code field is dynamically validated based on the selected country. The component uses the validator.js library to check if the postal code format is valid for the chosen country. For countries not on the supported list, a generic validation is applied.
Custom Validation#You can extend the default validation by passing a fieldValidation object. This allows you to specify custom regex patterns and error messages for any address field.
For example, to add a pattern validation for the state field:
const customValidation = {
  'billing_address.state': {
    pattern: '^[A-Z]{2}$',
    pattern_message: {
      en: 'State must be a 2-letter abbreviation.',
    },
  },
};

<AddressForm
  mode="required"
  stripe={false}
  fieldValidation={customValidation}
/>Related Components#CountrySelect: The AddressForm uses this component internally to provide a searchable, user-friendly country dropdown with flags.

Prop	Type	Description	Required
`mode`	`string`	Determines the form's behavior. Set to `'required'` to display the full address form.	Yes
`stripe`	`boolean`	If `true` and `mode` is not `'required'`, it displays a simplified form with only postal code and country.	Yes
`sx`	`SxProps`	Custom MUI styles to be applied to the root `Stack` component.	No
`fieldValidation`	`Record<string, any>`	An object for providing custom validation rules, such as regex patterns, for specific fields.	No
`errorPosition`	`'right'` \| `'bottom'`	Specifies the position of validation error messages relative to the input fields. Defaults to `'right'`.	No

Overview

Getting Started

Providers

Components

Guides

Hooks

AddressForm

Props#

Integration with React Hook Form#

Usage Scenarios#

Complete Address Form#

Simplified Stripe Form#

Validation#

Postal Code Validation#

Custom Validation#

Form Elements

PhoneInput