Address and Contact Elements

/**
 * Address collection element with international support
 * @param props - Address element configuration props
 * @returns JSX element for address collection
 */
function AddressElement(props: AddressElementProps): JSX.Element;

interface AddressElementProps extends ElementProps {
  /** Configuration options for the Address Element - REQUIRED */
  options: StripeAddressElementOptions;
  /** Triggered when data exposed by this Element is changed */
  onChange?: (event: StripeAddressElementChangeEvent) => any;
  /** Triggered when the Element is fully rendered and can accept focus */
  onReady?: (element: StripeAddressElement) => any;
  /** Triggered when the escape key is pressed within the Element */
  onEscape?: () => any;
  /** Triggered when the Element fails to load */
  onLoadError?: (event: {elementType: 'address'; error: StripeError}) => any;
  /** Triggered when the loader UI is mounted to the DOM */
  onLoaderStart?: (event: {elementType: 'address'}) => any;
}

interface StripeAddressElementOptions {
  /** Address collection mode */
  mode?: 'shipping' | 'billing';
  /** Whether to allow PO Boxes */
  allowedCountries?: string[];
  /** Block PO Box addresses */
  blockPoBox?: boolean;
  /** Fields to collect */
  fields?: {
    phone?: 'auto' | 'always' | 'never';
  };
  /** Address validation options */
  validation?: {
    mode?: 'auto' | 'always' | 'never';
  };
  /** Default values */
  defaultValues?: {
    name?: string;
    address?: {
      line1?: string;
      line2?: string;
      city?: string;
      state?: string;
      postal_code?: string;
      country?: string;
    };
    phone?: string;
  };
  /** Autocomplete configuration */
  autocomplete?: {
    mode?: 'automatic' | 'disabled';
  };
}

import React, { useState } from 'react';
import { AddressElement, useStripe, useElements } from '@stripe/react-stripe-js';

