让开源，少一点语言距离。
npm包中文文档

@chargebee/chargebee-js-react-wrapper

中文文档
0.6.9发布于 2025/10/10MITTypeScriptESM + CJS零依赖近 30 天下载 16.1万

React wrapper for Chargebee.js Components

原始使用文档
中文原文
文档目录11 节
  1. Examples
  2. Live Demo
  3. Installation
  4. Usage
  5. Basic usage
  6. A more complex example:
  7. Server Side Rendering using NextJS
  8. 3DS Authorization
  9. Components and APIs
  10. Reference:
  11. Support

Chargebee JS React Wrapper

React wrapper for Chargebee Components

Examples

For detailed examples: Click here

Live Demo

View live demo here

Installation

Install from npm:

npm install @chargebee/chargebee-js-react-wrapper

Usage

Chargebee Components requires you to initialize chargebee js with site and publishableKey

Wondering where to obtain your publishable API key? Refer here

In your index.html:

<html>
    <head>
        ...
        <script src="https://js.chargebee.com/v2/chargebee.js"></script>
        <script>
            Chargebee.init({
                site: 'your-site',
                publishableKey: 'your-publishable-key'
            })
        </script>
    </head>
    <body>
        <div id='root'></div>
    </body>
</html>

Basic usage

In your react component

import { CardComponent } from '@chargebee/chargebee-js-react-wrapper';

class App extends React.Component {
    cardRef = React.createRef()
    ...
    onSubmit = (e) => {
        if(e) e.preventDefault()
        this.cardRef.current.tokenize()
        .then((data) => {
          console.log('chargebee token', data.token)
        });
    }
    ...
    render() {
        // Using combined mode
        return(
            <div className="App">
                <form>
                    ...
                    <CardComponent ref={this.cardRef} onChange={this.onChange}/>
                    <button type="submit" onClick={this.onSubmit}>Submit</button>
                    ...
                </form>
            </div>
        )
    }
}

A more complex example:

import {CardComponent, CardNumber, CardExpiry, CardCVV} from "react-cb";
import './App.css'

class App extends Component {
  cardRef = React.createRef()

  state = {
    errors: {},
    errorMessage: '',
    // CSS class names for field's status
    classes: {
        'focus': 'focus-css-class',
        'complete': 'complete-css-class',
        'invalid': 'invalid-css-class',
        'empty': 'empty-css-class',
    },
    // Google Fonts and other whitelisted fonts
    fonts: [
        'https://fonts.googleapis.com/css?family=Open+Sans'
    ],
    // Style customizations
    styles: {
        base: {
            color: '#fff',
            fontWeight: 600,
            fontFamily: 'Quicksand, Open Sans, Segoe UI, sans-serif',
            fontSize: '16px',
            fontSmoothing: 'antialiased',

            ':focus': {
                color: '#424770',
            },

            '::placeholder': {
                color: '#9BACC8',
            },

            ':focus::placeholder': {
                color: '#CFD7DF',
            },
        },
        invalid: {
            color: '#fff',
            ':focus': {
                color: '#FA755A',
            },
            '::placeholder': {
                color: '#FFCCA5',
            },
        },
    }
  }

  onSubmit = (e) => {
    if(e) e.preventDefault()
    if(this.cardRef) {
      // Call tokenize method on card element
      this.cardRef.current.tokenize().then((data) => {
          console.log('chargebee token', data.token)
      });
    }
  }

  onChange = (status) => {
    let errors = {
      ...this.state.errors,
      [status.field]: status.error
    };
    let errMessages = Object.values(errors).filter(message => !!message);
    this.setState({
      errors,
      errorMessage: errMessages.pop() || '',
    })
  }

  onReady = (el) => {
    el.focus();
  }

  render() {
    const { fonts, styles, classes, locale } = this.state;
    // Using individual fields mode
    return (
      <div className="App">
          <div className="cell example example3" id="example-3">
            <form>
              <div className="fieldset">
                <CardComponent className="field" 
                    fonts={fonts} 
                    classes={classes} 
                    locale={locale} 
                    styles={styles} 
                    ref={this.CardRef} 
                    showTestCards={true}           
                    onReady={this.onReady}
                >
                    <CardNumber placeholder='4111 1111 1111 1111' className="field empty" onChange={this.onChange} onReady={this.onReady} />
                    <CardExpiry placeholder='MM / YY' className="field empty" onChange={this.onChange} />
                    <CardCVV placeholder='CVV' className="field empty" onChange={this.onChange} />
                </CardComponent>
              </div>
              <button type="submit" onClick={this.onSubmit}>Pay now</button>
            </form>
            <div id="errors">{this.state.errorMessage}</div>
          </div>
      </div>
    );
  }
}

Server Side Rendering using NextJS

Pre-requisites:

The chargebee instance should be initialized with site and API Key and the initiated cb instance should be passed as props to the Provider component. A validation is done to check 3 things:

  • Passed site as non-empty string, during initialization call
  • Passed API Key as non-empty string, during initialization call
  • cbInstance initialized status

Also, a project using NextJS should be setup

Usage:

  1. Load chargebee.js script before any other code/script execution(generally index.html). This is to enable Chargebee be a part of client side browser window
<script src="https://js.chargebee.com/v2/chargebee.js"> </script>
  1. Initialize chargebee inside componentDidMount(), do not use it in constructor() or render() when using SSR
componentDidMount() {
..
    // initialize with site, publishableKey
    window.Chargebee.init({
        site: "...",
        publishableKey: "..."
    });
    
    // get cb Instance
    cbInstance = window.Chargebee.getInstance();
..
}
  1. Import the Provider, CardComponent, etc. components from the module
import {CardComponent, CardNumber, CardExpiry, CardCVV, Provider} from "@chargebee/chargebee-js-react-wrapper";
  1. Within your custom component, wrap the CardComponent inside a Provider component, pass the cbInstance as props
<Provider cbInstance={this.props.cbInstance}>
   <CardComponent ... >
    ...
    </CardComponent>
</Provider>

Example:

Detailed example :

import {CardComponent, CardNumber, CardExpiry, CardCVV, Provider} from "@chargebee/chargebee-js-react-wrapper";

...
componentDidMount() {
  window.Chargebee.init({
    site: "honeycomics-v3-test",
    publishableKey: "your_site_pub_api_key"
  })

  this.setState({
    cbInstance: window.Chargebee.getInstance()
  })
}

render() {
...
<script src="https://js.chargebee.com/v2/chargebee.js" ></script>
...
<Provider cbInstance={this.state.cbInstance}>
  <CardComponent ref={this.cardRef} className="fieldset field"
    styles={style} 
    classes={classes} 
    locale={locale}
    placeholder={placeholder}
    fonts={fonts}
    showTestCards={true}
  >
    <div className="ex1-field">
      {/* Card number component */}
      <CardNumber className="ex1-input"/>
      <label className="ex1-label">Card Number</label><i className="ex1-bar"></i>
    </div>

    <div className="ex1-fields">
      <div className="ex1-field">
        {/* Card expiry component */}
        <CardExpiry className="ex1-input"/>
        <label className="ex1-label">Expiry</label><i className="ex1-bar"></i>
      </div>

      <div className="ex1-field">
        {/* Card cvv component */}
        <CardCVV className="ex1-input"/>
        <label className="ex1-label">CVC</label><i className="ex1-bar"></i>
      </div>

    </div>
  </CardComponent>
</Provider>
... 
}

Run the application

  • npm install
  • (NextJS project structure with chargebee-js-react-wrapper installed) -> npm run build / start / dev
"scripts": {
   "dev": "next dev",
   "build": "next build",
   "start": "next start"
 }

3DS Authorization

In your react component

import { CardComponent } from '@chargebee/chargebee-js-react-wrapper';

