Top list

TopListCard lists rows in rank order: an optional rank badge, an icon or avatar, a title and a description, a formatted value, an optional delta and an optional row sparkline. The top rows can be highlighted, rows can link elsewhere, and an empty list shows emptyLabel.

Preview Code

Connecting to the DMS preview…

static topListCard = TopListCard({
  title: "Top products",
  valueFormat: "currency",
  currencyCode: "EUR",
  showRank: true,
  highlightTopN: 3,
  showDelta: true,
  showBar: true,
  actions: [
    {
      label: "Catalogue",
      to: "/products",
      icon: "i-ph-arrow-right",
    },
  ],
  staticItems: [
    {
      id: "p1",
      title: "Ergonomic chair",
      description: "Furniture",
      value: 18400,
      delta: 14.2,
    },
    {
      id: "p2",
      title: "Standing desk",
      description: "Furniture",
      value: 12900,
      delta: 6.8,
    },
    {
      id: "p3",
      title: "Noise-cancelling headset",
      description: "Audio",
      value: 9800,
      delta: -3.1,
    },
    {
      id: "p4",
      title: "USB-C dock",
      description: "Accessories",
      value: 6200,
      delta: 1.4,
    },
    {
      id: "p5",
      title: "4K monitor",
      description: "Displays",
      value: 5100,
      delta: -7.9,
    },
  ],
});

Usage

import { TopListCard } from "@antelopejs/interface-dms/base/top-list-card";

static products = TopListCard({
  title: "$shop.sales.top_products",
  fetchUrl: "/api/sales/top-products",
  periodScope: "sales",
  valueFormat: "currency",
  currencyCode: "EUR",
  showRank: true,
  highlightTopN: 3,
});

The route answers { items: TopListItem[] }. An item carries an id, a title and a value, plus optional description, valueLabel, delta (in percent), sparkline, icon, avatar (src, alt) and to.

Options

valuePrecision is available in code (Value precision).

Recipes

A unit after each value

valueSuffix: " ms" with valuePrecision: 0 turns 1864 into "1,864 ms". The suffix is written as given, so the space goes in it; a $ key is translated. A row whose figure no format can write sends a valueLabel instead — a string, a $ key or a composed text — which replaces the value and its suffix while value still sizes the bar.

Rows that keep the reader's scope

A row's to may carry {{params.X}} / {{query.X}}, filled from the page URL when the row is drawn. A route answering to: "/modules/shop/products?id=42&store={{query.store}}" keeps the reader's store without knowing it.

Pitfalls

• skeletonCount defaults to 10 loading rows; set it to the usual number of rows to keep the card's height.
• A row's title and description take $ keys or composed texts; never format numbers into them on the server.

Next steps