Widgemo Props

WidgemoProps is the runtime prop contract for the <Widgemo> component. There are only 7 top-level props — almost all configuration lives inside config as a WidgemoConfig object.

import { Widgemo } from '@widgemo/widgemo-core';

<Widgemo
  data={rows}
  config={config}
/>

Props

Prop	Type	Required	Description
data	Entity[]	yes	Input dataset. Each element is a plain object (Record<string, unknown>).
config	WidgemoConfig	no	Layout and behaviour configuration. Omitting renders data with defaults.
className	string	no	Additional CSS class on the root element.
id	string	no	HTML id on the root element; also the second arg to zone title/subtitle functions. Auto-generated (wg-…) if omitted.
loading	boolean	no	Sugar prop — forces the content zone into a loading state. Overrides config.zones.content.status.
error	unknown	no	Sugar prop — forces the content zone into an error state.
onRetry	() => void	no	Sugar prop — retry callback wired into the content error UI.

data

data is the only required prop. It accepts an array of plain objects (Entity[] — Record<string, unknown>[]). Each element represents one record; the keys become addressable field keys in config.zones.content.item.fields.

Three records with name, role, status, and score keys — config.zones.content.item.fields maps each key to a labeled column.

Team

3 members

Name	Role	Status	Score
Aurora Chen	Product Designer	active	92%
Mateo Silva	Engineer	pending	71%
Priya Nair	Operations	inactive	55%

const rows = [
  { name: 'Aurora Chen', role: 'Product Designer', status: 'active',   score: 92 },
  { name: 'Mateo Silva',  role: 'Engineer',         status: 'pending',  score: 71 },
  { name: 'Priya Nair',   role: 'Operations',       status: 'inactive', score: 55 },
];

<Widgemo data={rows} config={config} />

data is passed by reference — updating the array reference causes Widgemo to re-render. Field keys do not need to be declared in advance; any key present in the objects can be addressed by FieldConfig.key.

config

The config prop accepts a WidgemoConfig object. For the full shape — containerFrame, devMode, collapse, interactions.onEvent, preRender, header/footer zones, and all ContentConfig options — see Widgemo Config.

Omitting config renders data using built-in defaults (auto-detected table mode, all keys as plain text fields).

className

className appends a custom CSS class to Widgemo's root element — it does not replace Widgemo's internal class. Use it to apply per-instance styles from your own stylesheet.

Custom class docs-outline-widget adds an indigo outline to this widget's root element.

Team Directory

Name	Role
Aurora Chen	Product Designer
Mateo Silva	Engineer
Priya Nair	Operations

/* your stylesheet */
.docs-outline-widget {
  outline: 2px solid #4f46e5;
  outline-offset: 3px;
}

<Widgemo data={rows} config={config} className="docs-outline-widget" />

id

id sets the HTML id attribute on the root element and is passed as the second argument to any title or subtitle function in ZoneConfig.

If omitted, Widgemo auto-generates a stable wg-<random> id on mount — so every instance is uniquely addressable in the DOM even without an explicit prop.

id=team-widget — the header title function receives it as its second argument. The root element also gets id=team-widget in the DOM.

team-widget — 3 members

id is the second arg to title(data, id)

Name	Role
Aurora Chen	Product Designer
Mateo Silva	Engineer
Priya Nair	Operations

<Widgemo
  data={rows}
  id="team-widget"
  config={{
    zones: {
      header: {
        // id is the value of the id prop
        title: (data, id) => `${id} — ${data.length} members`,
      },
    },
  }}
/>

Common uses for id:

• Scroll target — <a href="#team-widget">Go to table</a>
• Accessibility — aria-labelledby="team-widget", aria-describedby="team-widget"
• CSS overrides — #team-widget { … } for per-instance style rules
• Dynamic title — received as id in title(data, id) and subtitle(data, id) zone functions
• Auto-generated fallback — when omitted, Widgemo sets id="wg-Xk3mPq2f" (random, stable for the instance lifetime)

loading, error, and onRetry

These three props are "sugar" — shortcuts to the content zone status system that avoid writing a full loadingState/errorState config block for simple cases.

loading=true triggers the content spinner without any config.zones.content.status wiring.

Loading state

Loading...

<Widgemo data={rows} config={config} loading={isLoading} />

error prop + onRetry wires a retry button into the content error state.

Error state

An error occurred

<Widgemo
  data={rows}
  config={config}
  error={fetchError}
  onRetry={refetch}
/>

onRetry precedence

• When error + onRetry are provided, onRetry is wired into the content error retry action.
• If config.zones.content.errorState.retry is an object with a label, that label is preserved; only the onRetry callback is overridden.
• If config.zones.content.errorState.retry is false, retry remains disabled — onRetry is not injected.
• Content-level errorState.retry.onRetry takes precedence over the top-level onRetry when both are defined.

For the full loadingState and errorState config options, indicator variants, skeleton shapes, severity styles, and custom renderer signatures, see Content Config — Loading States and Content Config — Error States.

See Also

• Widgemo Config — full WidgemoConfig reference: zones, containerFrame, devMode, gestures
• Content Config — ContentConfig: loading/error states, pagination, search, grouping
• Field Config — FieldConfig and all renderAsOptions
• Action Config — action shape, placement, overflow, and action builders
• Extension API — widgemoRegistry, advanced, InteractionContext
• Utilities — widgemoColors, temporal utilities, general utilities
• All Exports — every named export from @widgemo/widgemo-core with links
• Theme API — WidgemoThemeProvider and theme registration