A modern React CAPTCHA component library with advanced human verification
npm install simplify-captchaA modern React CAPTCHA component library with advanced human verification capabilities. Originally ad3. Device-Adaptive Scoring: Automatically detects device capabilities and adjusts scoring:
- Desktop: Focuses on mouse movement patterns and click behaviors
- Mobile: Emphasizes touch gestures and natural finger interactions
- Cross-platform: Adapts to device pixel ratio and input capabilities
4. Intelligent Human Detection: Advanced algorithm analyzes multiple factors:
- Time spent on page and interaction frequency
- Natural timing variations in user actions
- Device-appropriate interaction patterns
- Behavioral consistency and human-like randomness
5. Automatic Verification: If the human score is high enough (โฅ80%), verification passes automatically
6. SVG-Based Fallback CAPTCHA: When automatic verification fails, a beautiful SVG-rendered CAPTCHA is presented with:
- Advanced distortion effects using SVG filters and transformations
- Noise patterns and visual interference to prevent OCR attacks
- Dynamic character styling with random colors, rotations, and scales
- Accessibility features maintaining readability for humans
7. Multiple Attempts: Users get up to 30 attempts to solve the text CAPTCHA Native, this library provides intelligent behavior analysis and fallback text-based verification.
The complete documentation includes:
- ๐ฎ Interactive Demo - Test the component with live behavior tracking
- ๐ Comprehensive API Reference - Complete TypeScript interfaces
- ๐ป Code Examples - Real-world usage patterns
- ๐ Installation Guide - Step-by-step setup instructions
- ๐ค Intelligent Behavior Analysis - Advanced real-time gesture and interaction tracking
- ๐ฑ๏ธ Mouse Movement Tracking - Analyzes cursor patterns, velocity, and natural variations
- ๐ Touch Gesture Recognition - Detects multi-touch gestures and natural mobile interactions
- โจ๏ธ Keyboard Pattern Analysis - Monitors typing rhythm and natural keystroke variations
- ๐ Scroll Behavior Monitoring - Tracks natural scrolling patterns and content engagement
- ๐จ SVG-based CAPTCHA Rendering - High-quality, scalable vector graphics with distortion effects
- ๐ Advanced Text Fallback - Beautiful SVG-rendered CAPTCHA with noise patterns and distortions
- ๐ฑ Responsive Design - Works seamlessly on desktop and mobile devices
- ๐จ Customizable Styling - Easy to customize with CSS classes and inline styles
- โก TypeScript Support - Full TypeScript definitions included
- ๐ Easy Integration - Simple API with ref-based control
- ๐ฏ Zero CSS Imports - Styles are automatically injected, no separate CSS imports needed
- ๐ Automatic Version Bumping - Intelligent semantic versioning with pre-commit hooks
- ๐ง Development Tools - Built-in version management and git hooks for seamless development
``bash`
npm install simplify-captcha
Note: No CSS imports are required! The component automatically injects its styles when used.
The library exports the following TypeScript types:
- SimplifyCaptcha - The main CAPTCHA componentSimplifyCaptchaProps
- - Props interface for the component SimplifyCaptchaRef
- - Ref interface for imperative methodsinjectStyles
- - Utility function for manual style injection
`tsx
import React, { useRef } from 'react';
import { SimplifyCaptcha, SimplifyCaptchaRef } from 'simplify-captcha';
function MyComponent() {
const captchaRef = useRef
const handleCaptchaResult = (event: { nativeEvent: { data: string } }) => {
const { data } = event.nativeEvent;
switch (data) {
case 'verified':
console.log('โ
User verified successfully!');
break;
case 'cancel':
console.log('โ User cancelled verification');
break;
case 'error':
console.log('โ Verification failed - too many attempts');
break;
}
};
return (
API Reference
$3
| Prop | Type | Required | Description |
|------|------|----------|-------------|
|
onMessage | (event: { nativeEvent: { data: string } }) => void | Yes | Callback for verification results |
| style | React.CSSProperties | No | Custom inline styles |
| className | string | No | Custom CSS class name |$3
| Method | Description |
|--------|-------------|
|
show() | Displays the CAPTCHA modal |
| hide() | Hides the CAPTCHA modal |$3
The
onMessage callback receives these possible results:-
'verified' - User passed verification
- 'cancel' - User cancelled the verification process
- 'error' - Verification failed due to too many incorrect attemptsHow It Works
1. Real-Time Gesture Analysis: The component continuously monitors user interactions including:
- Mouse movements: Cursor patterns, velocity changes, and natural variations
- Touch gestures: Multi-touch events, swipe patterns, and pressure sensitivity
- Keyboard interactions: Typing rhythm, keystroke timing, and natural variations
- Scroll behavior: Scrolling patterns indicating natural content consumption
2. Device-Adaptive Scoring: Automatically detects device capabilities and adjusts scoring:
- Desktop: Focuses on mouse movement patterns and click behaviors
- Mobile: Emphasizes touch gestures and natural finger interactions
- Cross-platform: Adapts to device pixel ratio and input capabilities
3. Intelligent Human Detection: Advanced algorithm analyzes multiple factors:
- Time spent on page and interaction frequency
- Natural timing variations in user actions
- Device-appropriate interaction patterns
- Behavioral consistency and human-like randomness
4. Automatic Verification: If the human score is high enough (โฅ80%), verification passes automatically
5. Fallback CAPTCHA: If automatic verification fails, a traditional text-based CAPTCHA is presented
6. Multiple Attempts: Users get up to 30 attempts to solve the text CAPTCHA
Customization
$3
The library automatically injects CSS styles when the component is used. This means:
- โ
No CSS imports needed - Just import the component and it works
- โ
No build configuration required - Styles are bundled with the JavaScript
- โ
No style conflicts - Styles are scoped with
sc- prefix
- โ
SSR compatible - Only injects styles on the client sideIf you need manual control over style injection:
`tsx
import { injectStyles } from 'simplify-captcha';// Manually inject styles (optional - happens automatically)
injectStyles();
`$3
The component uses CSS classes with the
sc- prefix. You can override these styles:`css
/ Override the overlay background /
.sc-overlay {
background-color: rgba(0, 0, 0, 0.8);
}/ Customize the container /
.sc-container {
border-color: #your-color;
background-color: #your-background;
}
/ Style the submit button /
.sc-submit-button {
background-color: #your-primary-color;
}
`$3
`tsx
ref={captchaRef}
onMessage={handleCaptchaResult}
className="my-custom-captcha"
style={{
borderColor: '#ff6b6b',
backgroundColor: '#2c3e50'
}}
/>
`Development
`bash
Install dependencies
npm installStart development server with demo
npm run devBuild the library
npm run buildBuild library only
npm run build:libServe documentation locally
npm run serve:docsVersion management
npm run version:bump # Manual version bump with confirmation
npm run version:bump:auto # Automatic version bump
npm run install:hooks # Install pre-commit hooks for auto-versioning
npm run uninstall:hooks # Remove pre-commit hooks
`๐ง Version Management
This project includes an intelligent automatic version bumping system:
$3
`bash
Install pre-commit hooks for automatic version bumping
npm run install:hooksNow every commit will automatically bump the version based on your changes!
`$3
`bash
Analyze changes and bump version with confirmation
npm run version:bumpAutomatically bump version without confirmation
npm run version:bump:auto
`$3
The system analyzes git changes and determines the appropriate semantic version bump:
- ๐ด MAJOR (X.0.0): Breaking changes, significant core library changes
- ๐ก MINOR (0.X.0): New features, components, API additions
- ๐ข PATCH (0.0.X): Bug fixes, documentation updates, small changes
$3
When pre-commit hooks are installed:
1. Every commit is analyzed for changes
2. Version is automatically bumped based on change significance
3. Updated
package.json is included in your commit
4. No manual version management needed!๐ Documentation Development
To work on the documentation:
1. Local Testing: Run
npm run serve:docs or use the quick-start scripts:
- Linux/Mac: ./quick-start.sh
- Windows: quick-start.bat2. GitHub Pages Setup: See GITHUB_PAGES_SETUP.md for detailed deployment instructions
3. Documentation Files:
-
docs/index.html - Main documentation page
- docs/styles.css - Styling
- docs/script.js - Interactive demo functionalityBrowser Support
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
License
MIT
Contributing
Contributions are welcome! Please follow these guidelines:
$3
When reporting bugs, please include:
- Clear description of the issue
- Steps to reproduce
- Expected vs actual behavior
- Browser/environment details
- Minimal code example
$3
For new features:
- Explain the use case and benefit
- Provide examples of how it would be used
- Consider backward compatibility
$3
1. Fork the repository
2. Create a feature branch:
git checkout -b feature/amazing-feature
3. Install dependencies: npm install
4. Make your changes
5. Test locally: npm run dev and npm run serve:docs
6. Build to ensure no errors: npm run build
7. Commit with clear messages: git commit -m 'Add amazing feature'
8. Push to your branch: git push origin feature/amazing-feature
9. Create a Pull Request$3
For documentation updates:
- Edit files in the
docs/ directory
- Test locally with npm run serve:docs`- Test on multiple browsers (Chrome, Firefox, Safari, Edge)
- Verify both desktop and mobile experiences
- Ensure the behavior analysis works correctly
- Test the fallback text CAPTCHA functionality
- Follow existing TypeScript patterns
- Use meaningful variable and function names
- Add JSDoc comments for public APIs
- Maintain backward compatibility when possible
Thank you for contributing to SimplifyCaptcha! ๐