Widgemo Config

WidgemoConfig is the central configuration object. It is zone-oriented and mode-driven.

Shape

Field	Type	Default	Description
zones.header	ZoneConfig	—	Optional header zone
zones.content	ContentConfig	—	Required. Content zone (mode, fields, actions, etc.)
zones.footer	ZoneConfig	—	Optional footer zone
collapse.initialState	'expanded' | 'collapsed' | 'fixed'	'expanded'	Widget collapse behaviour
collapse.button	boolean	true	Show/hide the collapse toggle
containerFrame	{ shell?, border?, shadow?, borderRadius?, borderColor?, borderWidth?, overflow? }	—	Outer shell frame controls
style	CSSProperties	—	Inline styles on the root element
theme	string	—	Registered theme name
interactions.onEvent	(ctx: InteractionContext) => void	—	Global sink for all actions and gestures
devMode	boolean | DevModeConfig	false	Dev inspector overlay (allowInProduction opt-in available)
preRender	() => void	—	Config-level callback invoked by Widgemo before render

Header and Footer Zones

zones.header and zones.footer each accept a ZoneConfig object. Both are optional; the content zone is always required.

Header with dynamic title + icon, footer with subtitle — a typical starting point.

Team (3 members)

Active: 1

Name	Status
Aurora Chen	active
Mateo Silva	pending
Priya Nair	inactive

Last synced just now

const config = {
  collapse: { initialState: 'expanded', button: true }, // top-level — see § Collapse below
  zones: {
    header: {
      title:    (data) => `Team (${data.length} members)`,
      subtitle: (data) => `Active: ${data.filter(d => d.status === 'active').length}`,
      icon:    { name: 'users', size: 24, color: '#4f46e5' },
      layout:  { iconPosition: 'left', titlePosition: 'left' },
      actions: [{ id: 'export', label: 'Export', icon: 'export', placement: 'pinned' }],
      themeOverrides: { /* ZoneTheme */ },
      style: { /* CSSProperties */ },
    },
    content: { /* … ContentConfig */ },
    footer: {
      subtitle: 'Last synced just now',
      layout: { titlePosition: 'center' },
    },
  },
};

For the full ZoneConfig shape, all ZoneLayout position options (with interactive configuration examples for every variant), icon, and themeOverrides, see Zone Config.

Content Zone

zones.content is the only required zone. It owns the data rendering pipeline — mode, field definitions, actions, pagination, search, grouping, sorting, filtering, gestures, loading/error states, and sizing.

const config = {
  zones: {
    content: {
      mode: 'table',
      item: {
        fields: [
          { key: 'name',   label: 'Name' },
          { key: 'status', label: 'Status', renderAs: 'badge' },
        ],
        layout: { type: 'auto' },
      },
    },
  },
};

For the full ContentConfig shape and all options, see Content Config.

Collapse

config.collapse controls whether the entire widget can be expanded and collapsed. The toggle button renders in the header zone — a header zone must be present for it to appear.

Widget starts collapsed. Click the toggle in the header to expand.

Team Directory

Click the toggle to expand

const config = {
  collapse: { initialState: 'collapsed', button: true },
  zones: {
    header: { title: 'Team Directory', subtitle: 'Click to expand' },
    content: { /* … */ },
    footer:  { subtitle: 'Last synced just now' },
  },
};

Option	Type	Default	Effect
initialState	'expanded' | 'collapsed' | 'fixed'	'expanded'	Starting state. 'fixed' disables the toggle entirely.
button	boolean	true	Show or hide the toggle button in the header zone.

When collapsed, the content zone and footer zone are hidden. The header zone remains visible.

Container Frame

containerFrame controls the visual shell around the entire widget — border, shadow, radius, and the optional outer chrome surface.

shell: 'none' + explicit border color and square corners — embeds Widgemo flush into a host surface.

Name	Status
Aurora Chen	active
Mateo Silva	pending
Priya Nair	inactive

config={{
  containerFrame: {
    shell: 'none',         // strip outer chrome background
    border: 'on',
    borderRadius: 'square',
    borderColor: '#6366f1',
    borderWidth: '2px',
    shadow: 'none',
    overflow: 'hidden',
  },
  zones: { content: { … } },
}}

ContainerFrame options

Option	Type	Default	Effect
shell	'on' | 'none'	'on'	Show or hide the outer chrome wrapper. When 'none', background is transparent and header/footer default to transparent too.
border	'on' | 'none'	'on'	Show or hide the outer border.
borderRadius	'square' | 'rounded' | number | string	theme default	Corner radius. 'square' forces 0; 'rounded' uses theme default.
shadow	'on' | 'none'	theme default	Box shadow on the outer shell.
borderColor	string	theme default	Explicit border color.
borderWidth	string | number	theme default	Explicit border width.
overflow	CSSProperties['overflow']	—	CSS overflow on the shell.