const ShippingForm = () => {
  const stripe = useStripe();
  const elements = useElements();
  const [addressComplete, setAddressComplete] = useState(false);
  const [addressData, setAddressData] = useState(null);

  const handleAddressChange = (event) => {
    setAddressComplete(event.complete);
    if (event.complete) {
      setAddressData(event.value);
    }
  };

  const handleSubmit = async (event) => {
    event.preventDefault();

    if (!stripe || !elements || !addressComplete) return;

    const address = elements.getElement(AddressElement);
    
    // Get the address data
    const {error, complete, value} = await address.getValue();
    
    if (error) {
      console.log('[Address error]', error);
    } else if (complete) {
      console.log('[Address]', value);
      // Use address data in payment or shipping
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <h3>Shipping Address</h3>
      <AddressElement
        options={{
          mode: 'shipping',
          allowedCountries: ['US', 'CA', 'GB', 'AU'],
          fields: {
            phone: 'always'
          },
          validation: {
            mode: 'auto'
          },
          defaultValues: {
            name: 'Jenny Rosen',
            address: {
              country: 'US'
            }
          }
        }}
        onChange={handleAddressChange}
        onReady={() => console.log('AddressElement ready')}
      />
      <button disabled={!stripe || !addressComplete}>
        Continue to Payment
      </button>
    </form>
  );
};

// Billing address variant
const BillingAddressForm = () => (
  <AddressElement
    options={{
      mode: 'billing',
      fields: {
        phone: 'never'
      },
      blockPoBox: true
    }}
    onChange={(event) => {
      if (event.complete) {
        console.log('Billing address complete:', event.value);
      }
    }}
  />
);

/**
 * Link authentication element for Stripe Link integration
 * @param props - Link authentication element configuration props
 * @returns JSX element for Link authentication
 */
function LinkAuthenticationElement(props: LinkAuthenticationElementProps): JSX.Element;

interface LinkAuthenticationElementProps extends ElementProps {
  /** Configuration options for the Link Authentication Element */
  options?: StripeLinkAuthenticationElementOptions;
  /** Triggered when data exposed by this Element is changed */
  onChange?: (event: StripeLinkAuthenticationElementChangeEvent) => any;
  /** Triggered when the Element is fully rendered and can accept focus */
  onReady?: (element: StripeLinkAuthenticationElement) => any;
  /** Triggered when the escape key is pressed within the Element */
  onEscape?: () => any;
  /** Triggered when the Element fails to load */
  onLoadError?: (event: {elementType: 'linkAuthentication'; error: StripeError}) => any;
  /** Triggered when the loader UI is mounted to the DOM */
  onLoaderStart?: (event: {elementType: 'linkAuthentication'}) => any;
}

interface StripeLinkAuthenticationElementOptions {
  /** Default email value */
  defaultValues?: {
    email?: string;
  };
}

import React, { useState } from 'react';
import { LinkAuthenticationElement, PaymentElement } from '@stripe/react-stripe-js';

const LinkPaymentForm = () => {
  const [email, setEmail] = useState('');
  const [linkAccount, setLinkAccount] = useState(null);

  const handleLinkChange = (event) => {
    setEmail(event.value.email);
    
    if (event.complete) {
      // User has authenticated with Link
      setLinkAccount(event.value);
      console.log('Link authenticated:', event.value);
    }
  };

  return (
    <form>
      <LinkAuthenticationElement
        options={{
          defaultValues: {
            email: 'customer@example.com'
          }
        }}
        onChange={handleLinkChange}
        onReady={() => console.log('LinkAuthenticationElement ready')}
      />
      
      {/* PaymentElement will automatically integrate with Link if authenticated */}
      <PaymentElement />
      
      <button disabled={!email}>
        Pay {linkAccount ? 'with Link' : 'Now'}
      </button>
    </form>
  );
};

/**
 * Tax ID collection element for business identification
 * Requires beta access - contact Stripe support for more information
 * @param props - Tax ID element configuration props
 * @returns JSX element for tax ID collection
 */
function TaxIdElement(props: TaxIdElementProps): JSX.Element;

interface TaxIdElementProps extends ElementProps {
  /** Configuration options for the Tax ID Element */
  options: StripeTaxIdElementOptions;
  /** Triggered when data exposed by this Element is changed */
  onChange?: (event: StripeTaxIdElementChangeEvent) => any;
  /** Triggered when the Element is fully rendered and can accept focus */
  onReady?: (element: StripeTaxIdElement) => any;
  /** Triggered when the escape key is pressed within the Element */
  onEscape?: () => any;
  /** Triggered when the Element fails to load */
  onLoadError?: (event: {elementType: 'taxId'; error: StripeError}) => any;
  /** Triggered when the loader UI is mounted to the DOM */
  onLoaderStart?: (event: {elementType: 'taxId'}) => any;
}

interface StripeTaxIdElementOptions {
  /** Supported tax ID types */
  supportedTypes?: Array<{
    type: string;
    country: string;
  }>;
  /** Default values */
  defaultValues?: {
    type?: string;
    value?: string;
  };
}

import React, { useState } from 'react';
import { TaxIdElement } from '@stripe/react-stripe-js';

const BusinessTaxForm = () => {
  const [taxIdComplete, setTaxIdComplete] = useState(false);
  const [taxIdData, setTaxIdData] = useState(null);

  const handleTaxIdChange = (event) => {
    setTaxIdComplete(event.complete);
    if (event.complete) {
      setTaxIdData(event.value);
    }
  };

  return (
    <form>
      <h3>Business Tax Information</h3>
      <TaxIdElement
        options={{
          supportedTypes: [
            { type: 'us_ein', country: 'US' },
            { type: 'eu_vat', country: 'DE' },
            { type: 'ca_bn', country: 'CA' }
          ],
          defaultValues: {
            type: 'us_ein'
          }
        }}
        onChange={handleTaxIdChange}
        onReady={() => console.log('TaxIdElement ready')}
      />
      {taxIdData && (
        <div>
          Tax ID: {taxIdData.type} - {taxIdData.value}
        </div>
      )}
      <button disabled={!taxIdComplete}>
        Submit Business Information
      </button>
    </form>
  );
};

/**
 * @deprecated Use AddressElement with mode: 'shipping' instead
 * Legacy shipping address element
 */
function ShippingAddressElement(props: ShippingAddressElementProps): JSX.Element;

interface ShippingAddressElementProps extends ElementProps {
  options?: StripeShippingAddressElementOptions;
  onChange?: (event: StripeShippingAddressElementChangeEvent) => any;
  onReady?: (element: StripeShippingAddressElement) => any;
  onEscape?: () => any;
  onLoadError?: (event: {elementType: 'shippingAddress'; error: StripeError}) => any;
  onLoaderStart?: (event: {elementType: 'shippingAddress'}) => any;
}

interface StripeAddressElementChangeEvent {
  elementType: 'address';
  empty: boolean;
  complete: boolean;
  isValidAddress?: boolean;
  value: {
    name: string;
    address: {
      line1: string;
      line2?: string;
      city: string;
      state: string;
      postal_code: string;
      country: string;
    };
    phone?: string;
  };
}

interface StripeLinkAuthenticationElementChangeEvent {
  elementType: 'linkAuthentication';
  empty: boolean;
  complete: boolean;
  value: {
    email: string;
  };
}

interface StripeTaxIdElementChangeEvent {
  elementType: 'taxId';
  empty: boolean;
  complete: boolean;
  value: {
    type: string;
    value: string;
  };
}

// Address validation example
const ValidatedAddressForm = () => {
  const [validationResult, setValidationResult] = useState(null);

  const handleAddressChange = (event) => {
    if (event.complete) {
      // Address is complete, validation results available
      setValidationResult({
        isValid: event.isValidAddress,
        address: event.value.address,
        suggestions: event.value.suggestions || []
      });
    }
  };

  return (
    <div>
      <AddressElement
        options={{
          mode: 'shipping',
          validation: {
            mode: 'auto' // Automatically validate addresses
          },
          autocomplete: {
            mode: 'automatic' // Enable address autocomplete
          }
        }}
        onChange={handleAddressChange}
      />
      
      {validationResult && !validationResult.isValid && (
        <div className="address-warning">
          Address may be invalid. Please verify the details.
        </div>
      )}
    </div>
  );
};