@vietmap/tracking-sdk-react

@vietmap/tracking-sdk-react

React SDK for GPS Tracking — drop-in Dashboard, LiveMap, and Report components built on React Query and VietmapGL.

Install

npm install @vietmap/tracking-sdk-react
# or
pnpm add @vietmap/tracking-sdk-react

Peer deps: react >= 16.8, react-dom >= 16.8.

Quick start

import {
  FleetworkProvider,
  Dashboard,
  LiveMap,
  Report,
} from '@vietmap/tracking-sdk-react'
import '@vietmap/tracking-sdk-react/styles.css'

export default function App() {
  return (
    <FleetworkProvider
      apiKey="YOUR_API_TOKEN"
      apiKeyTilemap="YOUR_VIETMAP_TILE_KEY"
      baseUrl="https://your-api-server.com"
      locale="vi"
    >
      <Dashboard />
      <LiveMap height="600px" memberNameKey="userName" />
      <Report />
    </FleetworkProvider>
  )
}

Provider

Prop	Type	Default	Description
apiKey	string	—	API token (X-API-Key header)
apiKeyTilemap	string	—	VietMap tile key for map rendering
baseUrl	string	—	API base URL — SDK appends /api/v1/ automatically
locale	'vi' | 'en'	'vi'	UI language
theme	ThemeConfig	—	CSS variable overrides (see Theming)

Components

<Dashboard />

All-in-one dashboard with 5 widgets. Each widget can also be imported standalone.

Widget	Description
SummaryCards	Total distance / travel time / fuel cost for a date
MemberReport	Per-user table with pagination and status badges
ActivityHeatmap	Hourly activity heatmap over a date range
FuelTracking	Fuel consumption bar/line chart
MonthlyExpenses	Monthly cost breakdown chart

import { SummaryCards, MemberReport } from '@vietmap/tracking-sdk-react'

<SummaryCards date={Date.now()} pollInterval={30_000} />
<MemberReport pageSize={20} onRowClick={(m) => console.log(m)} />

<LiveMap />

Real-time fleet map backed by VietmapGL with GPU-accelerated clustering.

Key features:

• Auto-polling member positions (pollInterval, default 10 s)
• GeoJSON clustering — renders 3 000+ markers as GL circle layers (no DOM nodes), zoom to expand clusters
• Spiderfy — click overlapping markers at the same coordinate to fan them out and select individually
• Member sidebar — infinite scroll, sorted moving → stopped → signal lost, with live search
• Tile switcher (terrain / satellite / road)
• Click a marker → popup → View History → animated playback with traveled/remaining route overlay
• ref API: flyTo, fitBounds, focusMember, getMembers, getMap

import { useRef } from 'react'
import { LiveMap, type LiveMapRef, type MemberStatus } from '@vietmap/tracking-sdk-react'

const mapRef = useRef<LiveMapRef>(null)

<LiveMap
  ref={mapRef}
  height="600px"
  center={[106.63, 10.82]}
  zoom={6}
  defaultTile="terrain"
  pollInterval={10_000}
  maxUsers={3000}
  clusterRadius={50}
  clusterMaxZoom={14}
  memberNameKey="userName"
  showList
  showLegend
  showTileSwitcher
  onMapReady={(map) => console.log('ready', map.getZoom())}
  onMarkerClick={(m: MemberStatus) => console.log(m.name)}
/>

LiveMapProps

Prop	Type	Default	Description
height	string	'100dvh'	Map container height
center	[lng, lat]	[106.6, 10.8]	Initial map center
zoom	number	11	Initial zoom level
defaultTile	'terrain' | 'satellite' | 'road'	'terrain'	Map tile style
pollInterval	number	10000	Member position refresh interval (ms)
maxUsers	number	3000	Max users fetched per poll
clusterRadius	number	50	Cluster radius in pixels
clusterMaxZoom	number	14	Zoom level at which clustering stops
memberNameKey	string	—	Key in lastLocation.metadata to use as display name
members	MemberStatus[]	—	Override with local data (skips API polling)
showList	boolean	true	Show member sidebar
showLegend	boolean	true	Show status legend
showTileSwitcher	boolean	true	Show tile switcher control
onMarkerClick	(m) => void | boolean	—	Marker click callback; return false to suppress default popup
onMemberClick	(m) => void | boolean	—	Sidebar item click callback
onMapClick	([lng, lat]) => void	—	Map background click
onMapReady	(map) => void	—	Fires once after map loads
renderMarkerPopup	(m) => ReactNode	—	Custom popup content
renderMemberItem	(m, default) => ReactNode	—	Custom sidebar row renderer

