or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

address-elements.mdbank-elements.mdcard-elements.mdcheckout-components.mdcore-providers-hooks.mdembedded-checkout.mdindex.mdmessage-elements.mdpayment-elements.md
tile.json

tessl/npm-stripe--react-stripe-js

React components and hooks for Stripe.js and Elements payment processing integration

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@stripe/react-stripe-js@4.0.x

To install, run

npx @tessl/cli install tessl/npm-stripe--react-stripe-js@4.0.0

index.mddocs/

React Stripe.js

React Stripe.js provides official React components and hooks for Stripe.js and Elements, enabling developers to build secure payment interfaces in React applications. It offers a comprehensive set of Element components for different payment methods, context providers for managing Stripe instances, and React hooks for accessing payment functionality.

Package Information

  • Package Name: @stripe/react-stripe-js
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @stripe/react-stripe-js @stripe/stripe-js

Core Imports

import {
  Elements,
  useStripe,
  useElements,
  PaymentElement,
  CardElement
} from "@stripe/react-stripe-js";

For checkout-specific features:

import {
  CheckoutProvider,
  useCheckout,
  BillingAddressElement,
  ShippingAddressElement
} from "@stripe/react-stripe-js/checkout";

CommonJS:

const {
  Elements,
  useStripe,
  useElements,
  PaymentElement,
  CardElement
} = require("@stripe/react-stripe-js");

Basic Usage

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

const stripePromise = loadStripe('pk_test_...');

const CheckoutForm = () => {
  const stripe = useStripe();
  const elements = useElements();
  const [isLoading, setIsLoading] = useState(false);

  const handleSubmit = async (event) => {
    event.preventDefault();
    
    if (!stripe || !elements) return;
    
    setIsLoading(true);
    
    const { error } = await stripe.confirmPayment({
      elements,
      confirmParams: {
        return_url: 'https://example.com/order/123/complete',
      },
    });
    
    if (error) {
      console.error(error.message);
    }
    
    setIsLoading(false);
  };

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      <button disabled={!stripe || isLoading}>
        {isLoading ? 'Processing...' : 'Pay now'}
      </button>
    </form>
  );
};

const App = () => (
  <Elements stripe={stripePromise} options={{ clientSecret: 'pi_...' }}>
    <CheckoutForm />
  </Elements>
);

Architecture

React Stripe.js is built around several key architectural patterns:

  • Context Providers: Elements and EmbeddedCheckoutProvider manage Stripe instances and configuration
  • React Hooks: useStripe and useElements provide access to Stripe functionality within components
  • Element Components: Pre-built React components wrapping Stripe Elements for specific payment methods
  • TypeScript Integration: Full type safety with comprehensive TypeScript definitions
  • Server-Side Rendering: Built-in SSR support with automatic client/server detection
  • Checkout Flow Support: Specialized checkout components and providers for streamlined payment flows

Capabilities

Core Providers and Hooks

Essential React context providers and hooks for integrating Stripe functionality into React applications.

function Elements(props: ElementsProps): JSX.Element;

interface ElementsProps {
  stripe: PromiseLike<Stripe | null> | Stripe | null;
  options?: StripeElementsOptions;
  children: ReactNode;
}

function useStripe(): Stripe | null;
function useElements(): StripeElements | null;

Core Providers and Hooks

Payment Elements

Modern payment elements supporting multiple payment methods with unified interfaces.

function PaymentElement(props: PaymentElementProps): JSX.Element;
function ExpressCheckoutElement(props: ExpressCheckoutElementProps): JSX.Element;
function PaymentRequestButtonElement(props: PaymentRequestButtonElementProps): JSX.Element;

interface PaymentElementProps extends ElementProps {
  options?: StripePaymentElementOptions;
  onChange?: (event: StripePaymentElementChangeEvent) => any;
  onReady?: (element: StripePaymentElement) => any;
  onEscape?: () => any;
  onLoadError?: (event: {elementType: 'payment'; error: StripeError}) => any;
  onLoaderStart?: (event: {elementType: 'payment'}) => any;
}

Payment Elements

Card Elements

Individual card input elements for granular control over payment form layout.

function CardElement(props: CardElementProps): JSX.Element;
function CardNumberElement(props: CardNumberElementProps): JSX.Element;
function CardExpiryElement(props: CardExpiryElementProps): JSX.Element;
function CardCvcElement(props: CardCvcElementProps): JSX.Element;

interface CardElementProps extends ElementProps {
  options?: StripeCardElementOptions;
  onChange?: (event: StripeCardElementChangeEvent) => any;
  onReady?: (element: StripeCardElement) => any;
  onEscape?: () => any;
  onNetworksChange?: (event: {elementType: 'card'}) => any;
  onLoadError?: (event: {elementType: 'card'; error: StripeError}) => any;
}

Card Elements

Bank Payment Elements

Elements for region-specific bank payment methods and direct bank transfers.

