https://github.com/verygoodsecurity/collect-js-react
https://github.com/verygoodsecurity/collect-js-react
team-developer-experience
Last synced: 8 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/verygoodsecurity/collect-js-react
- Owner: verygoodsecurity
- License: mit
- Created: 2022-11-01T16:05:53.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-09-23T20:05:48.000Z (9 months ago)
- Last Synced: 2025-09-23T22:09:03.377Z (9 months ago)
- Topics: team-developer-experience
- Language: TypeScript
- Homepage:
- Size: 1.11 MB
- Stars: 1
- Watchers: 5
- Forks: 16
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
VGS Collect.js React Wrapper
React wrapper for VGS Collect.js fields
Explore the docs »
Report Bug
·
Request Feature
[](https://circleci.com/gh/circleci/circleci-docs)
- [Overview](#overview)
- [Installation](#installation)
- [How to use](#how-to-use)
- [Documentation](#documentation)
- [Examples](#examples)
- [Contact](#contact)
- [License](#license)
## Overview
### What is VGS Collect.js?
[VGS Collect.js](https://www.verygoodsecurity.com/docs/vgs-collect/js/overview) is a JavaScript library that allows you to securely collect data via any form. Instantly create custom forms that adhere to PCI, HIPAA, GDPR, or CCPA security requirements. [VGS](https://www.verygoodsecurity.com/) intercepts sensitive data before it hits your servers and replaces it with aliased versions while securing the original data in our vault. The form fields behave like traditional forms while preventing access to unsecured data by injecting secure iframe components.
- [Documentation](https://www.verygoodsecurity.com/docs/vgs-collect/js/overview)
- [Reference Documentation](https://www.verygoodsecurity.com/docs/api/collect/)
- [Examples](https://verygoodsecurity.github.io/vgs-collect-examples)
### Why do I need to use this package?
This package provides a convenient way to use VGS secure frames in the React environment by exposing field components.
## Installation
Install the package using `npm`:
```bash
npm install @vgs/collect-js-react
```
## How to use
### 1. Load VGS Collect.js script:
To stay PCI Compliant it's a mandatory to load js from our `js.verygoodvault.com` domain as a consequence you need to find the most suitable way to download it.
There are couple of options here:
- [Download file directly from the CDN](https://www.verygoodsecurity.com/docs/vgs-collect/js#quick-start).
- Use our loading [npm module](https://www.npmjs.com/package/@vgs/collect-js). _[Example](https://github.com/verygoodsecurity/collect-js-react/blob/main/example/src/features/Basic.tsx#L45)_.
### 2. Define parent form wrapper component:
```javascript
import { VGSCollectForm } from '@vgs/collect-js-react';
const App = () => {
const onSubmitCallback = (status, data) => {};
const onUpdateCallback = (state) => {};
return (
// Add secure fields here
);
};
export default App;
```
| Property | Description | Documentation |
| ------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| vaultId | A string value beginning with the prefix `tnt`. | [Parameters.vaultId](https://www.verygoodsecurity.com/docs/api/collect/#api-vgscollectcreate) |
| environment | Vault environment: `sanbdox` \| `live` or region specific. | [Parameters.environment](https://www.verygoodsecurity.com/docs/api/collect/#api-vgscollectcreate) |
| action | Endpoint for the HTTP request. | [Parameters.path](https://www.verygoodsecurity.com/docs/api/collect/#api-formsubmit) |
| submitParamethers? | HTTP request configuration. | [Parameters.options](https://www.verygoodsecurity.com/docs/api/collect/#api-formsubmit) |
| onUpdateCallback? | Returns the form state in the callback. | [Parameters.stateCallback](https://www.verygoodsecurity.com/docs/api/collect/#api-vgscollectcreate) |
| onSubmitCallback? | Returns status and response data in the callback. | [Parameters.responseCallback](https://www.verygoodsecurity.com/docs/api/collect/#api-formsubmit) |
| cname? | String represents CNAME the request will be submitted to. | [.useCNAME()](https://www.verygoodsecurity.com/docs/api/collect/#api-formusecname) |
| routeId? | Inbound Route ID. | [.setRouteId()](https://www.verygoodsecurity.com/docs/api/collect/#api-formsetrouteid) |
### 3. Define secure input fields
| **Collect.js input type** | **Collect.js React Component** | **Default Prop Values** |
|---------------------------|---------------------------------------------|------------------------------------------------------------------------------------------|
| `text` | `` | `{ type: 'text', placeholder: 'Cardholder Name' }` |
| `text` | `` | `{ type: 'text', name: 'cardholder', placeholder: 'Cardholder' }` |
| `card-number` | `` | `{ type: 'card-number', name: 'pan', validations: ['required', 'validCardNumber'], placeholder: 'Credit Card Number' }` |
| `card-expiration-date` | ``| `{ type: 'card-expiration-date', name: 'exp-date', validations: ['required', 'validCardExpirationDate'], yearLength: 2, placeholder: 'MM/YY' }` |
| `card-security-code` | `` | `{ type: 'card-security-code', name: 'cvc', validations: ['required', 'validCardSecurityCode'], placeholder: 'CVC/CVV' }` |
| `password` | `` | `{ type: 'password', placeholder: 'Enter Password' }` |
| `ssn` | `` | `{ type: 'ssn', placeholder: 'SSN' }` |
| `zip-code` | `` | `{ type: 'zip-code', placeholder: 'Zip Code' }` |
| `number` | `` | `{ type: 'number', placeholder: 'Number' }` |
| `textarea` | `` | `{ type: 'textarea', placeholder: 'Comment' }` |
| `file` | `` | `{ type: 'file', placeholder: '' }` |
| `date` | `` | `{ type: 'date', placeholder: '' }` |
The complete list of supported properties you can find here: https://www.verygoodsecurity.com/docs/api/collect/#api-formfield.
All configuration properties available in the Reference Documentation can be passed in the component props using the same name.
_Example:_
```javascript
import { VGSCollectForm } from '@vgs/collect-js-react';
const { CardNumberField, CardExpirationDateField, CardSecurityCodeField } = VGSCollectForm;
const myApp = () => {
const onSubmitCallback = (status, data) => {};
const onUpdateCallback = (state) => {};
return (
);
};
```
### 3. Field event handlers
VGS Collect.js allows listening to input changes.
The library exposes the following handlers: `onFocus`, `onBlur`, `onUpdate`, `onDelete`, `onKeyUp`, `onKeyDown`, `onKeyPress`.
```javascript
{}}
onBlur={(info: VGSCollectFocusEventData) => {}}
onUpdate={(info: VGSCollectStateParams) => {}}
onKeyUp={(info: VGSCollectKeyboardEventData) => {}}
onKeyDown={(info: VGSCollectKeyboardEventData) => {}}
onKeyPress={(info: VGSCollectKeyboardEventData) => {}}
/>
```
### 4. Hooks
In order to access the form state and response from the hook, wrap consumer component with the form in `VGSCollectProvider` context provider.
```javascript
import { VGSCollectProvider, useVGSCollectState, useVGSCollectResponse, VGSCollectForm } from '@vgs/collect-js-react';
const { TextField } = VGSCollectForm;
const App = () => {
return (
);
};
const VGSCollectSecureForm = () => {
const [state] = useVGSCollectState();
const [response] = useVGSCollectResponse();
useEffect(() => {
if (state) {
// do something
}
}, [state]);
return (
);
};
```
## Integration with Card Management Platform
You can create a predefined Collect.js form to integrate with the [VGS Card Management Platform](https://docs.verygoodsecurity.com/card-management/api)
```javascript
import { VGSCollectForm } from '@vgs/collect-js-react';
const {CardholderField, CardNumberField, CardExpirationDateField, CardSecurityCodeField } = VGSCollectForm;
const myApp = () => {
const onSubmitCallback = (status, data) => {};
const onUpdateCallback = (state) => {};
return (
}
}}
onUpdateCallback={onUpdateCallback}
onSubmitCallback={onSubmitCallback}
>
);
};
```
## Documentation
- [Collect.js Documentation](https://www.verygoodsecurity.com/docs/vgs-collect/js/integration)
- [Collect.js Reference Documentation](https://www.verygoodsecurity.com/docs/api/collect)
## Examples
To run exmaples locally, in the core folder run:
```sh
yarn install
yarn start
```
Switch the folder to `example` and configure `.env` file, simply rename `.env.example` and replace values
```sh
REACT_APP_VAULT_ID=
REACT_APP_ENVIRONMENT=
REACT_APP_COLLECT_VERSION=
```
From `example` folder run:
```sh
yarn install
yarn start
```
Open [http://localhost:3000/](http://localhost:3000/)
- [Simple Configuration](https://github.com/verygoodsecurity/collect-js-react/blob/main/example/src/features/Basic.tsx)
- [Custom Payload Configuration](https://github.com/verygoodsecurity/collect-js-react/blob/main/example/src/features/CustomPayload.tsx)
- [Stackblitz](https://stackblitz.com/edit/react-ts-kuxtvv?file=App.tsx)
## Contact
If you have any questions please reach out to [support](mailto:support@verygoodsecurity.com) or open issue [here](https://github.com/verygoodsecurity/vgs-collect-js/issues).
## License
This project is licensed under the MIT license. See the [LICENSE](LICENSE) file
for details.