@hcaptcha/vue-hcaptcha

中文文档
1.3.0发布于 2023/07/29MITTypeScriptESM + CJS零依赖近 30 天下载 4.1万

hCaptcha Component Library for Vue.js. Compatible with Vue 2 and 3.

原始使用文档
文档目录17 节
  1. Installation
  2. Basic Usage
  3. JS API
  4. Props
  5. Callback Events
  6. Methods
  7. FAQ
  8. How can I get a sitekey?
  9. What is hCaptcha?
  10. Are features like bot scores and No-CAPTCHA/passive mode al…
  11. Demo
  12. TypeScript
  13. Notes for developers
  14. Scripts
  15. Notes for maintainers
  16. Publishing
  17. Contributing + Notable Contributors

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

NameValues/TypeRequiredDefaultDescription
sitekeyStringYes-Your sitekey. Please visit hCaptcha and sign up to get a sitekey.
sizeString (normal, compact, invisible)NonormalThis specifies the "size" of the checkbox. hCaptcha allows you to decide how big the component will appear on render. Defaults to normal.
themeString (light, dark)NolighthCaptcha supports both a light and dark theme. If no theme is set, the API will default to light.
tabindexIntegerNo0Set the tabindex of the widget and popup. When appropriate, this can make navigation of your site more intuitive.
languageString (ISO 639-2 code)NoautohCaptcha auto-detects language via the user's browser. This overrides that to set a default UI language.
reCaptchaCompatBooleanNotrueDisable drop-in replacement for reCAPTCHA with false to prevent hCaptcha from injecting into window.grecaptcha.
challengeContainerStringNo-A custom element ID to render the hCaptcha challenge.
rqdataStringNo-See Enterprise docs.
sentryBooleanNo-See Enterprise docs.
customBooleanNo-See Enterprise docs.
apiEndpointStringNo-See Enterprise docs.
endpointStringNo-See Enterprise docs.
reportapiStringNo-See Enterprise docs.
assethostStringNo-See Enterprise docs.
imghostStringNo-See Enterprise docs.

Callback Events

EventParamsDescription
errorerrWhen an error occurs. Component will reset immediately after an error.
verifytoken, eKeyWhen 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

MethodDescription
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 to get your sitekey. Check documentation for more information.

What is hCaptcha?

hCaptcha 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) for details.

Demo

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 with change details
  3. Push changes to master.

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

版本与发布记录

@hcaptcha/vue-hcaptcha 共发布 17 个版本,首次发布于 2018/09/26;过去 12 个月发布了 0 个版本。

版本发布日期距今
1.3.0latest2023/07/293 年前
1.2.12023/02/063 年前
1.2.02023/02/063 年前
0.4.02023/02/033 年前
0.3.22021/11/105 年前
0.3.12021/10/205 年前

关于 @hcaptcha/vue-hcaptcha 的常见问题

@hcaptcha/vue-hcaptcha 是什么?

hCaptcha Component Library for Vue.js. Compatible with Vue 2 and 3.

如何安装 @hcaptcha/vue-hcaptcha?

在项目目录运行 npm install @hcaptcha/vue-hcaptcha,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:vue(^2.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@hcaptcha/vue-hcaptcha 支持 TypeScript 吗?

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

@hcaptcha/vue-hcaptcha 支持 ESM 还是 CommonJS?

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

@hcaptcha/vue-hcaptcha 可以商用吗?

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

@hcaptcha/vue-hcaptcha 的下载量有多少?

根据 npm 官方下载统计,@hcaptcha/vue-hcaptcha 在 2026/10/18 – 2026/11/16 这 30 天内被下载 41,373 次,日均约 1,379 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hcaptcha/vue-hcaptcha 还在维护吗?

最新版本 1.3.0 发布于 2023/07/29(3 年前);至今共发布 17 个版本,其中过去 12 个月发布了 0 个;首次发布于 2018/09/26。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。