{"id":28934055,"url":"https://github.com/verygoodsecurity/collect-js-react","last_synced_at":"2025-10-11T07:06:51.347Z","repository":{"id":65615547,"uuid":"560490730","full_name":"verygoodsecurity/collect-js-react","owner":"verygoodsecurity","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-23T20:05:48.000Z","size":1164,"stargazers_count":1,"open_issues_count":17,"forks_count":16,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-09-23T22:09:03.377Z","etag":null,"topics":["team-developer-experience"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/verygoodsecurity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-11-01T16:05:53.000Z","updated_at":"2025-09-23T20:05:52.000Z","dependencies_parsed_at":"2023-02-16T23:15:18.637Z","dependency_job_id":"687216ca-8c77-4c40-84e5-d6b2b9cd3f02","html_url":"https://github.com/verygoodsecurity/collect-js-react","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/verygoodsecurity/collect-js-react","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodsecurity%2Fcollect-js-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodsecurity%2Fcollect-js-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodsecurity%2Fcollect-js-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodsecurity%2Fcollect-js-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/verygoodsecurity","download_url":"https://codeload.github.com/verygoodsecurity/collect-js-react/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodsecurity%2Fcollect-js-react/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006587,"owners_count":26084128,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["team-developer-experience"],"created_at":"2025-06-22T18:39:33.822Z","updated_at":"2025-10-11T07:06:51.342Z","avatar_url":"https://github.com/verygoodsecurity.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.verygoodsecurity.com/\" rel=\"nofollow\"\u003e\n    \u003cimg src=\"https://avatars0.githubusercontent.com/u/17788525\" width=\"128\" alt=\"VGS Logo\"\u003e\n  \u003c/a\u003e\n  \u003ch3 align=\"center\"\u003eVGS Collect.js React Wrapper\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    React wrapper for VGS Collect.js fields\n    \u003cbr /\u003e\n    \u003ca href=\"https://www.verygoodsecurity.com/docs/vgs-collect/js/overview\"\u003e\u003cstrong\u003eExplore the docs »\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/verygoodsecurity/collect-js-react/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/verygoodsecurity/collect-js-react/issues\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n[![CircleCI](https://circleci.com/gh/verygoodsecurity/collect-js-react.svg?style=svg)](https://circleci.com/gh/circleci/circleci-docs)\n\n- [Overview](#overview)\n- [Installation](#installation)\n- [How to use](#how-to-use)\n- [Documentation](#documentation)\n- [Examples](#examples)\n- [Contact](#contact)\n- [License](#license)\n\n## Overview\n\n### What is VGS Collect.js?\n\n[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.\n\n- [Documentation](https://www.verygoodsecurity.com/docs/vgs-collect/js/overview)\n- [Reference Documentation](https://www.verygoodsecurity.com/docs/api/collect/)\n- [Examples](https://verygoodsecurity.github.io/vgs-collect-examples)\n\n### Why do I need to use this package?\n\nThis package provides a convenient way to use VGS secure frames in the React environment by exposing field components.\n\n## Installation\n\nInstall the package using `npm`:\n\n```bash\nnpm install @vgs/collect-js-react\n```\n\n## How to use\n\n### 1. Load VGS Collect.js script:\n\nTo 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.\nThere are couple of options here:\n\n- [Download file directly from the CDN](https://www.verygoodsecurity.com/docs/vgs-collect/js#quick-start).\n- 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)_.\n\n\u003cbr/\u003e\n\n### 2. Define parent form wrapper component:\n\n```javascript\nimport { VGSCollectForm } from '@vgs/collect-js-react';\n\nconst App = () =\u003e {\n  const onSubmitCallback = (status, data) =\u003e {};\n  const onUpdateCallback = (state) =\u003e {};\n\n  return (\n    \u003cVGSCollectForm\n      vaultId='\u003cvault_id\u003e'\n      environment='\u003cenvironment\u003e'\n      action='/post'\n      submitParameters={{}}\n      onUpdateCallback={onUpdateCallback}\n      onSubmitCallback={onSubmitCallback}\n    \u003e\n      // Add secure fields here\n    \u003c/VGSCollectForm\u003e\n  );\n};\nexport default App;\n```\n\n| Property           | Description                                                | Documentation                                                                                       |\n| ------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |\n| vaultId            | A string value beginning with the prefix `tnt`.            | [Parameters.vaultId](https://www.verygoodsecurity.com/docs/api/collect/#api-vgscollectcreate)       |\n| environment        | Vault environment: `sanbdox` \\| `live` or region specific. | [Parameters.environment](https://www.verygoodsecurity.com/docs/api/collect/#api-vgscollectcreate)   |\n| action             | Endpoint for the HTTP request.                             | [Parameters.path](https://www.verygoodsecurity.com/docs/api/collect/#api-formsubmit)                |\n| submitParamethers? | HTTP request configuration.                                | [Parameters.options](https://www.verygoodsecurity.com/docs/api/collect/#api-formsubmit)             |\n| onUpdateCallback?  | Returns the form state in the callback.                    | [Parameters.stateCallback](https://www.verygoodsecurity.com/docs/api/collect/#api-vgscollectcreate) |\n| onSubmitCallback?  | Returns status and response data in the callback.          | [Parameters.responseCallback](https://www.verygoodsecurity.com/docs/api/collect/#api-formsubmit)    |\n| cname?             | String represents CNAME the request will be submitted to.  | [.useCNAME()](https://www.verygoodsecurity.com/docs/api/collect/#api-formusecname)                  |\n| routeId?           | Inbound Route ID.                                          | [.setRouteId()](https://www.verygoodsecurity.com/docs/api/collect/#api-formsetrouteid)              |\n\n\u003cbr/\u003e\n\n### 3. Define secure input fields\n\n| **Collect.js input type** | **Collect.js React Component**              | **Default Prop Values**                                                                 |\n|---------------------------|---------------------------------------------|------------------------------------------------------------------------------------------|\n| `text`                    | `\u003cVGSCollectForm.TextField /\u003e`              | `{ type: 'text', placeholder: 'Cardholder Name' }`                                      |\n| `text`                    | `\u003cVGSCollectForm.CardholderField /\u003e`        | `{ type: 'text', name: 'cardholder', placeholder: 'Cardholder' }`                       |\n| `card-number`             | `\u003cVGSCollectForm.CardNumberField /\u003e`        | `{ type: 'card-number', name: 'pan', validations: ['required', 'validCardNumber'], placeholder: 'Credit Card Number' }` |\n| `card-expiration-date`    | `\u003cVGSCollectForm.CardExpirationDateField /\u003e`| `{ type: 'card-expiration-date', name: 'exp-date', validations: ['required', 'validCardExpirationDate'], yearLength: 2, placeholder: 'MM/YY' }` |\n| `card-security-code`      | `\u003cVGSCollectForm.CardSecurityCodeField /\u003e`  | `{ type: 'card-security-code', name: 'cvc', validations: ['required', 'validCardSecurityCode'], placeholder: 'CVC/CVV' }` |\n| `password`                | `\u003cVGSCollectForm.PasswordField /\u003e`          | `{ type: 'password', placeholder: 'Enter Password' }`                                   |\n| `ssn`                     | `\u003cVGSCollectForm.SSNField /\u003e`               | `{ type: 'ssn', placeholder: 'SSN' }`                                                   |\n| `zip-code`                | `\u003cVGSCollectForm.ZipCodeField /\u003e`           | `{ type: 'zip-code', placeholder: 'Zip Code' }`                                         |\n| `number`                  | `\u003cVGSCollectForm.NumberField /\u003e`            | `{ type: 'number', placeholder: 'Number' }`                                             |\n| `textarea`                | `\u003cVGSCollectForm.TextareaField /\u003e`          | `{ type: 'textarea', placeholder: 'Comment' }`                                          |\n| `file`                    | `\u003cVGSCollectForm.FileField /\u003e`              | `{ type: 'file', placeholder: '' }`                                                     |\n| `date`                    | `\u003cVGSCollectForm.DateField /\u003e`              | `{ type: 'date', placeholder: '' }`                                                     |\n\nThe complete list of supported properties you can find here: https://www.verygoodsecurity.com/docs/api/collect/#api-formfield.\nAll configuration properties available in the Reference Documentation can be passed in the component props using the same name.\n\n_Example:_\n\n```javascript\nimport { VGSCollectForm } from '@vgs/collect-js-react';\n\nconst { CardNumberField, CardExpirationDateField, CardSecurityCodeField } = VGSCollectForm;\n\nconst myApp = () =\u003e {\n  const onSubmitCallback = (status, data) =\u003e {};\n  const onUpdateCallback = (state) =\u003e {};\n\n  return (\n    \u003cVGSCollectForm\n      vaultId='\u003cvault_id\u003e'\n      environment='\u003cenvironment\u003e'\n      action='/post'\n      submitParameters={{\n        headers: {\n          myHeader: 'MyHeader'\n        }\n      }}\n      onUpdateCallback={onUpdateCallback}\n      onSubmitCallback={onSubmitCallback}\n    \u003e\n      \u003cCardNumberField\n        name='card-number'\n        validations={['required', 'validCardNumber']}\n        placeholder='XXXX XXXX XXXX XXXX'\n        showCardIcon={true}\n        css={{}}\n      /\u003e\n      \u003cCardExpirationDateField\n        name='exp-date'\n        validations={['required', 'validCardExpirationDate']}\n        placeholder='MM / YY'\n        yearLength={2}\n        css={{}}\n      /\u003e\n      \u003cCardSecurityCodeField\n        name='cvv'\n        validations={['required', 'validCardSecurityCode']}\n        placeholder='CVV'\n        css={{}}\n      /\u003e\n    \u003c/VGSCollectForm\u003e\n  );\n};\n```\n\n\u003cbr/\u003e\n\n### 3. Field event handlers\n\nVGS Collect.js allows listening to input changes.\nThe library exposes the following handlers: `onFocus`, `onBlur`, `onUpdate`, `onDelete`, `onKeyUp`, `onKeyDown`, `onKeyPress`.\n\n```javascript\n\u003cTextField\n  name='text'\n  validations={['required']}\n  onFocus={(info: VGSCollectFocusEventData) =\u003e {}}\n  onBlur={(info: VGSCollectFocusEventData) =\u003e {}}\n  onUpdate={(info: VGSCollectStateParams) =\u003e {}}\n  onKeyUp={(info: VGSCollectKeyboardEventData) =\u003e {}}\n  onKeyDown={(info: VGSCollectKeyboardEventData) =\u003e {}}\n  onKeyPress={(info: VGSCollectKeyboardEventData) =\u003e {}}\n/\u003e\n```\n\n### 4. Hooks\n\nIn order to access the form state and response from the hook, wrap consumer component with the form in `VGSCollectProvider` context provider.\n\n```javascript\nimport { VGSCollectProvider, useVGSCollectState, useVGSCollectResponse, VGSCollectForm } from '@vgs/collect-js-react';\n\nconst { TextField } = VGSCollectForm;\n\nconst App = () =\u003e {\n  return (\n    \u003cVGSCollectProvider\u003e\n      \u003cVGSCollectSecureForm /\u003e\n    \u003c/VGSCollectProvider\u003e\n  );\n};\n\nconst VGSCollectSecureForm = () =\u003e {\n  const [state] = useVGSCollectState();\n  const [response] = useVGSCollectResponse();\n\n  useEffect(() =\u003e {\n    if (state) {\n      // do something\n    }\n  }, [state]);\n\n  return (\n    \u003cVGSCollectForm vaultId='\u003cvault_id\u003e' environment='\u003cenvironment\u003e' action='/post'\u003e\n      \u003cTextField name='cardholder-name' validations={['required']} placeholder='Cardholder name' /\u003e\n    \u003c/VGSCollectForm\u003e\n  );\n};\n```\n\n## Integration with Card Management Platform\n\nYou can create a predefined Collect.js form to integrate with the [VGS Card Management Platform](https://docs.verygoodsecurity.com/card-management/api)\n\n```javascript\nimport { VGSCollectForm } from '@vgs/collect-js-react';\n\nconst {CardholderField, CardNumberField, CardExpirationDateField, CardSecurityCodeField } = VGSCollectForm;\n\nconst myApp = () =\u003e {\n  const onSubmitCallback = (status, data) =\u003e {};\n  const onUpdateCallback = (state) =\u003e {};\n\n  return (\n    \u003cVGSCollectForm\n      vaultId='\u003cvault_id\u003e'\n      environment='\u003cenvironment\u003e'\n      submitParamethers={{\n        createCard: {\n          auth: \u003cvgs_auth_token\u003e\n        }\n      }}\n      onUpdateCallback={onUpdateCallback}\n      onSubmitCallback={onSubmitCallback}\n    \u003e\n      \u003cCardholderField css={{}} /\u003e\n      \u003cCardNumberField css={{}} /\u003e\n      \u003cCardExpirationDateField css={{}} /\u003e\n      \u003cCardSecurityCodeField css={{}} /\u003e\n    \u003c/VGSCollectForm\u003e\n  );\n};\n```\n\n## Documentation\n\n- [Collect.js Documentation](https://www.verygoodsecurity.com/docs/vgs-collect/js/integration)\n- [Collect.js Reference Documentation](https://www.verygoodsecurity.com/docs/api/collect)\n\n## Examples\n\nTo run exmaples locally, in the core folder run:\n\n```sh\nyarn install\nyarn start\n```\n\nSwitch the folder to `example` and configure `.env` file, simply rename `.env.example` and replace values\n\n```sh\nREACT_APP_VAULT_ID=\u003cvault_id\u003e\nREACT_APP_ENVIRONMENT=\u003cenv\u003e\nREACT_APP_COLLECT_VERSION=\u003ccollect_version\u003e\n```\n\nFrom `example` folder run:\n\n```sh\nyarn install\nyarn start\n```\n\nOpen [http://localhost:3000/](http://localhost:3000/)\n\n- [Simple Configuration](https://github.com/verygoodsecurity/collect-js-react/blob/main/example/src/features/Basic.tsx)\n- [Custom Payload Configuration](https://github.com/verygoodsecurity/collect-js-react/blob/main/example/src/features/CustomPayload.tsx)\n- [Stackblitz](https://stackblitz.com/edit/react-ts-kuxtvv?file=App.tsx)\n\n## Contact\n\nIf 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).\n\n## License\n\nThis project is licensed under the MIT license. See the [LICENSE](LICENSE) file\nfor details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverygoodsecurity%2Fcollect-js-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fverygoodsecurity%2Fcollect-js-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverygoodsecurity%2Fcollect-js-react/lists"}