function IbanElement(props: IbanElementProps): JSX.Element;
function FpxBankElement(props: FpxBankElementProps): JSX.Element;
function IdealBankElement(props: IdealBankElementProps): JSX.Element;
function P24BankElement(props: P24BankElementProps): JSX.Element;
function EpsBankElement(props: EpsBankElementProps): JSX.Element;
function AuBankAccountElement(props: AuBankAccountElementProps): JSX.Element;

interface IbanElementProps extends ElementProps {
  options?: StripeIbanElementOptions;
  onChange?: (event: StripeIbanElementChangeEvent) => any;
  onReady?: (element: StripeIbanElement) => any;
  onEscape?: () => any;
}

Bank Payment Elements

Address and Contact Elements

Elements for collecting customer address, shipping, and contact information.

function AddressElement(props: AddressElementProps): JSX.Element;
function LinkAuthenticationElement(props: LinkAuthenticationElementProps): JSX.Element;
function TaxIdElement(props: TaxIdElementProps): JSX.Element;

interface AddressElementProps extends ElementProps {
  options?: StripeAddressElementOptions;
  onChange?: (event: StripeAddressElementChangeEvent) => any;
  onReady?: (element: StripeAddressElement) => any;
  onEscape?: () => any;
  onLoadError?: (event: {elementType: 'address'; error: StripeError}) => any;
  onLoaderStart?: (event: {elementType: 'address'}) => any;
}

Address and Contact Elements

Message Elements

Elements for displaying financing options and payment method messaging to customers.

function PaymentMethodMessagingElement(props: PaymentMethodMessagingElementProps): JSX.Element;
function AffirmMessageElement(props: AffirmMessageElementProps): JSX.Element;
function AfterpayClearpayMessageElement(props: AfterpayClearpayMessageElementProps): JSX.Element;

interface PaymentMethodMessagingElementProps extends ElementProps {
  options?: StripePaymentMethodMessagingElementOptions;
  onReady?: (element: StripePaymentMethodMessagingElement) => any;
  onEscape?: () => any;
  onLoadError?: (event: {elementType: 'paymentMethodMessaging'; error: StripeError}) => any;
  onLoaderStart?: (event: {elementType: 'paymentMethodMessaging'}) => any;
}

Message Elements

Embedded Checkout

Complete embedded checkout solution for streamlined payment experiences.

function EmbeddedCheckoutProvider(props: EmbeddedCheckoutProviderProps): JSX.Element;
function EmbeddedCheckout(props: EmbeddedCheckoutProps): JSX.Element;

interface EmbeddedCheckoutProviderProps {
  stripe: PromiseLike<Stripe | null> | Stripe | null;
  options: EmbeddedCheckoutOptions;
  children: ReactNode;
}

interface EmbeddedCheckoutProps {
  id?: string;
  className?: string;
}

Embedded Checkout

Checkout Flow Components

Specialized components and providers for optimized checkout experiences.

function CheckoutProvider(props: CheckoutProviderProps): JSX.Element;
function useCheckout(): CheckoutState;
function BillingAddressElement(props: BillingAddressElementProps): JSX.Element;
function ShippingAddressElement(props: ShippingAddressElementProps): JSX.Element;
function CurrencySelectorElement(props: CurrencySelectorElementProps): JSX.Element;

type CheckoutState =
  | {type: 'loading'}
  | {type: 'success'; checkout: CheckoutValue}
  | {type: 'error'; error: {message: string}};

Checkout Flow Components

Common Types

interface ElementProps {
  id?: string;
  className?: string;
  onBlur?: (event: {elementType: StripeElementType}) => any;
  onFocus?: (event: {elementType: StripeElementType}) => any;
}

interface StripeElementsOptions {
  clientSecret?: string;
  appearance?: StripeElementsAppearance;
  fonts?: StripeElementsFonts;
  locale?: string;
  loader?: 'auto' | 'never' | 'always';
}

interface StripeElementsAppearance {
  theme?: 'stripe' | 'night' | 'flat';
  variables?: Record<string, string>;
  rules?: Record<string, Record<string, string>>;
}

interface StripeElementsFonts {
  family?: string;
  src?: string;
  display?: string;
  style?: string;
  unicodeRange?: string;
  weight?: string;
}

type StripeElementType = 
  | 'card' | 'cardNumber' | 'cardExpiry' | 'cardCvc'
  | 'payment' | 'expressCheckout' | 'paymentRequestButton'
  | 'iban' | 'fpxBank' | 'idealBank' | 'p24Bank' | 'epsBank' | 'auBankAccount'
  | 'address' | 'shippingAddress' | 'linkAuthentication' | 'taxId'
  | 'paymentMethodMessaging' | 'affirmMessage' | 'afterpayClearpayMessage';

interface EmbeddedCheckoutOptions {
  clientSecret?: string;
  fetchClientSecret?: () => Promise<string>;
  onComplete?: () => void;
  onError?: (error: {message: string}) => void;
}

type StripeError = {
  type: string;
  code?: string;
  message: string;
  decline_code?: string;
  param?: string;
};