Skip to main content

​
Components overview

<hanko-login/>

A Web Component that handles user login.

<hanko-registration/>

A Web Component that handles user registration.

<hanko-auth/>

User login and registration flows combined into a single Web Component.

<hanko-profile/>

A Web Component that allows users to manage their account.

​
Installation

Add Hanko Elements to your project using your preferred package manager or CDN: 
npm install @teamhanko/hanko-elements

​
Usage

To use Hanko, import and call the register() function from the hanko-elements module. This enables the web components throughout your application.
For proper functionality, add the <hanko-auth /> element to enable user authentication, and configure the “onSessionCreated” event handler to define post-authentication behavior, such as page redirection. Detailed implementation steps are provided in the following sections.

​
Importing the module

If you installed via 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 usage, 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 to register the Hanko elements with the browser’s CustomElementRegistry: 
const { hanko } = await register("YOUR_HANKO_API_URL");
You can provide configuration options 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 completing the above steps, you can add the web components to your application’s markup. Here’s a basic 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>

​
Advanced guides

Customization

Style Hanko Elements Web Components to match your app’s design.

Internationalization

Support for multiple languages and translation options for a global user base.