Browser widget

The HumanPass widget is a framework-independent Web Component. Load it from the versioned Valgix URL and provide your public sitekey.

Basic installation

<script
  src="https://humanpass.valgix.com/widget/0.1.0/humanpass.min.js"
  defer
></script>

<humanpass-widget
  data-humanpass-sitekey="hp_site_live_REPLACE_ME"
  data-humanpass-action="signup"
  required
></humanpass-widget>

Use an immutable version such as 0.1.0. Do not construct a mutable latest URL.

Required values

data-humanpass-sitekey is the only required configuration value. It is public and safe to include in HTML.

data-humanpass-action is optional. It defaults to default and must match the site’s Allowed actions policy.

Danger

Never add hp_secret_... to a widget attribute or browser JavaScript. Secret keys belong only on your backend.

Mode selection

Choose Checkbox, Non-interactive, or Invisible in the Valgix dashboard. The widget retrieves that setting from HumanPass after validating the browser origin.

There is no supported data-humanpass-mode attribute. This prevents browser markup from weakening the site’s configured presentation.

Responsive sizing

Visible widgets use the standard 300 × 65 px layout by default and shrink safely inside narrower containers. To fill the available width of a form or card, use:

<humanpass-widget
  data-humanpass-sitekey="hp_site_live_REPLACE_ME"
  data-humanpass-size="flexible"
></humanpass-widget>

HumanPass keeps its Valgix branding and the built-in Privacy and Help links in both layouts.

Dark theme

HumanPass uses the light theme by default. Add the theme attribute when the widget is placed on a dark surface:

<humanpass-widget
  data-humanpass-sitekey="hp_site_live_REPLACE_ME"
  data-humanpass-theme="dark"
></humanpass-widget>

Form value

The component creates a hidden input named humanpass-token. Customize the field name if needed:

<humanpass-widget
  data-humanpass-sitekey="hp_site_live_REPLACE_ME"
  data-humanpass-hidden-field-name="verification-response"
  required
></humanpass-widget>

Read the same field on your backend and verify it before processing the form.

Events

Use DOM events instead of inline handlers:

const widget = document.querySelector("humanpass-widget");

widget.addEventListener("solve", (event) => {
  console.log("HumanPass completed", event.detail.token);
});

widget.addEventListener("error", (event) => {
  showRetryMessage(event.detail.message);
});

widget.addEventListener("expire", () => {
  showExpiredMessage();
});

Do not log response tokens in production. The example only illustrates the event payload.

Localization

Set data-humanpass-lang for built-in localization or override individual labels with data-humanpass-i18n-* attributes. See the Widget API reference for the complete attribute list.

Content Security Policy

Allow the versioned widget script and HumanPass API connection:

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://humanpass.valgix.com;
  connect-src 'self' https://humanpass.valgix.com;
  worker-src 'self' blob:;

Merge these directives into your existing policy rather than replacing it.

Multiple widgets

You can place multiple widgets on one page. Give each widget the action for the operation it protects, and verify the matching expected action on your backend.