Content Config

ContentConfig is the canonical content contract inside zones.content.

Shape

Field	Type	Default	Description
`mode`	`'table' \| 'grid' \| 'carousel' \| 'board' \| 'chart' \| string`	—	Required. Display mode
`enabled`	`boolean`	`true`	Toggles the content zone on or off
`layout`	`ModeLayout`	—	Reserved; mode-specific settings live in `modeConfig`
`item`	`ItemConfig`	—	Required. Field definitions and card layout
`modeConfig`	`ModeConfig`	—	Mode-specific config (`table`, `grid`, `carousel`, `board`, `chart`)
`actions`	`ActionConfig[]`	—	Per-item actions
`actionOverflow`	`ActionOverflowConfig`	—	Overflow menu behaviour for item actions
`theme`	`string`	—	Registered theme name for content-zone styling
`themeOverrides`	`Partial<ZoneTheme>`	—	Zone-scoped theme token overrides
`groupings`	`GroupingConfig[]`	—	Row/card groupings
`sorting`	`SortConfig[]`	—	Initial sort
`filtering`	`StaticFilterRule[]`	—	Static filters (valid operators: `eq`, `ne`, `contains`, `startswith`, `gt`, `lt`)
`search`	`{ enabled?, placeholder?, fields?, debounceMs?, onSearch? }`	—	Search bar
`pagination`	`{ pageSize, initialPage?, onPageChange? }`	—	Pagination settings
`responsive`	`{ breakpoints: Record<string, { mode?, modeConfig? }> }`	—	Per-breakpoint mode and config overrides
`sizing`	`{ mode?: 'auto' \| 'fixed' \| 'fill'; height?: number \| string }`	—	Content sizing
`status`	`'idle' \| 'loading' \| 'success' \| 'error'`	—	Content state
`error`	`unknown`	—	Error payload used with `status: 'error'`
`loadingState`	`LoadingStateConfig`	—	Loading UI options
`errorState`	`ErrorStateConfig`	—	Error UI options
`style`	`CSSProperties`	—	Inline styles on the content zone
`gestures`	`GestureConfig[]`	—	Click and drop gestures

`mode`

mode is required. It selects which renderer Widgemo uses to display your data.

Built-in values: 'table', 'grid', 'carousel', 'board', 'chart'.

Custom string values are also accepted when a matching renderer is registered via the extension API.

zones: {
  content: {
    mode: 'table',
    item: { fields: […], layout: { type: 'auto' } },
  },
},

For mode-specific behaviour, layouts, and interactive configuration examples see: Table · Grid · Carousel · Board · Chart

`item`

item is required. It defines the field list and the card/row layout used by all modes.

item: {
  fields: [
    { key: 'name',   label: 'Name' },
    { key: 'status', label: 'Status', renderAs: 'badge' },
    { key: 'joined', label: 'Joined',  type: 'date' },
  ],
  layout: { type: 'auto' },
},

For the full ItemConfig shape (including item layout contracts), see Item Config.

For FieldConfig details — field types, renderAs keys, options lookup, visibility conditions, and custom field renderer links — see Field Config.

For type vs renderAs guidance, see Field Rendering Reference.

`modeConfig`

modeConfig holds mode-specific display settings that go beyond the shared item contract. Not all modes use every sub-key — each mode reads only its own namespace.

content: {
  mode: 'grid',
  modeConfig: {
    grid: { columns: 3, gap: '1rem' },
  },
  item: { fields: […], layout: { type: 'auto' } },
},

For the full modeConfig shape and all sub-keys for each mode see the reference pages: Table Mode Config · Grid Mode Config · Carousel Mode Config · Board Mode Config · Chart Mode Config

Actions

All action and gesture callbacks route through interactions.onEvent:

