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.

A leaderboard format is a deliberately different way of presenting procurement data compared to the heatmap or sector trends widgets. Rather than showing how activity is distributed, it names names — surfacing the specific companies that are winning the most work. This is exactly the kind of information a business owner wants when sizing up the competitive landscape before deciding whether to enter a new category, or when checking whether their own company appears where it should relative to competitors.

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.

Displaying the applied filters alongside the ranking matters because a leaderboard without context can be misleading. "Top 5 suppliers" means something very different depending on whether it covers the whole country across every sector, or a single province filtered to a single category. Surfacing the metadata keeps the widget honest about the scope of what it is showing, which is important given that the data is being embedded on third-party sites where the original filter selection might not be obvious to every visitor.

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://unpkg.com/@tenders-sa-org/widget-top-companies@latest/dist/widget-top-companies.global.js"
12  async
13></script>
HTML

Method 2: Programmatic (NPM)

Copy
1npm install @tenders-sa-org/widget-top-companies
BASH

Copy
1import { TopCompaniesWidget } from '@tenders-sa-org/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.

This server-side filtering design also has a practical implication for anyone embedding the widget on multiple pages of the same site. A construction industry publication, for example, could embed a Gauteng-filtered version on its Gauteng regional page and a Western Cape-filtered version on its Western Cape page, each showing a genuinely different, relevant leaderboard rather than the same national list repeated everywhere. Because each configuration triggers its own API request, every embedded instance stays independently accurate to its own filter combination.

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 @tenders-sa-org/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 already embed other Tenders-SA widgets on the same site, the Top Companies leaderboard pairs particularly well with the Sector Trends chart: the chart shows which sectors have the most activity, and the leaderboard filtered to that same sector shows exactly who is winning the work. Placing the two side by side on an industry-focused landing page gives visitors both the macro view and the specific supplier names in one glance, without requiring them to navigate away to Tenders-SA.org to piece the picture together themselves.

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.