Hanko Elements guide

Hanko Elements are Web Components that can be used to quickly add registration, login, and profile settings functionality to web apps.

Hanko Elements introduction guide:

About Hanko:

Hanko is a modern open source authentication solution and the fastest way you integrate passkeys, 2FA, SSO, and more—with full control over your data. Move between self-hosted and Hanko Cloud anytime. No lock-in. Just Auth how it should be: secure, user friendly, and fully yours.

What This Guide Covers: This guide introduces Hanko Elements, a collection of pre-built web components that provide modern authentication functionality. You’ll learn about the available components, their features, and how to get started with integrating the components in your applications.

Key Technologies:

• Hanko Elements
• Web Components
• JavaScript/TypeScript
• Passkeys
• OAuth SSO
• 2FA authentication
• CSS customization
• Internationalization
• Modern web frameworks integration

Prerequisites:

• Basic knowledge of frontend development, HTML/JavaScript, and web components
• Familiarity with your chosen frontend framework and an active Hanko account

Tasks You’ll Complete:

• Understand the available Hanko web components and their use cases
• Install and configure Hanko Elements in your project
• Register web components and configure authentication options
• Implement basic authentication flows using pre-built components
• Set up event handling for authentication state management
• Explore customization and internationalization options

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

npm install @teamhanko/hanko-elements

pnpm add @teamhanko/hanko-elements

yarn add @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);

Cookie options

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