const config = {
  interactions: {
    onEvent: (ctx) => {
      console.log(ctx.kind, ctx.interactionId, ctx.entity);
    },
  },
  zones: {
    content: {
      mode: 'table',
      actions: [
        { id: 'edit',   label: 'Edit',   icon: 'edit',   placement: 'pinned', variant: 'secondary' },
        { id: 'delete', label: 'Delete', icon: 'delete', placement: 'menu',   variant: 'danger',
          visibleIf: (entity) => entity.status === 'inactive' },
      ],
      item: { fields: […], layout: { type: 'auto' } },
    },
  },
};

onAction on individual ActionConfig objects is also supported as a local override — it takes precedence over interactions.onEvent for that action.

actionOverflow applies to both zone configs and ContentConfig. For full options, behavior, and indicator values, see Action Config — Action Overflow.

`theme`, `themeOverrides`, and `style`

theme accepts a registered theme name and applies it to the content zone.

themeOverrides accepts a Partial<ZoneTheme> object for inline token overrides scoped to this zone — useful when you need a different background, title colour, or padding without introducing a new named theme.

style accepts a CSSProperties object and applies inline styles directly to the content zone wrapper element.

content: {
  mode: 'table',
  theme: 'compact',
  themeOverrides: {
    backgroundColor: '#f8f9fa',
    padding: '0.5rem',
  },
  style: { borderTop: '2px solid #6366f1' },
  item: { fields: […], layout: { type: 'auto' } },
},

For the full ZoneTheme token list and theming precedence rules, see Theming and Theme API.

Grouping

groupings is the canonical grouping contract under zones.content, independent from mode-specific presentation controls.

GroupingConfig shape:

Field	Type	Default	Description
`fieldKey`	`string`	required	Data field used to build group buckets.
`initiallyCollapsed`	`boolean`	`false`	Starts every group collapsed when true.
`collapsible`	`boolean`	`true`	Enables user expand/collapse interactions for groups.
`renderer`	`(groupValue, count, isCollapsed) => ReactNode`	unset	Custom group header label renderer.
`showDropdownControl`	`boolean`	`false`	Table-only: shows the Group by dropdown control.
`showHeaderControls`	`boolean`	`true`	Table-only: shows grouping controls in table headers.
`aggregates`	`Record<string, AggregateType>`	unset	Table-only: aggregate chips in grouped table headers.

Mode applicability:

Grouping field	Table mode	Non-table modes
`fieldKey`	supported	supported
`initiallyCollapsed`	supported	supported
`collapsible`	supported	supported
`renderer`	supported	supported
`showDropdownControl`	supported	ignored
`showHeaderControls`	supported	ignored
`aggregates`	supported	ignored

For table-specific grouping control UX and live variants (dropdown-only, header-icons-only, both), see Table Mode: Grouping UI Controls.

content: {
  mode: 'table',
  groupings: [
    {
      fieldKey: 'department',
      initiallyCollapsed: false,
      showDropdownControl: true,
      showHeaderControls: true,
      renderer: (groupValue, count, isCollapsed) =>
        `${groupValue} — ${count} members ${isCollapsed ? '▶' : '▼'}`,
    },
  ],
  item: { fields: […], layout: { type: 'auto' } },
},

For grouped table header styling and host-CSS caveats, see Host CSS and Table Layout.

Static Filtering and Sorting

content: {
  mode: 'table',
  filtering: [{ fieldKey: 'status', operator: 'eq', value: 'active' }],
  sorting:   [{ fieldKey: 'name',   direction: 'asc' }],
  item: { fields: […], layout: { type: 'auto' } },
},

Pagination and Search

content: {
  mode: 'table',
  search: { placeholder: 'Search…', fields: ['name', 'department'] },
  pagination: { pageSize: 5, initialPage: 1 },
  item: { fields: […], layout: { type: 'auto' } },
},

Search filters the full dataset first; pagination slices the filtered results. Page resets to 1 on each new query.

search.onSearch is called with the current query after each debounce — useful for server-side search where you want to re-fetch data based on the query string.

`responsive`

responsive.breakpoints maps breakpoint keys to per-breakpoint mode and modeConfig overrides. The breakpoint key is any string that matches a registered breakpoint name (e.g. 'mobile', 'tablet').

