Widget API

The KEPCA widget is a standard Web Component (<maptcha-widget>) that handles the entire challenge flow inside a Shadow DOM.

Installation

Script tag (recommended)

<script src="https://cdn.kepca.com/v1/maptcha.js" defer></script>

NPM / ESM

pnpm add @maptcha/widget

import '@maptcha/widget';
// The <maptcha-widget> custom element is auto-registered on import.

HTML attributes

Attribute	Type	Default	Description
data-sitekey	string	(required)	Your site key from the dashboard.
data-mode	string	adaptive	Verification mode: adaptive, invisible, checkbox, always-challenge.
data-lang	string	auto-detect	Language code: en, tr, de, fr, es, ar, zh, ja, ru. Falls back to browser locale, then en.
data-theme	string	auto	Visual theme: light, dark, auto. Auto follows prefers-color-scheme.
data-endpoint	string	Production default	Override the KEPCA API URL. Useful for self-hosted or local development.

Example

<maptcha-widget
  data-sitekey="mpt_site_abc123"
  data-mode="adaptive"
  data-lang="tr"
  data-theme="dark"
  data-endpoint="https://api.kepca.com"
></maptcha-widget>

Events

The widget dispatches Custom Events that bubble and cross Shadow DOM boundaries (composed: true).

verify

Fired when verification succeeds. Contains the signed token.

widget.addEventListener('verify', (e) => {
  console.log(e.detail.token);
  // "eyJhbGciOiJIUzI1NiIsInYiOjF9.eyJzayI6Im1wdF9zaXRlXy..."
});

e.detail:

Field	Type	Description
token	string	HMAC-signed captcha token

error

Fired when verification fails (network error, invalid session, challenge expired, etc.).

widget.addEventListener('error', (e) => {
  console.error(e.detail.error);
  // "challenge_expired", "invalid_session", "network_error", etc.
});

e.detail:

Field	Type	Description
error	string	Error code or message

expire

Fired when a previously issued token expires (after 120 seconds).

widget.addEventListener('expire', () => {
  // Disable submit button, prompt re-verification
  submitBtn.disabled = true;
});

No detail payload.

CSS custom properties

The widget's Shadow DOM reads these CSS custom properties from the host element. Override them to match your site's design:

maptcha-widget {
  --mpt-bg: #ffffff;
  --mpt-text: #333333;
  --mpt-border: #d1d5db;
  --mpt-border-hover: #9ca3af;
  --mpt-check: #22c55e;
  --mpt-error: #ef4444;
  --mpt-brand: #6366f1;
  --mpt-shadow: rgba(0, 0, 0, 0.08);
}

Property	Default (light)	Description
--mpt-bg	#ffffff	Container background
--mpt-text	#333333	Label text color
--mpt-border	#d1d5db	Border color
--mpt-border-hover	#9ca3af	Border on hover
--mpt-check	#22c55e	Checkmark / success color
--mpt-error	#ef4444	Error indicator color
--mpt-brand	#6366f1	Brand accent (spinner, logo)
--mpt-shadow	rgba(0,0,0,.08)	Box shadow color

Programmatic usage

For advanced use cases you can interact with the widget class directly:

MaptchaAPI

Low-level API client for the challenge service.

import { MaptchaAPI } from '@maptcha/widget';

const api = new MaptchaAPI('https://api.kepca.com');

// 1. Init session
const init = await api.init('mpt_site_abc123', {
  timestamp: Date.now(),
  time_on_page_ms: 5200,
  user_agent: navigator.userAgent,
});

// 2. Get challenge (if required)
if (init.requires_challenge) {
  const ch = await api.challenge('mpt_site_abc123', init.session_id, {
    timestamp: Date.now(),
  });

  // 3. Solve and submit
  const solution = await solvePow(ch.challenge.token, ch.challenge.difficulty);
  const result = await api.solve('mpt_site_abc123', init.session_id, solution);
  console.log(result.token);
}

Widget instance methods

Method	Returns	Description
reset()	void	Reset the widget to idle state
getSitekey()	string	Get the current site key
getLanguage()	string	Get the resolved language code
getTheme()	string	Get the resolved theme (light, dark, auto)

const widget = document.querySelector('maptcha-widget');
widget.reset(); // Return to unchecked state