hcaptchavue3 v0.1.3
hCaptchaVue3 - Vue 3 hCaptcha Component
A Vue 3 SFC component to add a hCaptcha user validation widget.
- For use in Vue 3 Projects
- All configuration passed in with props, including size, theme, tab index and dark mode
- All hCaptcha events emitted for handling in parent component
- Optional custom endpoint server validation
- Enterprise options (rqdata, sentry etc.) not currently supported
This package created for internal use, feel free to use but support will be limited
Install
npm install hcaptchavue3
Dependencies
- vue ^3.0.0
Usage
To include in existing Vue 3 Project
- Import and declare in the parent component
import hcaptchavue3 from "hcaptchavue3"; ... export default { components: { hcaptchavue3, }, ... }
Add to the template, with your site key (defaults to test key)
<template> ... <hcaptchavue3 @verified="handleVerification($event)" sitekey="10000000-ffff-ffff-ffff-000000000001"> </hcaptchavue3> ... </template>
Include methods for any emitted event handling
... setup() { ... const handleVerification = ref((payload) => { console.log(payload); }); ... return { handleVerification }; },
Config
Props
See hCaptcha docs for valid values of the configuration options. (The data- prefix is not required)
https://docs.hcaptcha.com/configuration#hcaptcha-container-configuration
Prop Name | Type | Required | Default |
---|---|---|---|
sitekey | String | Yes | 10000000-ffff-ffff-ffff-000000000001 |
size | String | No | normal |
theme | String | No | light |
tabindex | String | No | 0 |
apiurl | String | No | https://js.hcaptcha.com/1/api.js |
validateendpoint | String | No | |
inclcredentials | Boolean | No | False |
apiurl
is currently the correct endpoint for hCaptcha. If changed, the final URL used will have the following options appended: -render
:explicit
-recaptchacompat
:off
validateendpoint
should be omitted if it is not required for the component to confirm response token with a server endpoint. Adding a value forvalidateendpoint
will trigger the component to attempt server validation. See below.
Emitted Events
Other than the verified
and serverResponse
events, the events are emitted by the hCapctha API
Event | Payload | Trigger |
---|---|---|
verified | Object: {token: String, eKey: String} | hCaptcha completed successfully by user |
error | "error":String | See "data-error-callback" in hCaptcha docs |
expired | "expired":String | See "data-expired-callback" in hCaptcha docs |
challengeExpired | "chalexpired":String | See "data-chalexpired-callback" in hCaptcha docs |
opened | "opened":String | See "data-open-callback" in hCaptcha docs |
closed | "closed":String | See "data-close-callback" in hCaptcha docs |
serverResponse | Object: {status: Int \| String, Response: Object} | Validation endpoint fetch completed |
Server Validation
As the hCaptcha secret key is required to validate the key returned from on-page verification, this validation should take place server side. The component can complete the additional step of calling this server side script and return its response. The script that performs the server-side validation is not covered by this package.
Configuration
If the validateendpoint
prop is passed with an URL value, the component will make a POST Fetch request to that URL after the user has successfully completed the on-page verification. The verified
event will still fire directly after on-page verification.
<template>
...
<hcaptchavue3
...
validateendpoint="https://xyz.com/validate">
</hcaptchavue3>
...
</template>
Optionally, a prop inclcredentials
can be added, if required:
<template>
...
<hcaptchavue3
...
validateendpoint="https://xyz.com/validate"
:inclcredentials=true>
</hcaptchavue3>
...
</template>
If it is required to post additional fields to the server, input
elements can be added in the default slot.
Note: Only input
fields of type hidden
are passed
<template>
...
<hcaptchavue3 ...>
<input type="hidden" name="extra" value="xyz">
</hcaptchavue3>
...
</template>
Request
After on-page verification is completed, the POST request will be made to the endpoint specified in validateendpoint
, passing the following fields as form data
Input Field Name | Value Characterisation |
---|---|
key | The key returned by the hCaptcha API after on-page verification |
eKey | The ekey retuend by the hCaptcha API after on-page verification |
If input
fields of type hidden
were found in the default slot, they will also be posted as form fields with the name and values as defined in the slot.
Response
Upon receiving the response from the server endpoint, the serverResponse
event will be emitted by the component
Event | Payload | Trigger |
---|---|---|
serverResponse | Object: {status: Int \| String, Response: Object} | Validation endpoint fetch completed |
status
- If there was an error during Fetch this will be the string "error". Otherwise it will be thestatus
property of the response object. Generally if the validation endpoint returns status 200 on success, this is all that needs to be checkedResponse
- This will be the complete response object, as returned from the endpoint