​
Features

Web Components

Pre-built components to give you a fully-functional auth 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

To use the Hanko Elements module in your project, you can install it via npm, pnpm, or yarn. Alternatively, you can also import the module directly via a CDN.

​
Usage

To integrate Hanko, you need to import and call the register() function from the hanko-elements module. Once this is done, you can use the web components in your code.

For a functioning page, at least the <hanko-auth> element should be placed, so the users can sign-in, and also, a handler for the “onSessionCreated” event should be added, to customize the behaviour after the authentication flow has been completed (e.g. redirect to another page). These steps will be described in the below sections.

​
Importing the module

If you’re using a module bundler like webpack or Parcel, you can import the register() function from the @teamhanko/hanko-elements package in your TypeScript or JavaScript file

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

If you prefer using a CDN, you can include a script tag with the import statement pointing to the CDN URL where the hanko-elements package is hosted.

<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");

You can also pass certain default options.

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.
};

const { hanko } = await register("YOUR_HANKO_API_URL", defaultOptions);
  • If you set cookieSameSite to none then your application must use 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

If you have followed the steps mentioned above, you should now be able to place the web components anywhere in the body of your code. A minimal example would look like this

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

<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>

To know more about individual components, refer to these.

Auth Component

Handles user login and user registration.

Profile Component

Allows to manage emails, passwords and passkeys.

Events Component

Binds event handler to certain events, without displaying UI elements.

Was this page helpful?

Mobile App BiometricsAuth Component