Hanko Elements
Hanko Elements provide web components that add a modern login and registration experience for your users.
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 “onAuthFlowCompleted” 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);
Cookie options
- If you set
cookieSameSite
tonone
then your application must use HTTPS. TheSecure
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 onmyapp.com
and you want cookies to be available onapi.myapp.com
, then thecookieDomain
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("onAuthFlowCompleted", () => {
// redirect to a different page
});
</script>
To know more about individual components, refer to these.
Was this page helpful?