LiveMapRef (imperative API)

mapRef.current?.flyTo([106.63, 10.82], 14)
mapRef.current?.fitBounds([[102, 8], [110, 23]])
mapRef.current?.focusMember('user-123')   // fly to + open popup
mapRef.current?.getMembers()              // MemberStatus[]
mapRef.current?.getMap()                  // MapInstance

<Report />

All-in-one report hub. Landing page with 3 cards → navigate into report types.

Report	Tabs	Description
Trip	Summary / Detail	Per-user trip totals and individual trip rows
Fuel	Summary / Detail	Fuel consumption and cost per user/trip
Activity time	—	Hourly active/inactive counts and distance

All report tables include row numbers, zebra striping, right-aligned numeric columns, sortable headers, and paginator with page number buttons + first/last navigation.

<Report from={Date.now() - 30 * 86_400_000} to={Date.now()} />

Sub-reports can also be used standalone:

import {
  TripSummaryReport,
  TripDetailReport,
  FuelSummaryReport,
  FuelDetailReport,
  ActivityTimeReport,
} from '@vietmap/tracking-sdk-react'

// All accept: range, onRangeChange, onBack, onError, pageSize
<TripSummaryReport
  range={{ from, to }}
  onRangeChange={setRange}
  pageSize={20}
/>

Hooks (React Query)

All hooks require FleetworkProvider in the tree. They return { data, isLoading, error, refetch, isFetching }.

// Dashboard
const { data } = useSummaryCards({ date?, pollInterval? })
const { data } = useMemberReport({ date?, page?, pageSize?, status? })
const { data } = useActivityHeatmap({ from?, to?, metric? })
const { data } = useFuelTracking({ from?, to?, groupBy? })
const { data } = useMonthlyExpenses({ from?, to?, currency? })

// LiveMap
const { data } = useMembers({ pollInterval?, nameKey?, maxUsers? })
const { data } = useMember(userId)
const { data } = useHistoryRoute({ userId, startTime, endTime })

// Reports
const { data } = useTripSummaryReport({ from, to, page?, pageSize?, sortBy?, sortDesc? })
const { data } = useTripDetailReport({ from, to, page?, pageSize?, sortBy?, sortDesc? })
const { data } = useFuelSummaryReport({ from, to, page?, pageSize?, sortBy?, sortDesc? })
const { data } = useFuelDetailReport({ from, to, page?, pageSize?, sortBy?, sortDesc? })
const { data } = useActivityTimeReport({ from, to, page?, pageSize? })

Controllers (framework-agnostic)

Use outside React — in Zustand actions, Redux thunks, Node scripts, or any non-React context.

import {
  initFleetwork,
  DashboardController,
  LiveMapController,
  ReportController,
} from '@vietmap/tracking-sdk-react'

initFleetwork({ apiKey: '...', apiKeyTilemap: '...', baseUrl: '...' })

const summary    = await DashboardController.getSummaryCards()
const members    = await LiveMapController.getMembers({ pageSize: 3000 })
const history    = await LiveMapController.getHistoryRoute(userId, from, to)
const tripReport = await ReportController.getTripSummary({ from, to })
const fuelReport = await ReportController.getFuelSummary({ from, to })

Theming

Override CSS variables via the theme prop:

<FleetworkProvider
  theme={{
    colors: {
      primary: '#2563eb',
      background: '#0f172a',
      text: '#f1f5f9',
    },
    borderRadius: 8,
    fontFamily: 'Inter, sans-serif',
  }}
>

Build

pnpm install
pnpm build

Outputs:

• dist/tracking-sdk-react.js (ESM)
• dist/tracking-sdk-react.cjs (CommonJS)
• dist/index.d.ts (TypeScript declarations)
• dist/tracking-sdk-react.css (styles)

License

MIT © VietMap