@hcaptcha/vue-hcaptcha
Version:
hCaptcha Component Library for Vue.js. Compatible with Vue 2 and 3.
157 lines (116 loc) • 8.89 kB
Markdown
# Vue.js hCaptcha Component Library
hCaptcha Component Library for Vue.js. Compatible with Vue 2 and 3.
## Installation
You can install this library via npm with:
* vue2: `npm install @hcaptcha/vue-hcaptcha --save`
* vue3: `npm install @hcaptcha/vue3-hcaptcha --save`
or via yarn:
* vue2: `yarn add @hcaptcha/vue-hcaptcha`
* vue3: `yarn add @hcaptcha/vue3-hcaptcha`
or via script tag (`Vue` must be globally available)
* vue2
```
<script src="https://unpkg.com/vue@2"></script>
<script src="https://unpkg.com/@hcaptcha/vue-hcaptcha"></script>
```
* vue3
```
<script src="https://unpkg.com/vue@3"></script>
<script src="https://unpkg.com/@hcaptcha/vue3-hcaptcha"></script>
```
## Basic Usage
* vue2:
```
<template>
<vue-hcaptcha sitekey="**Your sitekey here**"></vue-hcaptcha>
</template>
<script>
import VueHcaptcha from '@hcaptcha/vue-hcaptcha';
export default {
...
components: { VueHcaptcha }
};
</script>
```
* vue3:
```
<template>
<vue-hcaptcha sitekey="**Your sitekey here**"></vue-hcaptcha>
</template>
<script setup>
import VueHcaptcha from '@hcaptcha/vue3-hcaptcha';
</script>
```
The component will automatically load the hCaptcha API library and append it to the root component.
## JS API
### Props
| Name | Values/Type | Required | Default | Description |
|----------------------|-------------------------------------|-----------|----------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `sitekey` | String | **Yes** | `-` | Your sitekey. Please visit [hCaptcha](https://www.hcaptcha.com) and sign up to get a sitekey. |
| `size` | String (normal, compact, invisible) | No | `normal` | This specifies the "size" of the checkbox. hCaptcha allows you to decide how big the component will appear on render. Defaults to normal. |
| `theme` | String (light, dark) | No | `light` | hCaptcha supports both a light and dark theme. If no theme is set, the API will default to light. |
| `tabindex` | Integer | No | `0` | Set the tabindex of the widget and popup. When appropriate, this can make navigation of your site more intuitive. |
| `language` | String (ISO 639-2 code) | No | `auto` | hCaptcha auto-detects language via the user's browser. This overrides that to set a default UI language. |
| `reCaptchaCompat` | Boolean | No | `true` | Disable drop-in replacement for reCAPTCHA with `false` to prevent hCaptcha from injecting into window.grecaptcha. |
| `challengeContainer` | String | No | `-` | A custom element ID to render the hCaptcha challenge. |
| `rqdata` | String | No | - | See Enterprise docs. |
| `sentry` | Boolean | No | - | See Enterprise docs. |
| `custom` | Boolean | No | - | See Enterprise docs. |
| `apiEndpoint` | String | No | - | See Enterprise docs. |
| `endpoint` | String | No | - | See Enterprise docs. |
| `reportapi` | String | No | - | See Enterprise docs. |
| `assethost` | String | No | - | See Enterprise docs. |
| `imghost` | String | No | - | See Enterprise docs. |
### Callback Events
| Event | Params | Description |
|--------------------|---------------|--------------------------------------------------------------------------|
| `error` | `err` | When an error occurs. Component will reset immediately after an error. |
| `verify` | `token, eKey` | When challenge is completed. The `token` and an `eKey` are passed along. |
| `expired` | - | When the current token expires. |
| `challengeExpired` | - | When the unfinished challenge expires. |
| `opened` | - | When the challenge is opened. |
| `closed` | - | When the challenge is closed. |
| `reset` | - | When the challenge is reset. |
| `rendered` | - | When the challenge is rendered. |
| `executed` | - | When the challenge is executed. |
### Methods
| Method | Description |
|------------------|--------------------------------------------------|
| `execute()` | Programmatically trigger a challenge request |
| `executeAsync()` | Similar to `execute` but it returns a `Promise`. |
| `reset()` | Reset the current challenge |
## FAQ
### How can I get a sitekey?
Sign up at [hCaptcha](https://www.hcaptcha.com) to get your sitekey. Check [documentation](https://docs.hcaptcha.com/api#getapikey) for more information.
### What is hCaptcha?
[hCaptcha](https://www.hcaptcha.com) is a drop-in replacement for reCAPTCHA that earns websites money and helps companies get their data labeled.
### Are features like bot scores and No-CAPTCHA/passive mode also available?
Yes, in the enterprise version: see [hCaptcha Enterprise (BotStop)](https://www.botstop.com) for details.
## Demo
To run the demo:
1. clone this repo `git clone https://github.com/hCaptcha/vue-hcaptcha.git`
2. ```cd examples/traditional-vue2```
3. ```yarn && yarn serve```
* it will start the demo app on localhost:8080
* open your console to see the demo app emitting events
## TypeScript
TypeScript is supported. You can see example apps for both `vue2` and `vue3` in `examples` directory.
## Notes for developers
### Scripts
* `yarn lint` - will check for lint issues
* `yarn test` - will test both vue2 and vue3 packages
* `yarn build` - will build the production vue2,3 versions
## Notes for maintainers
### Publishing
To publish a new version, follow the next steps:
1. Bump the versions for both: `vue2/package.json` and `vue3/package.json` (keep them in sync)
2. Fill [`CHANGES.md`](./CHANGES.md) with change details
3. Push changes to master.
* CI/CD pipeline will publish the new version(s) to: [@hcaptcha/vue-hcaptcha](https://www.npmjs.com/package/@hcaptcha/vue-hcaptcha) or [@hcaptcha/vue3-hcaptcha](https://www.npmjs.com/package/@hcaptcha/vue3-hcaptcha).
## Contributing + Notable Contributors
`vue-hcaptcha` is developed and maintained through the collective efforts of the hCaptcha community.
This includes developers like you! We welcome your issues, suggestions, and PRs.
Notable contributors for larger changes:
- Vue2 support: hCaptcha team
- Vue3 support: JDinABox and DSergiu