Why a Supplier Leaderboard Matters

Understanding which companies win government contracts is a key piece of market intelligence. It reveals who your competitors are, which sectors are active, and where procurement spending is concentrated. However, this data is not easy to aggregate — tender awards are published across dozens of different government portals and PDF notices.

The Top Companies widget (github.com/Tenders-SA/widget-top-companies

) provides an embeddable, ranked leaderboard of suppliers by total awarded tender value. It is an open-source, zero-dependency JavaScript widget that can be added to any website with a single HTML tag. This guide covers its architecture, embed methods, filtering options, and links to the source repository.

What Data Does the Widget Display?

The widget fetches data from the /api/widgets/top-companies endpoint and renders a ranked leaderboard. Each entry shows:

The API also returns metadata about the request — the province and category filters applied, and a generation timestamp. This allows the widget to display context about the current view.

Architecture: How the Widget Works

Like the other Tenders-SA widgets, the Top Companies widget is a vanilla TypeScript class compiled to a self-contained bundle via tsup. It has no external dependencies. The architecture follows a consistent pattern:

• api.ts — The fetchTopCompanies() function builds a URL from the config parameters (province, category, limit) and calls the endpoint. It returns a TopCompaniesResponse with a data array and a meta object.
• renderer.ts — The DOM renderer builds the leaderboard layout: a ranked list where each supplier is shown with their position number, name, contract count badge, and formatted total value. Styles are injected programmatically with deduplication.
• index.ts — The TopCompaniesWidget class accepts config in the constructor, calls render(container) to fetch and display data, and supports destroy() for cleanup.

Configuration Options

A key difference from the simpler Winners Feed widget is that the Top Companies widget supports server-side filtering through query parameters. The filters are passed to the API, which aggregates the data before returning. This keeps the client lightweight.

When using the data-attribute method, set these via attributes on the container element: data-province, data-category, data-limit, and data-theme.

Embed Methods

Method 1: HTML Data Attribute

Copy
1<!-- Top 5 construction suppliers in Gauteng, dark theme -->
2<div
3  data-tendersa-top-companies
4  data-limit="5"
5  data-province="gauteng"
6  data-category="construction"
7  data-theme="dark"
8></div>
9
10<script
11  src="https://cdn.tenders-sa.org/widgets/widget-top-companies.js"
12  async
13></script>
HTML

Method 2: Programmatic (NPM)

Copy
1npm install @tendersa/widget-top-companies
BASH

Copy
1import { TopCompaniesWidget } from '@tendersa/widget-top-companies'
2
3const container = document.getElementById('leaderboard')
4const widget = new TopCompaniesWidget({
5  province: 'western-cape',
6  category: 'all',
7  limit: 10,
8  theme: 'light',
9})
10
11await widget.render(container)
JAVASCRIPT

Note that the programmatic constructor takes the config object and render() takes the container reference, which is slightly different from the Winners Feed API. This design lets you instantiate the widget once and render it into different containers if needed.

Filtering Behaviour

The filtering behaviour is worth understanding because it drives what the widget displays:

• Province filter: If set to a specific province (e.g. 'gauteng'), the API returns only suppliers whose contracts are managed in that province. This is useful for regional industry publications or local business directories.
• Category filter: Filters by procurement category. You can use this to show, for example, only IT suppliers or only construction contractors. Category slugs match the Tenders-SA category taxonomy.
• Combined filters: Province and category can be combined. For example, province=gauteng&category=information-technology returns the top IT suppliers in Gauteng.
• Limit: Controls how many suppliers appear in the list. The maximum is 10 — the widget is designed to be a compact leaderboard, not a full directory.

All filtering is done server-side by the API endpoint, not by filtering on the client. This means the widget receives only the data it needs to render, keeping the bundle size small and the render fast.

Browser Support and Performance

• Bundle size: approximately 5 KB (minified and gzipped)
• Supports all modern browsers (Chrome, Firefox, Safari, Edge)
• The API endpoint uses Incremental Static Regeneration with 1800-second revalidation, so repeated requests to the same filtered view are served from the Edge cache
• Network request falls through to an error state displayed inline if the API is unreachable

The Open Source Package

The Top Companies widget is published as @tendersa/widget-top-companies on npm and is open source under the MIT license. The source code is available at github.com/Tenders-SA/widget-top-companies

.

The repository includes TypeScript source code with exported type definitions, unit tests via Vitest, a tsup build pipeline that outputs ESM, CJS, and UMD bundles, and a README with embed examples. The widget is also available as an IIFE bundle served from the Tenders-SA CDN.

Use Cases

The Top Companies widget is designed for websites that serve the South African procurement ecosystem:

• Industry news and analysis sites — Show a sidebar of top contractors in the sector you cover, demonstrating market awareness.
• Business and supplier directories — Provide context about which companies are winning work in specific regions or categories.
• Local government and municipal sites — Display transparency metrics about procurement spending in your jurisdiction.
• Research and academic publications — Reference real supplier ranking data in procurement research.

Getting Started

The quickest way to add the widget is with the data-attribute method shown above. For more control, install the npm package and use the programmatic API. The full source code, documentation, and issue tracker are at github.com/Tenders-SA/widget-top-companies

.

If you are accessing the underlying data directly, the API endpoint at /api/widgets/top-companies is CORS-enabled and returns the TopCompaniesResponse format documented in the widget source. You can use it to build custom visualisations or integrate the data into your own systems.