​
Web Components

<hanko-login/>

A web component that handles user login.

<hanko-register/>

A web component that handles user registration.

<hanko-auth/>

A web component that handles user login and registration.

<hanko-profile/>

Allows Users to manage their login methods.

​
Features

Web Components

Pre-built components to give you fully-functional authentication and user management in minutes.

Customization

Fully customize web components to match your style preferences.

Internationalization

Supports multiple languages and provides translation options for a global user base.

Integration Flexibility

Offers versatile choices for integration, including CDN or npm.

​
Installation

Integrate Hanko Elements into your project using your preferred package manager or CDN implementation:

npm install @teamhanko/hanko-elements

​
Usage

To implement Hanko, import and invoke the register() function from the hanko-elements module. This enables the use of web components throughout your application.

For proper functionality, implement the <hanko-auth /> element to enable user authentication, and configure the “onSessionCreated” event handler to specify post-authentication behavior, such as page redirection. Detailed implementation steps are provided in subsequent sections.

​
Importing the module

If installed through a package manager, you can import the register() function from the @teamhanko/hanko-elements package in your TypeScript or JavaScript file

import { register } from "@teamhanko/hanko-elements";

For CDN implementation, include a script tag with the import statement referencing the CDN-hosted hanko-elements package URL.

<script type="module">
  import { register } from "https://cdn.jsdelivr.net/npm/@teamhanko/hanko-elements/dist/elements.js";
</script>

​
Registering the Web Components

After importing the register() function, call it with your Hanko API URL as an argument to register the Hanko elements with the browser’s CustomElementRegistry.

const { hanko } = await register("YOUR_HANKO_API_URL");

Configuration options can be provided to customize the behavior and appearance of the components.

const defaultOptions = {
  shadow: true, // Set to false if you do not want the web component to be attached to the shadow DOM.
  injectStyles: true, // Set to false if you do not want to inject any default styles.
  enablePasskeys: true, // Set to false if you do not want to display passkey-related content.
  hidePasskeyButtonOnLogin: false, // Hides the button to sign in with a passkey on the login page.
  translations: null, // Additional translations can be added here. English is used when the option is not
  // present or set to `null`, whereas setting an empty object `{}` prevents the elements
  // from displaying any translations.
  translationsLocation: "/i18n", // The URL or path where the translation files are located.
  fallbackLanguage: "en", // The fallback language to be used if a translation is not available.
  storageKey: "hanko", // The name of the cookie the session token is stored in and the prefix / name of local storage keys
  cookieDomain: undefined, // The domain where the cookie set from the SDK is available. When undefined,
  // defaults to the domain of the page where the cookie was created.
  cookieSameSite: "lax", // Specify whether/when cookies are sent with cross-site requests.
  sessionCheckInterval: 30000, // Interval for session validity checks in milliseconds. Must be greater than 3000 (3s).
  sessionTokenLocation: "cookie", // Specify where the session token should be stored. Either `cookie` or `sessionStorage`.
};

const { hanko } = await register("YOUR_HANKO_API_URL", defaultOptions);
  • If cookieSameSite is set to none then your application must be served through HTTPS. The Secure attribute is automatically set to true if your application uses HTTPS.
  • If you want cookies to be available on subdomains, you must set your cookieDomain to your domain prefixed with a .. For example, if your frontend application is running on myapp.com and you want cookies to be available on api.myapp.com, then the cookieDomain value should be .myapp.com.

​
Embedding the Web Components

After implementing the above steps, you can incorporate the web components into your application’s markup. Here’s a basic implementation example:

<body>
<hanko-auth id="authComponent"></hanko-auth>
</body>

<script type="module">
  import { register } from "https://cdn.jsdelivr.net/npm/@teamhanko/hanko-elements/dist/elements.js";

  await register("YOUR_HANKO_API_URL");

  const authComponent = document.getElementById("authComponent");
  authComponent.addEventListener("onSessionCreated", () => {
    // redirect to a different page
  });
</script>