Dependencies

• Required: Vue.js >= 3.2 (peer dependency)

Installation

npm install vue-client-recaptcha --save

yarn add vue-client-recaptcha

Usage

Basic

<script setup>
import { ref } from 'vue';
import { VueClientRecaptcha } from 'vue-client-recaptcha';

const inputValue = ref('');
const isValid = ref(false);
const captchaRef = ref(null);

const getCaptchaCode = (code) => console.log('Code:', code);
const checkValidCaptcha = (valid) => console.log('Valid:', valid);
</script>

<template>
  <div>
    <input v-model="inputValue" placeholder="Enter captcha" />
    <VueClientRecaptcha
      ref="captchaRef"
      v-model="inputValue"
      v-model:valid="isValid"
      @getCode="getCaptchaCode"
      @isValid="checkValidCaptcha"
    />
    <button @click="captchaRef?.resetCaptcha()">Reset</button>
  </div>
</template>

v-model

• v-model – binds user input for validation
• v-model:valid – binds validation state (boolean)

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | modelValue / value | string | "" | User input to validate | | chars | string | alphanumeric | Custom chars when charsPreset is "custom" | | charsPreset | "alphanumeric" \| "numeric" \| "letters" \| "custom" | "alphanumeric" | Character preset | | count | number | 5 | Number of captcha characters | | hideLines | boolean | false | Hide distortion lines | | customTextColor | string | "" | Fixed text color | | textColors | string[] | [] | Random text colors | | width | number \| (p) => number | p.count * 30 | Canvas width | | height | number | 50 | Canvas height | | radius | number | 0 | Border radius (px) | | hideRefreshIcon | boolean | false | Hide refresh button | | refreshLabel | string | "Refresh captcha" | A11y label for refresh | | canvasLabel | string | "Captcha image" | A11y label for canvas | | theme | "auto" \| "light" \| "dark" | "light" | Theme mode | | distortion | "none" \| "lines" \| "dots" \| "both" | "lines" | Distortion type | | noiseDots | number | 0 | Number of noise dots (0 = off) | | noiseLines | number | -1 | Distortion lines (-1 = use count) | | audioEnabled | boolean | false | Speak code for screen readers | | simpleMode | boolean | false | Clean, straight-line text with single color |

Events

| Event | Payload | Description | |-------|---------|-------------| | getCode | string | Emitted with captcha code on generate/refresh | | isValid | boolean | Validation state changed | | update:valid | boolean | v-model:valid sync | | refresh | string | Captcha regenerated | | ready | – | Canvas ready | | error | unknown | Canvas/context error |

Composable

<script setup>
import { useCaptcha } from 'vue-client-recaptcha';

const { code, generate, validate, reset } = useCaptcha({
  charsPreset: 'numeric',
  count: 4
});

generate(); // Generate new code
const ok = validate('1234'); // Check input
</script>

Security Note

This is a client-side captcha. It provides light protection against casual bots but is not a substitute for server-side validation. Do not rely on it for high-security use cases. Use reCAPTCHA or similar server-verified solutions for strong protection.

Migration from v1 to v2

1. Vue peer dependency – Add Vue 3.2+ as a peer dependency in your project.
2. value prop – Prefer v-model or modelValue; value is deprecated but still supported.
3. width prop – Function default (p) => p.count * 30 is now correctly resolved (v1 had a bug).
4. isDirty – Removed (was unused).

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT