Configuration Model

Widgemo configuration is four nested layers. Understanding the boundary between each layer is the core skill for working with the library.

Widgemo props — runtime inputs: data, config, and optional sugar props (loading, error)
zones — compose the Widgemo surface into named structural regions: header chrome, content data area, footer chrome
content — controls what the data does and how it renders: mode, sorting, filtering, grouping, gestures, actions
item and fields — item controls how a single record is arranged; fields control how each value appears

Configuration Model — Live Example

Header with a zone action, content with a sorted table using badge, currency, and sparkTrend renderers, and a footer zone with its own action. Click Export or View All — the interaction is logged to the browser console.

Team Performance

Q2 2026

Name	Role	Status	Revenue	Trend
Priya Nair	Engineering Lead	active	$155,000.00	+20.0%
Aurora Chen	Design Lead	active	$142,000.00	+33.0%
Mateo Silva	Platform Eng	active	$131,500.00	-18.0%
Jordan Reyes	Data Science	inactive	$112,000.00	-16.0%
Sam Torres	Growth	pending	$98,000.00	+25.0%

Updated today

The Four Layers

1. Widgemo Props

At the outermost level you pass data and config into <Widgemo>. Everything else lives inside config.

import { Widgemo, WidgemoThemeProvider } from '@widgemo/widgemo-core';
import '@widgemo/widgemo-core/style.css';

const data = [
  { id: 1, name: 'Priya Nair',   role: 'Engineering Lead', status: 'active',   revenue: 155000, trend: [60, 65, 70, 68, 72, 75, 80] },
  { id: 2, name: 'Aurora Chen',  role: 'Design Lead',      status: 'active',   revenue: 142000, trend: [38, 44, 41, 55, 62, 58, 71] },
  { id: 3, name: 'Mateo Silva',  role: 'Platform Eng',     status: 'active',   revenue: 131500, trend: [70, 64, 68, 60, 55, 58, 52] },
  { id: 4, name: 'Jordan Reyes', role: 'Data Science',     status: 'inactive', revenue: 112000, trend: [50, 45, 42, 40, 38, 36, 34] },
  { id: 5, name: 'Sam Torres',   role: 'Growth',           status: 'pending',  revenue: 98000,  trend: [20, 25, 30, 28, 35, 40, 45] },
];

<WidgemoThemeProvider theme="light">
  <Widgemo data={data} config={config} />
</WidgemoThemeProvider>

data is a plain array of objects — no special shape required. Notice that id is present in the data but will not appear in the Widgemo because it is not declared in fields. trend is an array of numbers; sparkTrend reads it as a series and derives the delta from first to last value.

config is a serialisable configuration object — no callbacks live in it except interaction handlers under interactions.onEvent.

2. Zones

Zones are the structural skeleton of the Widgemo surface. There are three named slots:

header — title, subtitle, and zone-level actions above the data
content — the dataset region (required)
footer — secondary chrome, summary text, or actions below the data

{
  interactions: {
    onEvent: (ctx) => {
      if (ctx.entity) {
        // item-action or item-click — entity is the specific row
        console.log('[Widgemo]', ctx.kind, ctx.interactionId, ctx.entity.name);
      } else {
        // zone-action — no entity; data holds the full visible dataset
        console.log('[Widgemo]', ctx.kind, ctx.interactionId, `(${ctx.data.length} rows)`);
      }
    },
  },
  zones: {
    header: {
      title: 'Team Performance',
      subtitle: 'Q2 2026',
      actions: [
        { id: 'export', label: 'Export', icon: 'export', placement: 'pinned' },
      ],
    },
    content: { /* ... */ },
    footer: {
      subtitle: 'Updated today',
      actions: [
        { id: 'view-all', label: 'View All', icon: 'external-link', placement: 'pinned' },
      ],
    },
  },
}

Header and footer are optional. The content zone is always required. interactions.onEvent at the top level of config is the single event sink for all zone and item actions — both the Export and View All buttons above route through it.

Zones do not control where in your page the Widgemo lives. That is a hosting concern. Zones only control the internal structure of the Widgemo surface itself.

3. Content

zones.content defines how the dataset renders and behaves.

content: {
  mode: 'table',
  sorting: [{ fieldKey: 'revenue', direction: 'desc' }],
  item: { /* ... */ },
},

mode picks the rendering strategy: 'table', 'grid', 'board', 'carousel', or 'chart'. The content zone also hosts sorting, filtering, grouping, pagination, gestures, and per-item actions — all declared as config, not imperative logic.

4. Item and Fields

item defines the layout of one entity. fields declare which values to show, how to label them, and how to render them.

item: {
  fields: [
    { key: 'name',    label: 'Name',    type: 'text',   sortable: true },
    { key: 'role',    label: 'Role',    type: 'text' },
    { key: 'status',  label: 'Status',  type: 'text',   renderAs: 'badge',
      renderAsOptions: { colorMap: { active: '#198754', pending: '#ffc107', inactive: '#6c757d' } } },
    { key: 'revenue', label: 'Revenue', type: 'number', renderAs: 'currency',
      renderAsOptions: { currency: 'USD' }, sortable: true },
    { key: 'trend',   label: 'Trend',   renderAs: 'sparkTrend',
      renderAsOptions: { width: 100, height: 32, showDeltaLabel: true } },
  ],
  layout: { type: 'auto' },
},

key maps to the entity property. type sets the sort comparator and default renderer. renderAs overrides the renderer. renderAsOptions configures it. Fields not listed in the array are not shown.

Reading a Config

When you encounter an unfamiliar Widgemo config, use this order:

zones — how many regions does the Widgemo have? What titles and actions do they carry?
zones.content.mode — what is the primary rendering strategy?
zones.content.item.layout — how are individual records arranged?
zones.content.item.fields — what values are shown and how are they rendered?
interactions.onEvent — what does the app do when something is clicked?