Class CaptchaGenerator

Advanced CAPTCHA generator class with fluent API for creating highly customizable CAPTCHAs.

This class provides a builder pattern interface for generating secure CAPTCHA images with extensive customization options including text styling, background images, trace lines, and decoy characters for enhanced security.

Example: Basic usage

const captcha = new CaptchaGenerator()
  .setDimension(300, 100)
  .setCaptcha({ text: 'HELLO', size: 50 });

const buffer = await captcha.generate();
console.log('Generated text:', captcha.text);

Example: Advanced customization

const captcha = new CaptchaGenerator({ width: 400, height: 150 })
  .setCaptcha({
    text: 'SECURE',
    size: 60,
    colors: ['#ff6b6b', '#4ecdc4', '#45b7d1'],
    rotate: 15,
    skew: true
  })
  .setTrace({ color: '#95a5a6', size: 3, opacity: 0.7 })
  .setDecoy({ total: 50, opacity: 0.4 })
  .setBackground('./background.jpg');

const buffer = await captcha.generate();

Since

2.0.0

Index

Constructors

constructor

new CaptchaGenerator(
options?: { height: number; width: number },
): CaptchaGenerator
Creates a new CaptchaGenerator instance with specified dimensions.

Initializes the generator with default settings and random text generation. All configuration methods can be chained after construction for fluent API usage.
Parameters
- options: { height: number; width: number } = ...
  Configuration options for the CAPTCHA generator
  - height: number
    Height of the CAPTCHA image in pixels (default: 100)
  - width: number
    Width of the CAPTCHA image in pixels (default: 300)
Returns CaptchaGenerator
Example: Basic initialization
```
const captcha = new CaptchaGenerator();
// Creates 300x100 CAPTCHA with default settings
```
Example: Custom dimensions
```
const captcha = new CaptchaGenerator({ height: 200, width: 600 });
// Creates 600x200 CAPTCHA
```
Since
2.0.0
- Defined in src/CaptchaGenerator.ts:72

Accessors

text

get text(): string
Gets the current CAPTCHA text that will be displayed in the image.

This property returns the text that users need to enter to solve the CAPTCHA. For array-based captchas with multiple text segments, it returns the concatenated result.

Returns string
The complete CAPTCHA text string
Example
```
const captcha = new CaptchaGenerator()
  .setCaptcha({ text: 'HELLO' });

console.log(captcha.text); // Output: "HELLO"
```
Example: Array-based captcha
```
const captcha = new CaptchaGenerator()
  .setCaptcha([
    { text: 'HE', color: '#ff0000' },
    { text: 'LLO', color: '#00ff00' }
  ]);

console.log(captcha.text); // Output: "HELLO"
```
Since
2.0.3
- Defined in src/CaptchaGenerator.ts:111

Methods

setDimension

setDimension(height: number, width: number): CaptchaGenerator
Sets the dimensions of the CAPTCHA image.

This method allows you to customize the width and height of the generated CAPTCHA image. Larger dimensions provide more space for text and security features but result in larger file sizes.
Parameters
- height: number
  Height of the CAPTCHA image in pixels
- width: number
  Width of the CAPTCHA image in pixels
Returns CaptchaGenerator
The CaptchaGenerator instance for method chaining
Example: Standard web form size
```
const captcha = new CaptchaGenerator()
  .setDimension(150, 400);
```
Example: Large size for better readability
```
const captcha = new CaptchaGenerator()
  .setDimension(200, 600)
  .setCaptcha({ size: 80 }); // Larger text for larger canvas
```
Example: Mobile-friendly dimensions
```
const captcha = new CaptchaGenerator()
  .setDimension(100, 250);
```
Since
2.0.0
- Defined in src/CaptchaGenerator.ts:148

setBackground

setBackground(image: string | Buffer): CaptchaGenerator
Sets a background image for the CAPTCHA to increase visual complexity and security.

Background images make it significantly harder for OCR systems to automatically solve the CAPTCHA while maintaining human readability. The image will be scaled to fit the CAPTCHA dimensions.
Parameters
- image: string | Buffer
  Image source as file path, URL, or Buffer
Returns CaptchaGenerator
The CaptchaGenerator instance for method chaining
Example: Using a local file path
```
const captcha = new CaptchaGenerator()
  .setBackground('./assets/noise-pattern.jpg')
  .setCaptcha({ opacity: 0.9 }); // Make text more visible over background
```
Example: Using a URL
```
const captcha = new CaptchaGenerator()
  .setBackground('https://example.com/background.png');
```
Example: Using a Buffer
```
import fs from 'fs';

const imageBuffer = fs.readFileSync('./background.jpg');
const captcha = new CaptchaGenerator()
  .setBackground(imageBuffer);
```
Since
2.0.0
- Defined in src/CaptchaGenerator.ts:187

