@tendersa/widget-heatmap

Tenders-SA Heatmap Widget — Embeddable province-level tender heatmap for South Africa.

A zero-dependency vanilla JS widget that renders a live tender heatmap showing active procurement opportunities across all South African provinces.

Quick Start

Script Tag (CDN)

<script src="https://unpkg.com/@tendersa/widget-heatmap@latest/dist/widget-heatmap.js"></script>
<div data-tendersa-heatmap></div>

Data Attributes API

<div
  data-tendersa-heatmap
  data-theme="light"
  data-province="gauteng"
></div>

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | data-tendersa-heatmap | boolean | — | Activates the widget on this element | | data-theme | 'light' \| 'dark' | 'light' | Color theme | | data-province | string | null | Filter to a single province |

Programmatic API

<div id="my-heatmap"></div>
<script type="module">
  import { HeatmapWidget } from 'https://unpkg.com/@tendersa/widget-heatmap@latest/dist/widget-heatmap.js'

  const container = document.getElementById('my-heatmap')
  const widget = new HeatmapWidget(container, {
    apiBase: 'https://tenders-sa.org',
    theme: 'dark',
    province: null,
  })

  widget.render()
</script>

NPM

npm install @tendersa/widget-heatmap

import { HeatmapWidget } from '@tendersa/widget-heatmap'

const widget = new HeatmapWidget(
  document.getElementById('heatmap-container'),
  { theme: 'dark' }
)

widget.render()

API

HeatmapWidget

| Method | Description | |--------|-------------| | constructor(element, config?) | Create widget instance | | render() | Fetch data and render the heatmap | | destroy() | Clean up event listeners and DOM |

Config Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiBase | string | 'https://tenders-sa.org' | API base URL | | theme | 'light' \| 'dark' | 'light' | Widget color theme | | province | string \| null | null | Filter to specific province |

Data Source

The widget fetches live data from GET /api/widgets/heatmap on the configured apiBase. The endpoint returns:

[
  {
    "province": "Gauteng",
    "tenderCount": 245,
    "totalValue": 12500000,
    "topIndustries": ["Construction", "IT"]
  }
]

Browser Support

Works in all modern browsers (Chrome, Firefox, Safari, Edge). Requires fetch and ES2022 support.

Development

# Install
npm install

# Build
npm run build

# Dev (watch mode)
npm run dev

# Type check
npm run typecheck

# Test
npm test

Links

• Tenders-SA Home
• Publisher Dashboard
• Provincial Tender Heatmap
• GitHub
• Issues

License

MIT © Tenders-SA