Szymdows CAPTCHA

Step 1

Install the script

Copy this one line and paste it into the <head> section of your HTML page. That's the entire installation. No npm. No build tools. No configuration.

Open your HTML file

Find the <head> section near the top of your HTML file. It's the part between <head> and </head>.

<html>
<head>
  <!-- 👇 paste the script tag here -->

</head>
<body>
  ...
</body>
</html>

Paste the script tag

Copy the line below and paste it inside your <head>. Do not add defer or async - just paste it exactly as shown.

<script src="https://cdn.szymdows.com/szymdows-captcha.js"></script>

That’s the whole installation. The script loads automatically and makes SzymdowsCaptcha available on your page.

Step 2

Place the widget

Add an empty <div> tag wherever you want the CAPTCHA to appear on your page - usually just above your submit button.

Add the div to your form

Put this empty div wherever you want the CAPTCHA box to appear. The id can be anything - just remember it.

<form>
  <input type="text" placeholder="Your name" />
  <input type="email" placeholder="Your email" />

  <!-- 👇 CAPTCHA goes here -->
  <div id="my-captcha"></div>

  <button type="button" id="submit-btn">Submit</button>
</form>

The CAPTCHA widget will fill the div automatically and fit neatly into normal layouts.

Step 3

Show the CAPTCHA

Add a small <script> block at the bottom of your page and call SzymdowsCaptcha.render().

Add a script block after your form

Paste this just before your closing </body> tag.

<script>
  SzymdowsCaptcha.render('my-captcha', {

    onSuccess: function(token) {
      document.getElementById('submit-btn').disabled = false;
    },

    onFail: function() {
      document.getElementById('submit-btn').disabled = true;
    },

  });
</script>

That’s it for the basic setup. The CAPTCHA appears and your onSuccess function runs when the user passes.

Step 4

Handle the result

When the user passes, you get a token. Send this token to your server with the rest of the form data.

Send the token when the form is submitted

document.getElementById('submit-btn')
  .addEventListener('click', function() {

    var token = SzymdowsCaptcha.getToken('my-captcha');

    fetch('/submit', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        name: document.getElementById('name').value,
        email: document.getElementById('email').value,
        captchaToken: token,
      }),
    });

  });

Tokens expire after 60 seconds and can only be used once.

Recipe A

Complete contact form

A full working example you can copy and use as a starting point.

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.szymdows.com/szymdows-captcha.js"></script>
</head>
<body>

  <input type="text"  id="name"  placeholder="Your name"  />
  <input type="email" id="email" placeholder="Your email" />

  <div id="my-captcha"></div>

  <button id="submit-btn" disabled>Send message</button>

  <script>
    SzymdowsCaptcha.render('my-captcha', {
      onSuccess: function(token) {
        document.getElementById('submit-btn').disabled = false;
      },
      onFail: function() {
        document.getElementById('submit-btn').disabled = true;
      },
    });

    document.getElementById('submit-btn')
      .addEventListener('click', function() {
        fetch('/submit', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            name: document.getElementById('name').value,
            email: document.getElementById('email').value,
            captchaToken: SzymdowsCaptcha.getToken('my-captcha'),
          }),
        });
      });
  </script>

</body>
</html>

Recipe B

Show only when the user clicks submit

Hide the CAPTCHA initially and only show it when the user clicks submit.

<div id="my-captcha" style="display:none"></div>
<button id="submit-btn">Submit</button>

<script>
  document.getElementById('submit-btn')
    .addEventListener('click', function() {

      if (SzymdowsCaptcha.isVerified('my-captcha')) {
        submitMyForm(SzymdowsCaptcha.getToken('my-captcha'));
        return;
      }

      document.getElementById('my-captcha').style.display = 'block';

      SzymdowsCaptcha.show('my-captcha', {
        onSuccess: function(token) {
          submitMyForm(token);
        },
      });
    });

  function submitMyForm(token) {
    fetch('/submit', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ captchaToken: token }),
    });
  }
</script>

Recipe C

Verify the token on your server

Always verify the token server-side before trusting it.

Always verify server-side. Never trust the token just because it arrived.

app.post('/submit', async function(req, res) {

  var token = req.body.captchaToken;

  var check = await fetch(
    'https://captcha.szymdows.com/__szc/verify-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ token: token }),
    }
  );

  var result = await check.json();

  if (!result.valid) {
    return res.status(403).json({ error: 'CAPTCHA failed' });
  }

  saveToDatabase(req.body);
  res.json({ success: true });

});

Reference

All options

These are all the settings you can pass to render() or show().

Option	Default	What it does
onSuccess	null	Called when the user passes. Receives the token string.
onFail	null	Called when the check fails. The widget retries automatically.
onExpire	null	Called when the CAPTCHA auto-resets after 5 minutes.
autoReset	true	If true, the CAPTCHA automatically resets after 5 minutes.
theme	'auto'	Use 'light', 'dark', or 'auto'.

Reference

All methods

These are the main things you can do with SzymdowsCaptcha.