setCaptcha

setCaptcha(option: SetCaptchaOption | SetCaptchaOption[]): CaptchaGenerator

Configures the CAPTCHA text appearance and content.

This method allows extensive customization of the CAPTCHA text including font, size, colors, rotation, skewing, and the actual text content. Supports both single configuration objects and arrays for multi-styled text segments.

Parameters

option: SetCaptchaOption | SetCaptchaOption[]
Single captcha configuration or array of configurations for multi-styled text

Returns CaptchaGenerator

The CaptchaGenerator instance for method chaining

Example: Basic text customization

const captcha = new CaptchaGenerator()
  .setCaptcha({
    text: 'SECURE',
    font: 'Arial',
    size: 60,
    color: '#2c3e50'
  });

Example: Advanced styling with rotation and skewing

const captcha = new CaptchaGenerator()
  .setCaptcha({
    text: 'VERIFY',
    size: 50,
    rotate: 20,        // Random rotation up to ±20 degrees
    skew: true,        // Apply random skewing
    opacity: 0.8       // Semi-transparent text
  });

Example: Multi-color text using colors array

const captcha = new CaptchaGenerator()
  .setCaptcha({
    text: 'RAINBOW',
    size: 45,
    colors: ['#e74c3c', '#f39c12', '#f1c40f', '#27ae60', '#3498db', '#9b59b6']
  });

Example: Multi-styled text segments

const captcha = new CaptchaGenerator()
  .setCaptcha([
    { text: 'SEC', size: 50, color: '#e74c3c', font: 'Arial' },
    { text: 'URE', size: 45, color: '#27ae60', font: 'Times' }
  ]);

Example: Random text generation

const captcha = new CaptchaGenerator()
  .setCaptcha({
    characters: 8,     // Generate 8 random characters
    size: 40,
    colors: ['#34495e', '#e67e22']
  });

Since

2.0.0

setTrace

setTrace(option: SetTraceOption): CaptchaGenerator

Configures trace lines that connect CAPTCHA characters for enhanced security.

Trace lines are drawn connecting the CAPTCHA characters, making it significantly harder for automated systems to segment and recognize individual characters while maintaining human readability.

Parameters

option: SetTraceOption
Trace line appearance configuration

Returns CaptchaGenerator

The CaptchaGenerator instance for method chaining

Example: Basic trace line

const captcha = new CaptchaGenerator()
  .setCaptcha({ text: 'HELLO' })
  .setTrace({ color: '#95a5a6', size: 3 });

Example: Subtle trace for better readability

const captcha = new CaptchaGenerator()
  .setCaptcha({ text: 'VERIFY' })
  .setTrace({
    color: '#bdc3c7',
    size: 2,
    opacity: 0.6      // Semi-transparent trace
  });

Example: Bold security trace

const captcha = new CaptchaGenerator()
  .setCaptcha({ text: 'SECURE' })
  .setTrace({
    color: '#e74c3c',
    size: 5,
    opacity: 0.8
  });

Example: Disable trace lines

const captcha = new CaptchaGenerator()
  .setCaptcha({ text: 'CLEAN' })
  .setTrace({ opacity: 0 }); // Completely transparent = disabled

Since

2.0.0

setDecoy

setDecoy(option: SetDecoyOption): CaptchaGenerator

Configures decoy characters that add visual noise to prevent automated solving.

Decoy characters are randomly placed fake characters that confuse OCR systems while being distinguishable from the actual CAPTCHA text by humans through differences in opacity, size, or color.

Parameters

option: SetDecoyOption
Decoy characters configuration

Returns CaptchaGenerator

The CaptchaGenerator instance for method chaining

Example: Basic decoy setup

const captcha = new CaptchaGenerator()
  .setCaptcha({ text: 'HELLO' })
  .setDecoy({
    total: 30,
    opacity: 0.3,
    color: '#95a5a6'
  });

Example: Subtle decoys for clean look

const captcha = new CaptchaGenerator()
  .setCaptcha({ text: 'VERIFY' })
  .setDecoy({
    total: 15,
    size: 12,
    opacity: 0.2,
    font: 'Arial'
  });

Example: Heavy security with many decoys

const captcha = new CaptchaGenerator()
  .setCaptcha({ text: 'SECURE' })
  .setDecoy({
    total: 50,
    size: 18,
    opacity: 0.4,
    color: '#7f8c8d'
  });

Example: Disable decoy characters

const captcha = new CaptchaGenerator()
  .setCaptcha({ text: 'SIMPLE' })
  .setDecoy({ opacity: 0 }); // No decoy characters

Since

2.0.0

generate

