Skip to content

Node Badges

Small visual indicators on nodes for status, counts, alerts, or contextual info.

NodeBadge Interface

PropertyTypeDefaultDescription
textstringRequiredBadge text or number.
colorstring'#ffffff'Text/icon color.
backgroundstring'#ef4444'Background color.
positionstring'top-right''top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
shape'circle' | 'rect''circle'Badge shape.
icon'dot' | 'alert' | 'check' | 'star'undefinedBuilt-in icon (overrides text).

Basic Usage

TypeScript 
graph.addNode({
  id: 'server-1',
  data: { name: 'Web Server', status: 'healthy' },
  style: {
    fill: '#3b82f6',
    label: 'Web Server',
    badges: [
      {
        text: 'OK',
        color: '#ffffff',
        background: '#10b981',
        position: 'top-right',
        shape: 'rect',
      },
    ],
  },
});

Multiple Badges

TypeScript 
graph.addNode({
  id: 'user-alice',
  data: { name: 'Alice' },
  style: {
    fill: '#8b5cf6',
    label: 'Alice',
    badges: [
      { text: '5', color: '#fff', background: '#ef4444', position: 'top-right' },
      { text: '', icon: 'star', color: '#fbbf24', background: '#78350f', position: 'top-left' },
      { text: '', icon: 'dot', color: '#10b981', background: '#064e3b', position: 'bottom-right' },
    ],
  },
});

Built-in Icons

IconVisualUse Case
'dot'Filled circleOnline/offline status
'alert'Exclamation markWarnings, errors
'check'CheckmarkVerified, completed
'star'StarFavorites, featured
TypeScript 
const statusBadge = (status) => {
  switch (status) {
    case 'healthy':
      return { icon: 'check', color: '#10b981', background: '#064e3b' };
    case 'warning':
      return { icon: 'alert', color: '#f59e0b', background: '#78350f' };
    case 'critical':
      return { icon: 'alert', color: '#ef4444', background: '#7f1d1d' };
  }
};

Updating Badges

TypeScript 
// Update notification count
graph.updateNode('user-alice', {
  style: {
    badges: [
      { text: '12', color: '#fff', background: '#ef4444', position: 'top-right' },
    ],
  },
});

// Remove all badges
graph.updateNode('user-alice', { style: { badges: [] } });

Dynamic Badges from Data

TypeScript 
graph.batch(() => {
  for (const node of graph.getNodes()) {
    const count = graph.getNeighbors(node.id).length;
    graph.updateNode(node.id, {
      style: {
        badges: [{
          text: String(count),
          color: '#e2e8f0',
          background: count > 5 ? '#7c3aed' : '#475569',
          position: 'bottom-right',
        }],
      },
    });
  }
});

“Made with TopoKit” Branding

There are two distinct “Made with TopoKit” surfaces — they look similar but live at different layers and respond to different conditions:

  1. SDK canvas watermark. Painted directly into the graph canvas by the renderer (watermark.ts). Only shown for unlicensed or trial builds; a valid license suppresses it. The SDK uses getBoundingClientRect to lift the watermark above any bottom-right toolbar so it doesn't overlap controls.
  2. Page-level DOM badge. An <a class="tk-made-with"> element rendered by the host page (TopoKit Play, shared topos at /t/<hash>, embedder pages). This is the badge you see when the SDK watermark is suppressed by a valid license. Style and link target are owned by the host page, not the SDK.

The two are independent: licensed embeds can still surface the page-level DOM badge as soft attribution, and the SDK watermark only ever appears when there is no valid license.

Next Steps