Web component for HOTOSM SSO authentication with Hanko and OSM integration
npm install @hotosm/hanko-authLit-based web component for HOTOSM SSO authentication with Hanko and OpenStreetMap integration.
``bashnpm
npm install @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
``