Widget Reference

The Squeaker widget is a web component (<squeaker-widget>) that works in any HTML page or JavaScript framework.

Basic embed

<squeaker-widget
  data-sitekey="sq_live_your_key"
  data-api="https://api.squeaker.cc/v1"
  data-theme="light"
  data-mode="interactive"
></squeaker-widget>
<script src="https://cdn.squeaker.cc/squeaker.js" async defer></script>

Attributes

AttributeRequiredDescription
data-sitekeyYesPublic site key from the dashboard (starts with sq_live_).
data-apiNoAPI base URL. Default: https://api.squeaker.cc/v1.
data-themeNoVisual theme. Default: light.
data-borderNoShow widget frame. Default: true. Set false for borderless.
data-modeNoDisplay and trigger mode. Default: interactive.
data-formNoCSS selector for the form to attach to (recommended for auto mode).
data-callbackNoName of a global JavaScript function called on successful verification.
data-langNoLanguage code or auto. Omit for auto-detection.

Themes

ThemeBest for
lightDefault. Clean white card, mint accent.
darkNear-black card for dark pages and night mode — blends with #0a0a0a / #111 backgrounds.
cheeseFlat golden cheese — readable on light and dark page backgrounds.
terminalRetro CRT terminal — phosphor green on near-black, monospace, subtle scanlines and glow.
sunsetWarm orange gradient background.
monoMonospace font, sharp corners - developer tools aesthetic.

Modes

interactive (default)

User clicks the widget to verify. Best for high-value actions where you want visible confirmation (signup, payment).

invisible

Widget is hidden. Verification runs automatically on page load. Best for low-friction pages where you still want protection before any interaction.

<squeaker-widget
  data-sitekey="sq_live_xxx"
  data-mode="invisible"
></squeaker-widget>

auto

Widget shows (unless combined with invisible styling). On form submit, solves the challenge and injects a hidden squeaker-token input. Blocks submit until verified.

<form id="signup" data-squeaker-auto>
  <squeaker-widget
    data-sitekey="sq_live_xxx"
    data-mode="auto"
    data-form="#signup"
  ></squeaker-widget>
  <button type="submit">Sign up</button>
</form>

Languages (30)

Supported codes: en, zh, es, ar, pt, id, fr, ja, ru, de, ko, tr, it, nl, pl, vi, th, uk, cs, ro, hu, el, sv, hi, bn, ms, fil, da, fi, no.

Auto-detection

By default the widget reads navigator.languages, region code, and timezone to pick the best match. Unsupported locales fall back to English.

JavaScript API

Methods

const widget = document.querySelector('squeaker-widget');

await widget.execute();   // run verification, returns token string
widget.getToken();        // current token or null
widget.reset();           // clear token and reset UI

Events

EventDetail
squeaker-success{ token: string }
squeaker-error{ message: string }
squeaker-resetWidget was reset
squeaker-state{ state: 'idle' | 'solving' | 'solved' | 'error' } — UI state changes
 
widget.addEventListener('squeaker-success', (e) => {
  console.log('Token:', e.detail.token);
  // submit form or call your API
});

Callback attribute

<script>
  function onVerified(token) {
    console.log(token);
  }
</script>

<squeaker-widget
  data-sitekey="sq_live_xxx"
  data-callback="onVerified"
></squeaker-widget>

Framework examples

Plain HTML / WordPress

Paste the script tag before </body> and add the widget inside your form template.

React / Next.js

Use the <squeaker-widget> web component in your JSX and load squeaker.js once (e.g. in useEffect). See Server Verify for a full example — no npm package required.

Vue / Svelte / Angular

Use the web component directly in your template. Load squeaker.js once in your app shell or layout.

Bundle size

~32 KB single IIFE file. No external dependencies. Proof-of-work runs in a Web Worker so the main thread stays responsive.

Troubleshooting