React

Install

npm install @elaanio/react

The React package ships the three components, the hooks behind them, and SSE realtime. It depends on @elaanio/react-core (provider + hooks) and @elaanio/core.

Components

import { ElaanProvider, NotificationBell, NotificationFeed, Preferences } from "@elaanio/react";
import "@elaanio/react/styles.css";

<ElaanProvider apiBase="https://api.elaan.io/v1" tokenProvider={tokenProvider}>
  <NotificationBell />              {/* bell + badge + popover */}
  <NotificationFeed />             {/* inbox list, inline */}
  <Preferences />                  {/* per-type × channel toggles */}
</ElaanProvider>

Everything below ElaanProvider shares one client, one inbox store and one realtime connection, so a bell in your header and a feed on a notifications page stay in sync without any wiring between them.

Hooks

Each component is a thin shell over a hook you can call directly:

import {
  useNotifications, useUnreadCount, usePreferences, usePush,
} from "@elaanio/react";

const { notifications, markRead, markAllRead, remove, refresh } = useNotifications();
const unread = useUnreadCount();
const { preferences, setPreference, clearPreference } = usePreferences();
const { register, unregister } = usePush();

Reads and writes are optimistic: marking a notification read updates the store immediately and reconciles against the server response. See Headless to go one level lower.

Realtime options

Realtime is on by default over SSE with automatic polling fallback. Pass realtime={false} to force polling, or pollInterval={ms} to tune it.

<ElaanProvider
  apiBase="https://api.elaan.io/v1"
  tokenProvider={tokenProvider}
  realtime={true}
  pollInterval={30000}
>

More on the transport and its fallback in Real-time.

Styling

Import @elaanio/react/styles.css once, then override the CSS custom properties on :root. Light and dark are automatic via prefers-color-scheme. Full token list in Theming.