🎯 Slider Captcha Library

A lightweight, customizable slider captcha for JavaScript, React, and TypeScript.
Supports UMD + ESM builds, themes, async verification, and server integration.
Perfect for adding a secure, interactive human verification step to your apps.

---

🌐 Demo

A live demo is available on GitHub Pages:
https://amazingdevteam.github.io/slider-captcha-js

---

✨ Features

• ⚡ Works in Vanilla JS, React, and TypeScript
• 📦 UMD + ESM builds
• 🎨 Customizable size, theme (light / dark), and image source
• 🔄 Built-in refresh button with hover effects
• 🔒 No backend required, but supports async onVerify and request() for server integration
• 🪶 Lightweight and dependency-free
• 🖼️ Canvas fallback with gradient if image fails to load
• 🧩 Complex puzzle piece shape with shadows and outlines
• 🚫 Auto-refresh after 3 failed attempts

---

⚙️ Options & Logic

Both the function API (sliderCaptcha) and the class API (new SliderCaptcha) accept an options object.

Validation & Image Source Logic

• If request + onVerify are provided → the captcha will use server-side validation.
• Otherwise → it falls back to client-side validation (local puzzle check).
• If imageUrl is provided → it will use that as the custom image source.
• Otherwise → it falls back to a default random image (picsum).

Available Options

Option	Type	Default	Description
root	string / HTMLElement	null	Container element where captcha will render
width	number / string	320	Width of the captcha
height	number	160	Height of the captcha
fit	"cover" / "contain" / "stretch"	"cover"	How the image should fit
imageUrl	string / null	null	Custom image URL for the captcha background (overrides default/request)
crossOrigin	string / null	null	Cross-origin setting for images
theme	"light" / "dark"	"light"	Theme mode
successText	string	"✅ Verified!"	Success message
failText	string	"❌ Try again!"	Failure message
onSuccess	function	() => {}	Callback when verification succeeds
onFail	function	() => {}	Callback when verification fails
onRefresh	function	() => {}	Callback when captcha is refreshed
onVerify	function	null	Optional async callback for custom verification
request	function	null	Optional async function returning { bgUrl, puzzleUrl }

---

🚀 Installation

npm install slider-captcha-js

or via CDN:

<link rel="stylesheet" href="https://unpkg.com/slider-captcha-js/dist/slider-captcha.css" />
<script src="https://unpkg.com/slider-captcha-js/dist/slider-captcha.umd.js"></script>
<script>
  const captcha = new SliderCaptcha({
    root: "#stage",
    width: 320,
    height: 160,
    onSuccess: () => alert("Verified!"),
    onFail: () => alert("Try again"),
  });

  captcha.refresh();
</script>

---

💻 Usage

Vanilla JavaScript

<div id="stage"></div>
<script type="module">
  import { SliderCaptcha } from "slider-captcha-js";

  const captcha = new SliderCaptcha({
    root: "#stage",
    width: 320,
    height: 160,
    theme: "dark",
    onSuccess: () => alert("Verified!"),
    onFail: () => alert("Try again"),
  });

  captcha.refresh();
</script>

React (JavaScript)

import SliderCaptcha from "slider-captcha-js/react";
import { useRef } from "react";

function App() {
  const captchaRef = useRef(null);

  return (
    <div>
      <SliderCaptcha
        ref={captchaRef}
        width={320}
        height={160}
        theme="light"
        onSuccess={() => console.log("Verified!")}
        onFail={() => console.log("Try again")}
      />
      <button onClick={() => captchaRef.current?.refresh()}>Refresh</button>
    </div>
  );
}

React (TypeScript)

import SliderCaptcha, { type SliderCaptchaRef } from "slider-captcha-js/react";
import { useRef } from "react";

function App() {
  const captchaRef = useRef<SliderCaptchaRef>(null);

  return (
    <div>
      <SliderCaptcha
        ref={captchaRef}
        width={320}
        height={160}
        theme="light"
        onSuccess={() => console.log("Verified!")}
        onFail={() => console.log("Try again")}
      />
      <button onClick={() => captchaRef.current?.refresh()}>Refresh</button>
    </div>
  );
}

TypeScript

import { SliderCaptcha } from "slider-captcha-js";

const captcha = new SliderCaptcha({
  root: "#stage",
  width: 320,
  height: 160,
  onVerify: async ({ x, duration, trail }) => {
    // Custom async verification
    if (Math.abs(x - 100) < 6) return true;
    throw new Error("Verification failed");
  },
});

---

🔒 Backend Integration

sliderCaptcha({
  root: "#captcha",
  request: async () => {
    const res = await fetch("/api/captcha");
    return res.json(); // { bgUrl, puzzleUrl }
  },
  onVerify: async (data) => {
    const res = await fetch("/api/captcha/verify", {
      method: "POST",
      body: JSON.stringify(data),
    });
    const result = await res.json();
    if (!result.success) throw new Error("Invalid");
  },
});

---

🎨 Theming

.my-dark-theme .slider-captcha-bar {
  background: #222;
  color: #eee;
}
.my-dark-theme .slider-captcha-refresh {
  color: #0af;
}

---

🛠 Build

npm run build

Outputs:

• dist/slider-captcha.umd.js
• dist/slider-captcha.esm.js
• dist/react-slider-captcha.js
• dist/react-slider-captcha.esm.js

---

📜 License

MIT © 2025