# Captcha

**`sonic-captcha`** embeds an [ALTCHA](https://altcha.org) proof-of-work widget and makes the nearest form wait for it. Place it inside a form scope and put **`sonic-submit`** in its default slot: the widget renders above the slot content, and the submit sends only once a token is available.

## Basic example

The widget loads only on **HTTPS**. On plain HTTP the component renders nothing and the form is not blocked.

<sonic-code>
  <template>
    <sonic-scope
      serviceURL="/docs-mock-api"
      formDataProvider="captcha-docs-form"
      submitResultDataProvider="captcha-docs-result"
    >
      <sonic-captcha>
        <sonic-input class="mb-3 block" name="email" type="email" label="Email" value="demo@example.com"></sonic-input>
        <sonic-submit endPoint="api/register" onClick>
          <sonic-button type="primary">Join the crew</sonic-button>
        </sonic-submit>
      </sonic-captcha>
    </sonic-scope>
  </template>
</sonic-code>

## Form integration

The component writes to the publisher named by the closest `headersDataProvider`, or else `formDataProvider`, on itself or an ancestor. On connect it sets `needsCaptchaValidation` to `true`. When **`sonic-submit`** sees that flag, it requests a token, the captcha copies the solved ALTCHA payload into `captchaToken` and its key into `captchaKey`, and the request is sent. `needsCaptchaValidation` is stripped from the payload. On disconnect both fields are reset.

<sonic-code language="typescript">
  <template>
{
  email: "demo@example.com",
  captchaKey: "…",
  captchaToken: "…"
}
  </template>
</sonic-code>

## Key and challenge endpoint

With no `key`, the component generates an encrypted key on connect. The widget fetches its challenge from the `chalengeUrl` property (a JavaScript property, not an attribute) with `key` and `maxNumber` (default `50000`) as query parameters. Point it at your own ALTCHA server and verify `captchaToken` there.

Labels follow the page language: French when `<html lang>` starts with `fr`, English otherwise.

## API reference

| Attribute | Values | Description |
|----------|---------|-------------|
| `key` | string (default generated) | Key sent to the challenge endpoint and copied to `captchaKey` |

| Slot | Description |
|------|-------------|
| *(default)* | Form fields and actions, rendered below the widget |

No events.