Widget API

Script

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

The script registers <humanpass-widget> and exposes window.HumanPass.

Element attributes

Attribute	Type	Default	Description
`data-humanpass-sitekey`	string	—	Public sitekey. Required.
`data-humanpass-action`	string	`default`	Protected operation. Must match the site’s policy.
`data-humanpass-size`	`normal` or `flexible`	`normal`	Uses the standard 300 × 65 px layout or fills the available container width.
`data-humanpass-theme`	`light` or `dark`	`light`	Selects the widget color theme.
`data-humanpass-hidden-field-name`	string	`humanpass-token`	Name of the generated hidden form field.
`data-humanpass-lang`	string	browser language	Widget language.
`data-humanpass-disable-haptics`	boolean attribute	false	Disables supported haptic feedback.
`data-humanpass-troubleshooting-url`	URL	—	Customer help URL shown for recoverable failures.
`required`	boolean attribute	false	Makes an unsolved visible component invalid in forms.

There is no data-humanpass-mode; mode is controlled by the dashboard.

Visible widgets always include Valgix branding plus Privacy and Help links. The Valgix logo opens the HumanPass product page, Privacy opens the HumanPass Privacy Addendum, and Help opens the Valgix contact page. These destinations open in a new tab.

Sizing

The default normal layout is 300 × 65 px and safely shrinks if its container is narrower. Use the flexible layout when the widget should fill a form or card:

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

Flexible sizing changes presentation only. It does not change the site’s verification mode or security policy.

Color theme

The widget uses the light theme by default. Use the dark theme on dark surfaces:

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

The theme changes presentation only. It does not change verification behavior.

Localization attributes

Override individual strings with:

data-humanpass-i18n-initial-state
data-humanpass-i18n-verifying-label
data-humanpass-i18n-solved-label
data-humanpass-i18n-error-label
data-humanpass-i18n-verify-aria-label
data-humanpass-i18n-verifying-aria-label
data-humanpass-i18n-verified-aria-label
data-humanpass-i18n-error-aria-label
data-humanpass-i18n-required-label

Keep accessible labels meaningful when overriding visible copy.

Properties and methods

interface HumanPassWidget extends HTMLElement {
  readonly token: string | null;
  readonly tokenValue: string | null;
  solve(): Promise<{ success: boolean; token: string }>;
  reset(reason?: string): void;
}

Use solve() for programmatic and Invisible flows. Call reset() before requesting a new response after an application-level retry.

Events

Event	`detail`	When it fires
`progress`	`{ progress: number }`	Progress changes from 0 to 100.
`solve`	`{ token: string }`	A response token is ready.
`reset`	`{ reason: string }`	State and response are cleared.
`expire`	`{ expiredAt: string }`	The current response expires.
`error`	`{ isHumanPass: true, code: string, message: string }`	Verification cannot complete.

widget.addEventListener("solve", ({ detail }) => submit(detail.token));
widget.addEventListener("error", ({ detail }) => showError(detail.message));

Browser controller

const humanpass = new window.HumanPass({
  sitekey: "hp_site_live_REPLACE_ME",
  action: "signup",
});

const { token } = await humanpass.solve();
humanpass.reset();

The controller supports the same event names as the custom element.

Floating placement helper

Floating placement is an optional layout helper for visible modes, not a mode. Load the matching immutable helper version after the main widget script:

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

<button data-humanpass-floating="#humanpass">Continue</button>
<humanpass-widget
  id="humanpass"
  data-humanpass-sitekey="hp_site_live_REPLACE_ME"
></humanpass-widget>

Optional trigger attributes are data-humanpass-floating-position="top|bottom" and data-humanpass-floating-offset="8".