Skip to main content

Action Config

Actions can be defined at zone-level (header/footer) and content-level (per-item).

ActionConfig Interface​

interface ActionConfig<T = unknown> {
  id: string;
  label: string;
  icon?: string;
  variant?: string;
  placement?: 'pinned' | 'onHover' | 'menu';
  visibleIf?: (entity: T) => boolean;
  onAction?: InteractionEventHandler;
}

Interactive Configurations​

Zone Actions​

Header and Footer Actions

Header and footer actions with pinned and menu placements.

Team Directory

Pinned and menu placements in header and footer zones

Name
Role
Status
Aurora ChenDesign Leadactive
Mateo SilvaPlatform Engineerpending
zones: {
  header: {
    actions: [
      { id: 'add-user', label: 'Add User', icon: 'add', placement: 'pinned', variant: 'primary' },
      { id: 'export-csv', label: 'Export', icon: 'download', placement: 'menu' },
    ],
  },
  footer: {
    actions: [{ id: 'settings', label: 'Settings', icon: 'settings', placement: 'menu' }],
  },
}

Per-Item Actions​

Item Actions with Overflow

Mixed action placements with overflow behavior and conditional visibility.

Action Overflow
Name
Status
Priority
Aurora Chenactivehigh
Mateo Silvainactivemedium
Priya Nairpendinglow
content: {
  mode: 'table',
  actions: [
    { id: 'edit', label: 'Edit', icon: 'edit', placement: 'pinned', variant: 'secondary' },
    { id: 'view', label: 'View', icon: 'view', placement: 'onHover' },
    {
      id: 'delete',
      label: 'Delete',
      icon: 'delete',
      placement: 'menu',
      variant: 'danger',
      visibleIf: (entity) => entity.status === 'inactive',
    },
  ],
  actionOverflow: {
    maxInline: { mobile: 1, tablet: 2, desktop: 3 },
    menuLabel: 'More',
    menuTooltip: 'More actions',
    indicator: 'pulse',
  },
  item: { fields: [{ key: 'name' }, { key: 'status' }], layout: { type: 'auto' } },
}

Action Context Notes​

ctx.entity is set for item actions; ctx.data and ctx.zone are set for zone actions.

ActionConfig Properties​

PropertyTypeDescription
idstringStable action identifier (used in ctx.interactionId)
labelstringButton label
iconstringIcon name (built-in or registered)
variantstringVisual variant. Common values in built-in examples include primary, secondary, danger, and ghost.
placement'pinned' | 'onHover' | 'menu'Where the action appears
visibleIf(entity) => booleanConditional visibility per item
onAction(ctx) => voidLocal override (takes precedence over interactions.onEvent)

Action Overflow​

actionOverflow: {
  maxInline: { mobile: 1, tablet: 2, desktop: 3 },
  menuLabel: 'More',
  menuTooltip: 'More actions',
  indicator: 'pulse',  // 'pulse' | 'scale' | 'color-shift' | 'none'
},

actionOverflow is available on both zone configs and ContentConfig.

Controls how zone and item actions behave when there are more actions than can fit inline. The overflow button (⋯) appears automatically when actions are tucked into a menu. When the overflow count increases (for example, after a container resize), the button plays an attention animation defined by indicator.

indicator values​

ValueEffect
'pulse'Scale pop + blue radial ripple. Default.
'scale'Clean scale-only pop with no color change.
'color-shift'Brief background and border tint flash toward the primary color with no movement.
'none'Animation disabled entirely.

The animation fires only when the overflow count increases, not on initial mount.

Reusable action presets​

Widgemo ships coreActions presets you can spread into your own action objects. Define only what is unique (id, label, placement, handlers), and inherit common preset fields (icon, default variant, and default visibility).

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

actions: [
  { ...coreActions.edit, id: 'edit-user', label: 'Edit User', placement: 'pinned' },
  { ...coreActions.view, id: 'view-profile', label: 'View Profile', placement: 'onHover' },
  { ...coreActions.delete, id: 'delete-user', label: 'Delete User', placement: 'menu' },
]

For multiple widgemos, define shared host defaults once, then apply per-widget overrides:

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

const HOST_ACTIONS = {
  edit: { ...coreActions.edit, placement: 'pinned' as const },
  view: { ...coreActions.view, placement: 'onHover' as const },
  remove: { ...coreActions.delete, placement: 'menu' as const, variant: 'danger' as const },
};

const makeHostAction = (
  type: keyof typeof HOST_ACTIONS,
  overrides: Partial<typeof HOST_ACTIONS.edit> = {},
) => ({
  ...HOST_ACTIONS[type],
  ...overrides,
});

actions: [
  makeHostAction('edit', { id: 'edit-user', label: 'Edit User' }),
  makeHostAction('view', { id: 'view-profile', label: 'View Profile' }),
  makeHostAction('remove', { id: 'delete-user', label: 'Delete User' }),
]

Preset Configuration​

Core Action Presets

Uses coreActions plus host-side spread overrides.

Preset-backed Actions

coreActions spread + local overrides

Name
Status
Priority
Aurora Chenactivehigh
Mateo Silvainactivemedium
Priya Nairpendinglow
import { coreActions } from '@widgemo/widgemo-core';

const config = {
  zones: {
    header: {
      title: 'Team Directory',
      actions: [
        { ...coreActions.add, id: 'add-user', label: 'Add User', placement: 'pinned', variant: 'primary' },
        { ...coreActions.refresh, id: 'sync-users', label: 'Sync', placement: 'pinned', variant: 'secondary' },
        { ...coreActions.export, id: 'export-users', label: 'Export Users', placement: 'menu' },
      ],
    },
    content: {
      mode: 'table',
      item: { fields: [{ key: 'name', label: 'Name' }, { key: 'status', label: 'Status' }], layout: { type: 'auto' } },
      actions: [
        { ...coreActions.edit, id: 'edit-user', label: 'Edit User', placement: 'pinned' },
        { ...coreActions.view, id: 'view-profile', label: 'View Profile', placement: 'onHover' },
        {
          ...coreActions.delete,
          id: 'delete-user',
          label: 'Delete User',
          placement: 'menu',
          variant: 'danger',
          visibleIf: (entity) => entity.status === 'inactive',
        },
      ],
      actionOverflow: { maxInline: { mobile: 1, tablet: 2, desktop: 2 }, menuLabel: 'More', indicator: 'pulse' },
    },
  },
};

coreActions​

Built-in action presets for common operations. Use them directly as ActionConfig entries or spread them to override fields:

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

// Use a preset directly
actions: [coreActions.view, coreActions.export]

// Override a field on a preset
actions: [{ ...coreActions.export, label: 'Export Users', placement: 'pinned' }]

Built-in presets: add, refresh, viewToggle, export, import, settings, view, edit, delete, filter, sort, search.

See Also​