Skip to main content

Demo Mode

A widget normally needs a working backend before it can show anything: an OAuth connection, a whitelisted domain, or an API reachable from the portal. Demo Mode removes that dependency. When it's on, the widget shows hardcoded demo data instead of calling its API, so you can place it on any portal, for example a demo portal for a client walkthrough, and it works immediately.

Demo Mode has a second purpose: the demo data documents the data contract. It is written against the same TypeScript types as the real API responses, so anyone reading it sees exactly what each API call is expected to return, and the compiler flags the demo data when the contract changes.

Widgets created from the current template have Demo Mode built in, switched off by default. Switch it on in the widget's settings wherever you want demo data.

How it works​

Demo Mode swaps the widget's data source in one place, at the top of the widget. Everything below that point (components, loading and error handling, React Query) is identical in both modes:

Demo Mode on → demo API → returns hardcoded demo data ┐
├→ same widget UI
Demo Mode off → real API → httpClient + apiUrl ┘

In demo mode the widget makes no network calls for its data, so it needs no OAuth connection, no domain whitelisting, and no backend.

There is no visible "demo" indicator in the UI. Demo portals are shown to clients, so the widget looks exactly as it would with live data.

The setting​

Demo Mode is an ordinary widget setting, defined in widget-config.json: in settingsSchema, plus a matching entry in defaultProps:

"defaultProps": {
"apiUrl": "_internal_api_",
"demoMode": false
},
"settingsSchema": {
"uiSchema": {
"demoMode": { "ui:widget": "ToggleWidget", "ui:options": {} },
"ui:order": ["title", "titleTooltip", "apiUrl", "demoMode"]
},
"jsonSchema": {
"type": "object",
"properties": {
"demoMode": { "type": "boolean", "title": "Demo Mode", "default": false }
}
}
}

Like every setting, it reaches the widget as a prop (demoMode). Whoever places the widget on a dashboard can switch it on in the widget's settings, for example on a demo portal with no backend connected.

In the settings form, Demo Mode is a toggle switch with its title above it, like the other settings. ToggleWidget is not one of the built-in @invent/json-settings widgets: the template defines it in src/<widget>/<widget>-settings-widgets.tsx and registers it through the widgets prop of JsonForm in the widget's settings component:

// src/<widget>/<widget>-settings.tsx
<JsonForm
{...jsonSchemaProps}
formData={jsonSchemaProps.formData}
schema={settingsSchema as any}
widgets={{ ...jsonSchemaProps.widgets, ...settingsWidgets }}
/>

You can use "ui:widget": "ToggleWidget" for any other on/off setting in the same widget.

apiUrl keeps its default value, so the settings form is valid in either mode.

Switching the data source​

The widget's API module defines an interface and a factory that builds the real implementation from the platform httpClient and the configured apiUrl. Demo Mode adds a second factory that implements the same interface with hardcoded data:

// src/<widget>/api/<widget>-api.ts
export interface KpiTrackerApi {
getKpis(): Promise<KpiDto[]>;
}

export function createKpiTrackerApi(httpClient: HttpClientT<unknown>, apiUrl: string): KpiTrackerApi {
// real implementation: calls `${apiUrl}/kpis` through httpClient
}
// src/<widget>/api/<widget>-demo-api.ts
import type { KpiTrackerApi } from './<widget>-api';
import { DEMO_KPIS } from './<widget>-demo-data';

export function createDemoKpiTrackerApi(): KpiTrackerApi {
return {
getKpis: async () => DEMO_KPIS
};
}

The widget picks one of them once, at the top level, and passes it down:

// src/<widget>/<widget>.tsx
const KpiTracker = ({ demoMode = false, httpClient, apiUrl, ...props }: IKpiTrackerProps) => {
const api = useMemo(
() => (demoMode ? createDemoKpiTrackerApi() : createKpiTrackerApi(httpClient, apiUrl)),
[demoMode, httpClient, apiUrl]
);

return (
<WidgetRootWrapper>
<KpiTrackerInner api={api} {...props} />
</WidgetRootWrapper>
);
};

That is the only place demoMode is read. Keep it that way:

  • Don't check demoMode inside components, hooks, or query functions.
  • Don't pass demoMode further down the tree.
  • Do make the demo API return Promises, like the real one, so loading states and React Query behave the same.

Most widgets fetch some data and render it in a single view, so the switch is usually one useMemo and one extra file of demo data.

The template ships a working example of all of this: getItems() (GET {apiUrl}/items) in src/<widget>/api/<widget>-api.ts, its demo counterpart in <widget>-demo-api.ts, and DEMO_ITEMS in <widget>-demo-data.ts, rendered as an "Items" card. Replace them with your own endpoints and data.

Writing the demo data​

Put the demo data in its own file next to the API module and type it with the same DTOs the real API returns:

// src/<widget>/api/<widget>-demo-data.ts
import type { KpiDto } from './<widget>-api';

/** Example response of GET {apiUrl}/kpis. */
export const DEMO_KPIS: KpiDto[] = [
{ id: '1001', label: 'Assets Under Management', value: 482_300_000, trend: 0.042 },
{ id: '1002', label: 'Net New Assets (QTD)', value: 12_750_000, trend: 0.118 },
{ id: '1003', label: 'Client Retention', value: 0.97, trend: -0.004 }
];

Guidelines:

  • Hardcode it. The demo data is part of the widget bundle, with no fetching and no external files.
  • Type every value with the real DTO. That is what makes the demo data a reliable description of the contract: if a field is renamed or a type changes, the build fails until the demo data is updated.
  • Make it look real. Clients see it on demo portals. Use plausible names, amounts, and dates, never placeholder text like foo or test.
  • Mirror real responses. Start from an actual API response, remove anything sensitive, and keep the same shape, including optional fields and nesting.
  • Keep ids as strings, exactly as the real API does.
  • One constant per endpoint, with a comment naming the call it stands for.

Turning Demo Mode on and off​

To show demo data, open the widget's settings on the dashboard and switch Demo Mode on. Switch it off again to go back to live data.

With Demo Mode off (the default), the widget uses httpClient and apiUrl as usual and needs whatever the real API requires: an OAuth connection, domain whitelisting, and so on. See OAuth Authentication.

If a widget is meant mainly for demos, you can have new instances start in demo mode: in widget-config.json, set demoMode to true in both defaultProps and the jsonSchema property's "default". Existing widget instances keep whatever value they were saved with.

In local development (npm run dev), the harness starts with Demo Mode on, because it has no backend. Toggle it in the harness's settings dialog to exercise the real API path.

Where to go next​