content: {
  mode: 'table',
  responsive: {
    breakpoints: {
      mobile: {
        mode: 'grid',
        modeConfig: { grid: { columns: 1 } },
      },
    },
  },
  item: { fields: […], layout: { type: 'auto' } },
},

For the full breakpoint system, available keys, and container-query behaviour, see Responsive Mode Switching.

`sizing`

sizing controls how the content zone determines its height.

Option	Type	Default	Effect
`mode`	`'auto' \| 'fixed' \| 'fill'`	`'auto'`	`auto`: grows with content. `fixed`: uses explicit `height`. `fill`: stretches to 100% of parent height.
`height`	`number \| string`	—	Used when `mode` is `'fixed'`. Numbers are treated as `px`.

content: {
  mode: 'table',
  sizing: { mode: 'fixed', height: 400 },
  item: { fields: […], layout: { type: 'auto' } },
},

Loading States

Set status: 'loading' to activate the built-in loading UI. Three patterns are available — spinner, skeleton, and text — plus a full custom renderer override.

content: {
  status: 'loading',
  loadingState: { indicator: 'spinner', message: 'Fetching data…' },
  mode: 'table',
  item: { … },
},

For all loadingState options, skeleton variants, and the custom renderer API, see Loading State.

Error States

Set status: 'error' to activate the built-in error UI. Three severity styles — error, warning, info — are available with optional retry support.

content: {
  status: 'error',
  error: thrownError,
  errorState: {
    message: 'Failed to load team data.',
    severity: 'error',
    retry: { label: 'Try again', onRetry: refetch },
  },
  mode: 'table',
  item: { … },
},

For severity variants, retry wiring, and the custom renderer API, see Error State.

Gestures

zones.content.gestures defines config-driven user interaction handlers for item events.

Supported types:

item-click — fires when a user clicks a row, card, or selectable item
item-drag-start — fires when a drag begins on a board card
item-drop — fires when a board card is dropped onto a target

Gesture Types

Type	Typical Source	Payload Intent	Handler location
`item-click`	Table rows, cards	User selection or activation	`onTrigger` on the gesture entry, else `interactions.onEvent`
`item-drag-start`	Board cards	Drag initiation details	`onTrigger` on the gesture entry, else `interactions.onEvent`
`item-drop`	Board drop targets	Drop/completion details	`onTrigger` on the gesture entry, else `interactions.onEvent`

Handler Flow

If the matching gesture entry defines onTrigger, Widgemo calls that handler first.
If onTrigger is not provided, Widgemo falls back to interactions.onEvent.
If neither is provided, Widgemo does not run an app-level handler for that event.

const config = {
  interactions: {
    onEvent: (ctx) => {
      // fallback for any event without a local onTrigger
      console.log(ctx.kind, ctx.entity?.id);
    },
  },
  zones: {
    content: {
      mode: 'board',
      gestures: [
        {
          type: 'item-click',
          interactionId: 'open-item',
          interactionLabel: 'Open item',
          onTrigger: (ctx) => {
            openItem(ctx.entity?.id);
          },
        },
        {
          type: 'item-drag-start',
          interactionId: 'move-start',
          interactionLabel: 'Start move',
          // no onTrigger — falls through to interactions.onEvent
        },
        {
          type: 'item-drop',
          interactionId: 'move-drop',
          interactionLabel: 'Finish move',
        },
      ],
      item: { fields: [{ key: 'name' }], layout: { type: 'auto' } },
    },
  },
};

interactions.onEvent is a top-level WidgemoConfig field — see Widgemo Config — interactions.onEvent.

For the full InteractionContext shape, InteractionKind values, and the decision guide on gestures vs lifecycle hooks, see Extension API.

Shape​

mode​

item​

modeConfig​

Actions​

theme, themeOverrides, and style​

Grouping​

Static Filtering and Sorting​

Pagination and Search​

responsive​

sizing​

Loading States​

Error States​

Gestures​

Gesture Types​

Handler Flow​

See Also​