@tenders-sa-org/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/@tenders-sa-org/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/@tenders-sa-org/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 @tenders-sa-org/widget-heatmap

import { HeatmapWidget } from '@tenders-sa-org/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