> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hanko.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hanko Elements guide

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

<div class="hidden">
  **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
</div>

## Components overview

<CardGroup cols={2}>
  <Card title="<hanko-login/>" href="/guides/hanko-elements/login-component">
    A Web Component that handles user login.
  </Card>

  <Card title="<hanko-registration/>" href="/guides/hanko-elements/register-component">
    A Web Component that handles user registration.
  </Card>

  <Card title="<hanko-auth/>" href="/guides/hanko-elements/auth-component">
    User login and registration flows combined into a single Web Component.
  </Card>

  <Card title="<hanko-profile/>" href="/guides/hanko-elements/profile-component">
    A Web Component that allows users to manage their account.
  </Card>
</CardGroup>

## Installation

Add Hanko Elements to your project using your preferred package manager or CDN:

<CodeGroup>
  ```bash npm theme={null}
  npm install @teamhanko/hanko-elements
  ```

  ```bash pnpm theme={null}
  pnpm add @teamhanko/hanko-elements
  ```

  ```bash yarn theme={null}
  yarn add @teamhanko/hanko-elements
  ```
</CodeGroup>

## Usage

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

<Info>
  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.
</Info>

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

```js theme={null}
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:

```html theme={null}
<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`:

```js theme={null}
const { hanko } = await register("YOUR_HANKO_API_URL");
```

You can provide configuration options to customize the behavior and appearance of the components:

```js theme={null}
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:

```html theme={null}
<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

<CardGroup cols={2}>
  <Card
    title="Customization"
    icon={
  <svg
    xmlns="http://www.w3.org/2000/svg"
    className="icon icon-tabler icon-tabler-brush"
    width="24"
    height="24"
    viewBox="0 0 24 24"
    strokeWidth="2"
    stroke="currentColor"
    fill="none"
    strokeLinecap="round"
    strokeLinejoin="round"
  >
    <path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
    <path d="M3 21v-4a4 4 0 1 1 4 4h-4"></path>
    <path d="M21 3a16 16 0 0 0 -12.8 10.2"></path>
    <path d="M21 3a16 16 0 0 1 -10.2 12.8"></path>
    <path d="M10.6 9a9 9 0 0 1 4.4 4.4"></path>
  </svg>
}
    href="/guides/hanko-elements/customize-appearance"
  >
    Style Hanko Elements Web Components to match your app's design.
  </Card>

  <Card
    title="Internationalization"
    icon={
  <svg
    xmlns="http://www.w3.org/2000/svg"
    className="icon icon-tabler icon-tabler-language"
    width="24"
    height="24"
    viewBox="0 0 24 24"
    strokeWidth="2"
    stroke="currentColor"
    fill="none"
    strokeLinecap="round"
    strokeLinejoin="round"
  >
    <path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
    <path d="M4 5h7"></path>
    <path d="M9 3v2c0 4.418 -2.239 8 -5 8"></path>
    <path d="M5 9c0 2.144 2.952 3.908 6.7 4"></path>
    <path d="M12 20l4 -9l4 9"></path>
    <path d="M19.1 18h-6.2"></path>
  </svg>
}
    href="/guides/hanko-elements/translations"
  >
    Support for multiple languages and translation options for a global user base.
  </Card>
</CardGroup>