Next.js
In this guide you will learn how to use the hanko-elements web components to add authentication and a user profile to your Next.js application.
Install dependencies
Install the @teamhanko/hanko-elements
package:
- npm
- Yarn
npm install @teamhanko/hanko-elements
yarn add @teamhanko/hanko-elements
Add <hanko-auth>
component
To provide a login interface in your app, use the <hanko-auth>
web component. To do so, first import the register
function from @teamhanko/hanko-elements
in your Next.js component. Then call register
to register the <hanko-auth>
element with the browser's CustomElementRegistry
and use the <hanko-auth>
element in your JSX.
When adding the <hanko-auth>
element to your JSX you must provide the URL of the Hanko API via the api
attribute. If you are using Hanko Cloud, you can find the API URL on your project dashboard.
If you are self-hosting you need to provide the URL of your running Hanko backend.
import { register } from "@teamhanko/hanko-elements";
const hankoApi = "<YOUR_API_URL>";
export default function HankoAuth() {
useEffect(() => {
// register the component
// see: https://github.com/teamhanko/hanko/blob/main/frontend/elements/README.md#script
register({ shadow: true })
.catch((error) => {
// handle error
});
}, []);
return (
<hanko-auth api={hankoApi} />
);
}
The call to register
attempts to register the <hanko-auth>
element with the
browser's CustomElementRegistry
through a
call to window.customElements.define()
.
Next.js pre-renders pages on the server but the browser window
is not available during pre-rendering, so the custom
element registration would fail.
A solution for this is to use Next's dynamic import feature to dynamically load the component on the client-side and disable server rendering for it:
import dynamic from "next/dynamic";
export default function Home() {
const HankoAuth = dynamic(
// replace with path to your component using the <hanko-auth> element
() => import('../components/HankoAuth'),
{ ssr: false },
)
return (
<Suspense fallback={"Loading ..."}>
<HankoAuth/>
</Suspense>
)
}
Define login callbacks
The <hanko-auth>
element dispatches a custom hankoAuthSuccess
event on successful login. React to this
event in order to, for example, redirect your users to protected pages in your application,
e.g. a user profile page.
To do so, apply an event listener with an appropriate redirect callback:
import React, { useEffect, useCallback } from "react";
import { useRouter } from "next/router";
import { register } from "@teamhanko/hanko-elements";
const hankoApi = "<YOUR_API_URL>";
export default function HankoAuth() {
const router = useRouter();
const redirectAfterLogin = useCallback(() => {
// successfully logged in, redirect to a page in your application
router.replace("...");
}, [router]);
useEffect(() => {
document.addEventListener("hankoAuthSuccess", redirectAfterLogin);
return () =>
document.removeEventListener("hankoAuthSuccess", redirectAfterLogin);
}, [redirectAfterLogin]);
useEffect(() => {
// register the component
// see: https://github.com/teamhanko/hanko/blob/main/frontend/elements/README.md#script
register({ shadow: true })
.catch((error) => {
// handle error
});
}, []);
return (
<hanko-auth api={hankoApi} />
);
}
Add <hanko-profile>
component
To provide a page where users can manage their email addresses, password and passkeys, use the <hanko-profile>
web
component. Just as with the <hanko-auth>
component, import the register
function from @teamhanko/hanko-elements
in
your Next.js component. Then call register
to register the <hanko-profile>
element with the browser's
CustomElementRegistry
and use
the element in your JSX.
When adding the <hanko-profile>
element to your template you must provide the URL of the Hanko API via the api
attribute. If you are using Hanko Cloud, you can find the API URL on your project dashboard.
If you are self-hosting you need to provide the URL of your running Hanko backend.
import { useEffect } from "react";
import { register } from "@teamhanko/hanko-elements";
const hankoApi = "<YOUR_API_URL>";
export default function HankoProfile() {
useEffect(() => {
// register the component
// see: https://github.com/teamhanko/hanko/blob/main/frontend/elements/README.md#script
register({ shadow: true })
.catch((error) => {
// handle error
});
}, []);
return (
<hanko-profile api={hankoApi} />
);
};
Customize component styles
The styles of the hanko-auth
and hanko-profile
elements can be customized using CSS variables and parts. See our
guide on customization here.
Authenticate backend requests
If you want to authenticate requests in your own backend, please view our backend guide.