class App extends React.Component {
    cardRef = React.createRef()
    ...
    createPaymentIntent() {
      // make ajax call to server to create payment intent
    }
    ...
    componentDidMount() {
      this.createPaymentIntent().then(intent => {
        this.state.intent = intent;
      })
    }
    ...
    onSubmit = (e) => {
        if(e) e.preventDefault()
        
        const intent = this.state.intent;
        const additionalData = this.state.additionalData;
        
        this.cardRef.current.authorizeWith3ds(intent, additionalData)
        .then(authorizedPaymentIntent => {
          console.log('Authorized payment intent', authorizedPaymentIntent.id)
        }).catch(error => {
          console.error('Error occured', error)
        });
    }
    ...
    render() {
        // Using combined mode
        return(
            <div className="App">
                <form>
                    ...
                    <CardComponent ref={this.cardRef} onChange={this.onChange}/>
                    <button type="submit" onClick={this.onSubmit}>Submit</button>
                    ...
                </form>
            </div>
        )
    }
}

Components and APIs

Card Component (docs)

PropsDescriptionDatatype
classNameCSS Class name for the container divString
fontsAn array of font faces or linksFonts
classesSet of CSS classnames that get substituted for various eventsClasses
localeLanguage codeLocale
stylesSet of style customizationsStyles
placeholderSet of placeholders for the card fieldsPlaceholder
refReact Ref element for tokenizing dataReactRef
showTestCardsAdd ability to show test cards on test sitesBoolean
Event Props (docs)
PropsDescriptionArguments
onReadyTriggers when component is mounted and readyField
onChangeTriggers for every state changeField State
onFocusTriggers when component is focusedField State
onBlurTriggers when component is blurredField State
onKeyPressTriggers when a key is pressed inside component
Supports ESC key		Field State

Field Components (docs)

  • CardNumber
  • CardExpiry
  • CardCVV
PropsDescriptionDatatype
classNameCSS Classname for container divString
stylesStyles for inidividual fieldStyles
placeholderPlaceholder for the fieldString
Event Props (docs)
PropsDescriptionArguments
onReadyTriggers when component is mounted and readyField
onChangeTriggers for every state changeField State
onFocusTriggers when component is focusedField State
onBlurTriggers when component is blurredField State

Reference:

Chargebee Components - JS Docs

Support

Have any queries regarding the implementation? Reach out to [email protected]

版本与发布记录

@chargebee/chargebee-js-react-wrapper 共发布 25 个版本，首次发布于 2019/04/28；过去 12 个月发布了 0 个版本。

版本发布日期距今
0.6.9latest2025/10/101.1 年前
0.6.82025/10/091.1 年前
0.6.72025/04/151.6 年前
0.6.6next2024/11/182 年前
0.6.7-rc.02024/11/182 年前
0.6.52024/05/202 年前

关于 @chargebee/chargebee-js-react-wrapper 的常见问题

@chargebee/chargebee-js-react-wrapper 是什么？

React wrapper for Chargebee.js Components

如何安装 @chargebee/chargebee-js-react-wrapper？

在项目目录运行 npm install @chargebee/chargebee-js-react-wrapper，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19.0.0 || ^18.0.0 || ^17.0.0）、react-dom（^19.0.0 || ^18.0.0 || ^17.0.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

@chargebee/chargebee-js-react-wrapper 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@chargebee/chargebee-js-react-wrapper 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require() 都可以使用，打包工具会自动选择合适的版本。

@chargebee/chargebee-js-react-wrapper 可以商用吗？

@chargebee/chargebee-js-react-wrapper 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@chargebee/chargebee-js-react-wrapper 的下载量有多少？

根据 npm 官方下载统计，@chargebee/chargebee-js-react-wrapper 在 2026/10/10 – 2026/11/08 这 30 天内被下载 161,142 次，日均约 5,371 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@chargebee/chargebee-js-react-wrapper 还在维护吗？

最新版本 0.6.9 发布于 2025/10/10（1.1 年前）；至今共发布 25 个版本，其中过去 12 个月发布了 0 个；首次发布于 2019/04/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。