@humlabs/react

React hooks and components for Hum visitor counters.

Installation

npm install @humlabs/core @humlabs/react

Quick Start

import { HumProvider, useHum } from '@humlabs/react';

function App() {
  return (
    <HumProvider
      siteId="site_abc123"
      template="minimal-pill" // optional: badge template slug for dashboard analytics
    >
      <Counter />
    </HumProvider>
  );
}

function Counter() {
  const { count, loading } = useHum({ type: 'unique' });

  if (loading) return <div>Loading...</div>;
  return <div>{count} visitors</div>;
}

Hooks

useHum(options?)

Main hook for fetching counts. Returns { count, loading, error, track }.

const { count, loading, error, track } = useHum({ type: 'unique' });
// type: 'unique' | 'views' | 'online'  (default: 'unique')

useTicker(target, duration?)

Animated counter that smoothly transitions to target value.

const { count } = useHum();
const animated = useTicker(count, 2000); // duration in ms, default 1000

return <div>{animated}</div>;

usePresence()

Realtime presence count via WebSocket.

const online = usePresence();
return <div>{online} online</div>;

useWatermark()

Returns the current watermark state for hobby-plan sites approaching their visit cap.

const { state, usage } = useWatermark();
// state: 'free' | 'over_limit' | 'hidden'
// usage: { plan, used, limit, reset_at } | null

Development

Watch Mode (Auto-rebuild)

npm run dev

Build Once

npm run build

Run Tests

npm test

License

MIT