@captcha-la/vue

English · 简体中文

Official Captchala CAPTCHA Vue 3 component - Smart CAPTCHA protection for your Vue applications.

Installation

npm install @captcha-la/vue
# or
yarn add @captcha-la/vue
# or
pnpm add @captcha-la/vue

Quick Start

<template>
  <Captchala
    app-key="your-app-key"
    product="popup"
    @success="handleSuccess"
    @error="handleError"
  />
</template>

<script setup>
import { Captchala } from '@captcha-la/vue'

function handleSuccess(result) {
  console.log('Verification successful!')
  console.log('Token:', result.token)
  // Send token to your server for validation
}

function handleError(error) {
  console.error('Verification failed:', error)
}
</script>

Props

Prop	Type	Default	Description
appKey	string	required	Your Captchala application key
serverToken	string	-	One-time, server-issued challenge token. Required when the app has server_token_required=true. See Production: serverToken mode below.
product	'popup' | 'float' | 'embed' | 'bind'	'popup'	Display mode
action	string	'default'	Action identifier (e.g., 'login', 'register', 'checkout')
lang	string	'zh-CN'	Language code ('zh-CN', 'en', 'ja', etc.)

Events

Event	Payload	Description
success	{ token, type, action }	Fired when verification succeeds
error	error	Fired when verification fails
close	-	Fired when CAPTCHA is closed
ready	-	Fired when CAPTCHA is ready

Methods (via ref)

<template>
  <Captchala ref="captchaRef" app-key="your-app-key" />
  <button @click="handleVerify">Verify</button>
</template>

<script setup>
import { ref } from 'vue'
import { Captchala } from '@captcha-la/vue'

const captchaRef = ref()

function handleVerify() {
  captchaRef.value?.verify()
}
</script>

Method	Description
verify()	Trigger verification
reset()	Reset CAPTCHA state
destroy()	Destroy CAPTCHA instance
bindTo(selector)	Bind to element (for 'bind' mode)

Display Modes

Popup Mode (Default)

Shows a button that triggers a popup CAPTCHA dialog.

<Captchala app-key="your-key" product="popup" />

Float Mode

Displays an inline floating CAPTCHA widget.

<Captchala app-key="your-key" product="float" />

Embed Mode

Embeds the CAPTCHA directly in the page.

<Captchala app-key="your-key" product="embed" />

Bind Mode

Binds CAPTCHA to an existing button - verifies when the button is clicked.

<template>
  <Captchala
    ref="captchaRef"
    app-key="your-key"
    product="bind"
    @success="handleSuccess"
  />
  <button id="submit-btn">Submit</button>
</template>

<script setup>
import { ref, onMounted } from 'vue'

const captchaRef = ref()

onMounted(() => {
  captchaRef.value?.bindTo('#submit-btn')
})

function handleSuccess(result) {
  // Form can now be submitted with result.token
}
</script>

Production: using serverToken

For production (login, registration, payment, etc.) we recommend the server-issued token flow. Your backend holds the app secret, calls POST /v1/server/challenge/issue with X-App-Key + X-App-Secret to mint a one-time server_token (5-minute TTL), and hands that token to the browser.

<template>
  <div v-if="!serverToken">Loading...</div>
  <Captchala
    v-else
    :server-token="serverToken"
    app-key="pk_your_public_app_key"
    action="login"
    @success="onSuccess"
  />
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { Captchala } from '@captcha-la/vue'

const serverToken = ref<string>()

onMounted(async () => {
  // Your own backend endpoint that proxies /v1/server/challenge/issue
  const r = await fetch('/api/captcha-token')
  const d = await r.json()
  serverToken.value = d.server_token
})

function onSuccess(result: { token: string }) {
  console.log('pass_token:', result.token)
}
</script>

Example backend endpoint (Node.js / Express):

// server.js — call this from your own /api/captcha-token handler
app.get('/api/captcha-token', async (req, res) => {
  const r = await fetch('https://apiv1.captcha.la/v1/server/challenge/issue', {
    method: 'POST',
    headers: {
      'X-App-Key': process.env.CAPTCHALA_APP_KEY,
      'X-App-Secret': process.env.CAPTCHALA_APP_SECRET,
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: 'action=login&ttl=300'
  })
  const { data } = await r.json()
  res.json({ server_token: data.server_token })
})

Notes:

• Never embed X-App-Secret in browser code.
• Each server_token can be used exactly once. Regenerate before every widget mount.
• Legacy apps with server_token_required=false can still use the public appKey-only flow.

Server-side Validation

After receiving the token from onSuccess, validate it on your server:

// Your backend
const response = await fetch('https://api.captcha.la/v1/risk/consume', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-App-Key': 'your-app-key',
    'X-App-Secret': 'your-app-secret'
  },
  body: JSON.stringify({ token })
})

const result = await response.json()
if (result.code === 0 && result.data.valid) {
  // Token is valid, proceed with the request
}

TypeScript Support

Full TypeScript support is included:

import { Captchala, type CaptchalaProps, type CaptchalaResult } from '@captcha-la/vue'

License

MIT License - see LICENSE for details.

Links

• Website
• Documentation
• Dashboard