generate(): Promise<Buffer>

Generates the final CAPTCHA image as a PNG buffer asynchronously.

This method renders all configured elements (background, decoys, text, traces) into a final PNG image buffer that can be saved to file or sent to clients. The generation process is asynchronous to handle background image loading.

Returns Promise<Buffer>

Promise that resolves to a PNG image buffer

Example: Basic generation and file saving

import fs from 'fs';

const captcha = new CaptchaGenerator()
  .setCaptcha({ text: 'HELLO' });

const buffer = await captcha.generate();
fs.writeFileSync('captcha.png', buffer);
console.log('CAPTCHA text:', captcha.text);

Example: Web server response

import express from 'express';

app.get('/captcha', async (req, res) => {
  const captcha = new CaptchaGenerator()
    .setDimension(300, 100)
    .setCaptcha({ characters: 6 });
  
  const buffer = await captcha.generate();
  
  // Store captcha.text in session for verification
  req.session.captcha = captcha.text;
  
  res.type('png').send(buffer);
});

Example: Complete customization

const captcha = new CaptchaGenerator({ width: 400, height: 150 })
  .setBackground('./noise-bg.jpg')
  .setCaptcha({
    text: 'SECURE',
    size: 60,
    colors: ['#e74c3c', '#3498db'],
    rotate: 15
  })
  .setTrace({ color: '#95a5a6', size: 3 })
  .setDecoy({ total: 40, opacity: 0.3 });

const buffer = await captcha.generate();

Throws

When background image fails to load or other rendering errors occur

Since

2.0.0

generateSync

generateSync(option?: { background?: Image }): Buffer

Generates the CAPTCHA image synchronously without async/await.

This method provides synchronous CAPTCHA generation for use cases where async operations are not suitable. Note that background images set via setBackground() are ignored - use the background parameter instead.

Parameters

option: { background?: Image } = {}
Additional options for synchronous generation
- Optionalbackground?: Image
  Pre-loaded background image (use resolveImage() to load)

Returns Buffer

PNG image buffer

Example: Basic synchronous generation

const captcha = new CaptchaGenerator()
  .setCaptcha({ text: 'SYNC' });

const buffer = captcha.generateSync();
fs.writeFileSync('captcha.png', buffer);

Example: With pre-loaded background image

import { CaptchaGenerator, resolveImage } from 'captcha-canvas';

// Load background image first
const backgroundImage = await resolveImage('./background.jpg');

const captcha = new CaptchaGenerator()
  .setCaptcha({ text: 'HELLO' });

// Generate synchronously with background
const buffer = captcha.generateSync({ background: backgroundImage });
fs.writeFileSync('captcha.png', buffer);

Example: Synchronous generation in non-async context

function createCaptchaSync() {
  const captcha = new CaptchaGenerator()
    .setDimension(250, 80)
    .setCaptcha({ characters: 5, size: 35 })
    .setTrace({ size: 2, opacity: 0.7 });
  
  return {
    buffer: captcha.generateSync(),
    text: captcha.text
  };
}

Note: Background images set via setBackground() are not used in sync mode. Use the background parameter with pre-loaded images instead.

Since

2.2.0

Class CaptchaGenerator

Example: Basic usage

Example: Advanced customization

Since

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

height: number

width: number

Returns CaptchaGenerator

Example: Basic initialization

Example: Custom dimensions

Since

Accessors

text

Returns string

Example

Example: Array-based captcha

Since

Methods

setDimension

Parameters

Returns CaptchaGenerator

Example: Standard web form size

Example: Large size for better readability

Example: Mobile-friendly dimensions

Since

setBackground

Parameters

Returns CaptchaGenerator

Example: Using a local file path

Example: Using a URL

Example: Using a Buffer

Since

setCaptcha

Parameters

Returns CaptchaGenerator

Example: Basic text customization

Example: Advanced styling with rotation and skewing

Example: Multi-color text using colors array

Example: Multi-styled text segments

Example: Random text generation

Since

setTrace

Parameters

Returns CaptchaGenerator

Example: Basic trace line

Example: Subtle trace for better readability

Example: Bold security trace

Example: Disable trace lines

Since

setDecoy

Parameters

Returns CaptchaGenerator

Example: Basic decoy setup

Example: Subtle decoys for clean look

Example: Heavy security with many decoys

Example: Disable decoy characters

Since

generate

Returns Promise<Buffer>

Example: Basic generation and file saving

Example: Web server response

Example: Complete customization

Throws

Since

generateSync

Parameters

Optionalbackground?: Image

Returns Buffer

Example: Basic synchronous generation

Example: With pre-loaded background image

Example: Synchronous generation in non-async context

Since

Settings

On This Page

`Optional`background?: Image