Hanko Frontend Integration 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 demonstrates how to integrate Hanko authentication into your frontend application. You’ll implement user authentication, profile management, route protection, and logout functionality with Hanko Elements web components.Key Technologies:
- Modern frontend framework with TypeScript support
- Build tools and development environment
- Client-side routing and navigation
- Hanko Elements web components
- Hanko SDK for authentication logic
- Node.js installed on your system
- Basic knowledge of your chosen frontend framework
- A Hanko Cloud account (sign up at cloud.hanko.io)
- Set up your frontend application with the appropriate build tools
- Install and configure Hanko Elements
- Create a Hanko project in the cloud console
- Implement authentication components (HankoAuth, HankoProfile)
- Set up routing and navigation
- Add logout functionality
- Implement protected routes with session validation
- Retrieve and display user data
- Customize component styling and behavior
Create a React application
Set up your React frontend using Vite as the build tool. Run the following command to create a new Vite React application:Install @teamhanko/hanko-elements
Install hanko-elements
to access the pre-built hanko-auth
and hanko-profile
components.
Also install react-router-dom
for navigation between pages and routes.
Set up your Hanko project
Go to the Hanko Console and create a project for this application.During creation make sure to input the URL you will be developing on as the
APP URL
.
(Most likely http://localhost:5173/)Add the Hanko API URL
Retrieve the API URL from the Hanko Console and place it in your .env file..env
If you are self-hosting you need to provide the URL of your running Hanko
backend.
Create Hanko components
Create a folder calledcomponents
and create two files in it, HankoAuth.tsx
and HankoProfile.tsx
.
Typescript
To get these elements to work with typescript, currently we must add the types to the project. To do do this, create a file calledcustom.d.ts
and place it in your apps root / src folder.
src/custom.d.ts
Hanko Auth
Now lets setup theHankoAuth.tsx
file to create a functioning login page.
Here we subscribe to the onSessionCreated
event, this triggers when a user successfully logs in. You can use these event to perform any desired action (e.g. redirect to your dashboard).
For more information please refer to the Auth component page.
components/HankoAuth.tsx
pages/loginPage.tsx
Hanko Profile
After setting up the HankoAuth let’s set up theHankoProfile.jsx
file to create an interface where users can
manage their Email Addresses
and credentials.
For more information please refer to the Profile component page.
components/HankoProfile.tsx
HankoProfile
component, simply import it into any page.
pages/dashboardPage.tsx
Setup your routes
After you created theLoginPage.tsx
and DashboardPage.tsx
you are able to import them into your react App.tsx
.
We will use react-router-dom
to setup the routes of your app.
App.tsx
/
to see the <HankoAuth>
, and to /dashboard
to see the <HankoProfile>
.
They should look something like this👇


Implement logout functionality
You can use@teamhanko/hanko-elements
to easily logout users. Here we will make a logout button.
Create LogoutButton.tsx
and insert the code below.
components/LogoutButton.tsx
Customize component styles
You can customize the appearance ofhanko-auth
and hanko-profile
components using CSS variables and parts. Refer to our customization guide.
Securing routes
To secure our routes we should validate the session token at the backend. Please refer to our backend guides. Lets set up a Private route to do this for us. Create a new React component atcomponents/PrivateRoute.tsx
.
If the backend couldn’t validate our token we get navigated back to /
.
Otherwise if the validation was successfull it will return the children inside the private route.
components/PrivateRoute.tsx
PrivateRoute.tsx
to your App.tsx
file.To use the private route wrap your
Dashboard
in the Private Route;
App.tsx
/dashboard
, you should get redirected back.
Getting user data
Client side
Lets use the Hanko SDK to get user data. Lets update thedashboard
page to log some of the information from the user.
pages/dashboardPage.tsx
Try it yourself
React example (Vite)
It uses Express.js for the backend, full source code available on our GitHub.