AddressForm

The AddressForm component provides a pre-built UI for collecting billing address information. It integrates seamlessly with react-hook-form and includes built-in, country-specific validation for fields like postal codes.

This component is designed to be flexible, supporting both full address collection and a simplified version for Stripe postal code verification.

Props#

Prop	Type	Description	Default
mode	string	Determines the fields to display. Set to 'required' to show the complete address form (line 1, city, state, postal code, country).	undefined
stripe	boolean	If true, displays a simplified form with only the postal code and country, typically used for card validation with Stripe.	false
sx	SxProps	MUI's sx prop for custom styling of the root Stack component.	{}
fieldValidation	Record<string, any>	An object for providing custom validation rules, such as regex patterns, for specific fields. See the validation section for details.	{}
errorPosition	'right' | 'bottom'	Specifies where to display validation error messages relative to the input field.	'right'

Usage#

AddressForm must be used within a FormProvider from react-hook-form because it relies on its context to register fields and manage state.

Standard Billing Address#

To collect a full billing address, set the mode prop to 'required'. This will render all standard address fields, each with a 'required' validation rule.

import { FormProvider, useForm } from 'react-hook-form';
import { Button, Stack } from '@mui/material';
import AddressForm from './AddressForm'; // Adjust the import path

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

  const onSubmit = (data) => {
    console.log('Form data:', data);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <Stack spacing={2}>

This setup renders input fields for the address line, city, state, and postal code. The country is selected via the integrated CountrySelect component.

Stripe Postal Code Verification#

When using payment methods like Stripe, you often only need the postal code and country for card verification. Set the stripe prop to true to render a simplified form containing only these two fields.

import { FormProvider, useForm } from 'react-hook-form';
import { Button, Stack } from '@mui/material';
import AddressForm from './AddressForm'; // Adjust the import path

export default function StripeAddressExample() {
  const methods = useForm({
    defaultValues: {
      billing_address: {
        postal_code: '',
        country: 'US', // Default country
      },
    },
  });

  const onSubmit = (data) => {
    console.log('Form data:', data);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <Stack spacing={2}>
          <AddressForm stripe={true} />
          <Button type="submit" variant="contained">
            Submit

Validation#

The component includes automatic validation for required fields. The most notable feature is the dynamic postal code validation, which adjusts its rules based on the selected country.

• Required Fields: All visible fields are automatically marked as required.
• Postal Code: The validation logic uses the validator/lib/isPostalCode library. It checks the postal code format against the selected country's standard format (e.g., 5 digits for the US, alphanumeric for Canada). If a country's format is not explicitly supported, a general validation is applied.
• Custom Validation: You can pass additional validation rules via the fieldValidation prop. For example, to enforce a specific pattern on the state field:

const customValidation = {
  'billing_address.state': {
    pattern: '^[A-Z]{2}$',
    pattern_message: {
      en: 'State must be a 2-letter code.',
    },
  },
};

<AddressForm mode="required" fieldValidation={customValidation} />;