Web Component:

Lit-based web component for HOTOSM SSO authentication with Hanko and OpenStreetMap integration.

Installation

``bash


npm

npm install @hotosm/hanko-auth

pnpm

pnpm add @hotosm/hanko-auth

yarn

yarn add @hotosm/hanko-auth
`

Quick Start

$3

`js
import "@hotosm/hanko-auth";
`

$3

`html
hanko-url="https://login.hotosm.org"
show-profile="true"
>
`

$3

`tsx
import { useEffect, useRef } from "react";
import "@hotosm/hanko-auth";

export function AuthButton({ hankoUrl, onLogin }) {
const ref = useRef(null);

useEffect(() => {
const el = ref.current;
const handler = (e: CustomEvent) => onLogin(e.detail.user);
el?.addEventListener("hanko-login", handler);
return () => el?.removeEventListener("hanko-login", handler);
}, [onLogin]);

return ;
}
`

Attributes

$3

| Attribute | Type | Default | Description |
| ----------- | ------ | ------------------------ | ------------------------------------------ |
| hanko-url | string | window.location.origin | Login service URL for Hanko authentication |
| base-path | string | "" | Base URL for OSM OAuth endpoints |
| auth-path | string | /api/auth/osm | OSM auth endpoints path |

$3

| Attribute | Type | Default | Description |
| ---------------- | ------- | -------------- | -------------------------- |
| osm-required | boolean | false | Require OSM connection |
| osm-scopes | string | "read_prefs" | Space-separated OSM scopes |
| auto-connect | boolean | false | Auto-redirect to OSM OAuth |
| verify-session | boolean | false | Verify session on return |

$3

| Attribute | Type | Default | Description |
| ---------------- | ------- | ---------- | ----------------------------------------------------------------- |
| show-profile | boolean | false | Show full profile (vs header button) |
| display-name | string | "" | Override display name |
| lang | string | "en" | Language/locale code (e.g., "en", "es", "fr"). Enlish as fallback |
| button-variant | string | "filled" | Button style: filled, outline, or plain |
| button-color | string | "primary"| Button color: primary, neutral, or danger |

$3

| Attribute | Type | Default | Description |
| ----------------------- | ------ | ------- | -------------------------- |
| redirect-after-login | string | "" | URL after successful login |
| redirect-after-logout | string | "" | URL after logout |

$3

| Attribute | Type | Default | Description |
| ------------------- | ------ | ------- | ----------------------------- |
| mapping-check-url | string | "" | URL to check user mapping |
| app-id | string | "" | App identifier for onboarding |

Events

The component dispatches the following custom events:

| Event | Detail | When |
| --------------- | ---------------------- | --------------------------- |
| hanko-login | { user: HankoUser } | User logged in |
| osm-connected | { osmData: OSMData } | OSM account linked |
| osm-skipped | {} | User skipped OSM connection |
| auth-complete | {} | Auth flow complete |
| logout | {} | User logged out |

$3

`js
const auth = document.querySelector("hotosm-auth");

auth.addEventListener("hanko-login", (e) => {
console.log("Logged in:", e.detail.user.email);
});

auth.addEventListener("osm-connected", (e) => {
console.log("OSM connected:", e.detail.osmData.osm_username);
});

auth.addEventListener("logout", () => {
console.log("User logged out");
window.location.href = "/";
});
`

Usage Modes

$3

Shows a compact login button in the header:

`html



hanko-url="https://login.hotosm.org"
redirect-after-login="/"
>



`

#### Button Styling

Customize the login button appearance with button-variant and button-color:

`html




hanko-url="https://login.hotosm.org"
button-variant="outline"
button-color="primary"
>


hanko-url="https://login.hotosm.org"
button-variant="plain"
button-color="neutral"
>


hanko-url="https://login.hotosm.org"
button-variant="filled"
button-color="danger"
>
`

$3

Shows full authentication form (for login pages):

`html
hanko-url="https://login.hotosm.org"
show-profile
osm-required
auto-connect
redirect-after-login="https://portal.hotosm.org"
>
`

Styling

The component uses Shadow DOM and can be customized using CSS custom properties.

$3

| Property | Description | Default |
| ----------------------------- | ---------------------------------- | ------------------------------------ |
| --login-btn-margin | Margin around the login button | 0 |
| --login-btn-padding | Padding inside the login button | var(--hot-spacing-x-small) var(--hot-spacing-medium) |
| --login-btn-bg-color | Background color of login button | var(--hot-color-primary-1000) |
| --login-btn-hover-bg-color | Background color on hover | var(--hot-color-primary-900) |
| --login-btn-border-radius | Border radius of login button | var(--hot-border-radius-medium) |
| --login-btn-text-color | Text color of login button | white |
| --login-btn-text-size | Font size of login button text | var(--hot-font-size-medium) |
| --login-btn-font-family | Font family of login button | inherit |

Example:

`css
hotosm-auth {
--login-btn-margin: 8px;
--login-btn-padding: 12px 24px;
--login-btn-bg-color: #d73f3f;
--login-btn-hover-bg-color: #b83333;
--login-btn-border-radius: 8px;
--login-btn-text-color: #ffffff;
--login-btn-text-size: 16px;
--login-btn-font-family: 'Arial', sans-serif;
}
`

Configuration

$3

The component detects the Hanko URL in the following priority order:

1. hanko-url attribute
2. tag
3. window.HANKO_URL global variable
4. window.location.origin (fallback)

`html










``