Shellless mode (shell: 'none')

When shell: 'none', the outer shell surface is disabled while zone internals continue to render normally:

• Outer background is transparent
• Border and shadow are removed
• Header and footer default to transparent backgrounds
• Outer radius defaults to 0 unless explicitly configured
• Outer overflow defaults to visible unless explicitly configured
• zones.content spacing remains mode-owned

Borderless vs shellless — when to use which

	Borderless (border: 'none', shadow: 'none')	Shellless (shell: 'none')
Outer card background	Present (uses theme background)	Transparent
Header/footer background	Present (theme/card surfaces)	Transparent by default
Border line	Removed	Removed
Outer radius default	Theme/card default	0 unless configured
Visual effect	Flat card, chrome stripped	Blends into host surface — no card boundary
Use when	Fits inside a panel but keeps its own background	Reads as part of the page, no card boundary

style

style applies inline CSS to the Widgemo root element, layered on top of Widgemo's computed styles. Use it for one-off positioning or sizing overrides that don't warrant a CSS class.

style: maxWidth + centred margin — constrains the widget width without adding a CSS class.

Centred widget

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

config={{ style: { maxWidth: 480, margin: '0 auto' }, zones: { … } }}

For scoped per-zone styling use zones.header.style / zones.footer.style in ZoneConfig. For class-based styling use the className prop on <Widgemo> — see Widgemo Props.

theme

theme sets a named theme registered via WidgemoThemeProvider or widgemoRegistry.registerWidgemoTheme. Built-in values are 'light' (default) and 'dark'.

config={{ theme: 'dark', zones: { … } }}

Theme tokens control the color palette, spacing, and surface appearance across the entire widget. Per-zone overrides use zones.header.themeOverrides / zones.footer.themeOverrides in ZoneConfig.

For the full token reference, registration API, and WidgemoThemeProvider, see Theme API.

interactions.onEvent

interactions.onEvent is the global interaction sink for all actions and gestures when no local handler is provided. It receives an InteractionContext for every action click, item gesture, and zone-action event across the whole widget.

const config = {
  interactions: {
    onEvent: (ctx) => {
      console.log(ctx.kind, ctx.interactionId, ctx.entity);
    },
  },
  zones: { content: { … } },
};

For the full InteractionContext shape and InteractionKind values, see Extension API — InteractionContext.

For per-gesture config (zones.content.gestures), handler flow, and examples, see Content Config — Gestures.

preRender

preRender is a config-level callback invoked synchronously before each render. Use it for lightweight side effects — analytics events, telemetry, or pre-flight state checks.

const config = {
  preRender: () => {
    analytics.track('widget.render');
  },
  zones: { content: { … } },
};

preRender does not receive arguments. It is separate from registry-based lifecycle hooks (registerWidgemoHook). For postRender, onItemClick, onModeChange, onDragDrop, and the decision guide on when to use each, see Extension API — Lifecycle Hooks.

devMode

devMode: true or devMode: { enabled: true } activates the dev inspector overlay — a collapsible panel showing the live serialised config. Useful during development.

For a walkthrough of the Inspector UI, button placement rules, the JSON tree, and the interaction notes panel, see DevMode.

// Shorthand
config={{ devMode: true, zones: { content: { … } } }}

// Full config
config={{
  devMode: {
    enabled: true,
    allowInProduction: false,    // must opt in to show in production builds
    zone: 'auto',                // 'header' | 'content' | 'footer' | 'floating' | 'auto'
    overlay: {
      showHeader: true,
      showDocsLink: 'https://your-docs.example.com',
      showBranding: true,
      excludeFields: ['zones.content.item.fields'],  // dot-path fields to omit
    },
  },
  zones: { content: { … } },
}}

Option	Type	Default	Effect
enabled	boolean	required	Activates the overlay.
allowInProduction	boolean	false	Must be explicitly true to render in production builds.
zone	'header' | 'content' | 'footer' | 'floating' | 'auto'	'auto'	Where to attach the inspector toggle icon. 'auto' uses the fallback hierarchy: header → footer → floating.
overlay.showHeader	boolean	true	Show the overlay header bar with copy button and docs link.
overlay.showDocsLink	string | false	unset	URL for the docs link in the overlay header. false hides it.
overlay.showBranding	boolean	true	Show the Widgemo branding footer in the overlay.
overlay.excludeFields	string[]	unset	Dot-path fields to omit from the JSON display (e.g. 'zones.content.item.fields').

See Also

• Widgemo Props — component props, loading/error/onRetry sugar props, exports
• Content Config — full ContentConfig reference: loading states, error states, pagination, search, grouping, gestures
• Action Config — action shape, placement, overflow
• Field Config — field types and renderAsOptions
• Extension API — custom renderers, modes, hooks, icons
• Theme API — WidgemoThemeProvider and theme registration