Skip to main content

Item Config

ItemConfig defines how each entity is presented inside the active content mode.

zones.content.item is the bridge between:

  • field semantics and rendering (fields[], type, renderAs)
  • item composition (layout, template)
  • item-level styling behavior (style, conditionalBorder, conditionalBackgroundColor, wrap)

For field-level options and renderer catalogs, see Field Config.

For mode-specific controls (table/grid/carousel/board/chart), see Mode Config Reference.

For type vs renderAs resolution rules, see Field Rendering Reference.

ItemConfig Interface​

interface ItemConfig<T> {
  fields: FieldConfig[];
  layout?: ItemLayout;
  style?: React.CSSProperties | string;
  template?: ItemTemplate;
  conditionalBorder?: (entity: T) => { thickness?: number; color: string; placement?: 'left' | 'right' | 'top' | 'bottom' | 'all' } | null;
  cardOptions?: {
    border?: boolean;
    borderStyle?: string;
    borderWidth?: string;
    borderColor?: string;
    borderRadius?: string;
    backgroundColor?: string;
    boxShadow?: string;
    padding?: string;
  };
  conditionalBackgroundColor?: (entity: T) => string | { backgroundColor: string; color?: string } | undefined;
  wrap?: boolean;
  actionOverflow?: {
    maxInline?: number | { mobile: number; tablet: number; desktop: number };
    menuLabel?: string;
    menuTooltip?: string;
    indicator?: 'pulse' | 'scale' | 'color-shift' | 'none';
  };
}

SectionConfig Interface​

interface SectionConfig {
  title?: string;
  fields: string[];
  layout?: ItemLayout;
  className?: string;
}

Fields Relationship​

ItemConfig.fields is required and uses FieldConfig[].

item: {
  fields: [
    { key: 'name', label: 'Name', type: 'text' },
    { key: 'status', label: 'Status', renderAs: 'badge' },
    { key: 'joinedAt', label: 'Joined', type: 'date', renderAs: 'date', renderAsOptions: { parseMode: 'iso-date' } },
  ],
  layout: { type: 'auto' },
}

Item Layout​

ItemConfig.layout controls how fields are arranged within each item card.

  • In grid/board/carousel mode, item layout is applied directly to each rendered item.
  • In table mode, item layout applies when using rich-cell item rendering patterns (for example, section-based rich cells), not plain traditional cell rendering.

Interactive Configurations​

Auto​

Item Layout: Auto

Default field flow with no explicit flex/grid/section grouping.

Auto Layout

item.layout.type = auto

Name:Aurora Chen
Email:aurora@widgemo.dev
Role:Design Lead
Department:Design Systems
Status:active
Name:Mateo Silva
Email:mateo@widgemo.dev
Role:Platform Engineer
Department:Core Platform
Status:pending
item: {
  fields: [
    { key: 'name', label: 'Name' },
    { key: 'email', label: 'Email', type: 'email' },
    { key: 'role', label: 'Role', renderAs: 'badge' },
    { key: 'department', label: 'Department' },
    { key: 'status', label: 'Status', renderAs: 'badge' },
  ],
  layout: { type: 'auto' },
}

Flex​

Item Layout: Flex

Single-row alignment with avatar, identity, and status fields.

Flex Layout

item.layout.type = flex (direction: row)

Avatar
Aurora Chen
Lead
active
Design Ops
Avatar
Mateo Silva
Platform
pending
Core Platform
item: {
  fields: [
    { key: 'avatar', label: 'Avatar', type: 'image', showLabel: false, width: 48,
      imageOptions: { circular: true, width: 48, height: 48 } },
    { key: 'name', label: 'Name', showLabel: false, width: '8.5rem', wrap: false },
    { key: 'role', label: 'Role', renderAs: 'badge', showLabel: false, width: '6rem', wrap: false },
    { key: 'status', label: 'Status', renderAs: 'badge', showLabel: false, width: '5.5rem', wrap: false },
    { key: 'department', label: 'Dept', showLabel: false, width: '9rem' },
  ],
  layout: {
    type: 'flex',
    flex: {
      direction: 'row',
      wrap: true,
      justify: 'flex-start',
      align: 'center',
    },
  },
}

CSS Grid with Template Areas​

Item Layout: Grid Areas

Area tokens map directly to field keys; repeated area names create spanning fields.

Grid Areas Layout

item.layout.type = grid with named areas

Avatar
Aurora Chen
aurora@wg.dev
Design Lead
Design Systems
Avatar
Mateo Silva
mateo@wg.dev
Platform Engineer
Core Platform

How grid.areas maps to rendered fields:

  • Each token in areas must match a field key exactly.
  • A field is rendered once per item; repeating the same token in multiple cells makes that one field span those cells.
  • If a field key is not present in areas, the browser auto-places that field in the grid flow.
  • If an areas token has no matching field key, that named area remains empty.
item: {
  fields: [
    { key: 'avatar', label: 'Avatar', type: 'image', showLabel: false,
      imageOptions: { circular: true, width: 56, height: 56 } },
    { key: 'name', label: 'Name', showLabel: false, wrap: false },
    { key: 'email', label: 'Email', type: 'email', showLabel: false, wrap: false },
    { key: 'role', label: 'Role', renderAs: 'badge', showLabel: false, wrap: false },
    { key: 'department', label: 'Dept', showLabel: false, wrap: false },
  ],
  layout: {
    type: 'grid',
    grid: {
      columns: '56px minmax(10rem, 1.35fr) minmax(8rem, 1fr)',
      gap: '0.75rem 1rem',
      areas: [
        '"avatar name role"',
        '"avatar email department"',
      ],
    },
  },
}

Sections​

Item Layout: Sections

Fields grouped into titled sections for structured card content.

Sections Layout

item.layout.type = sections

1. Contact

Name:Aurora Chen
Email:aurora@wg.dev

2. Role & Team

Role:Design Lead
Department:Design Systems

3. Metrics

Status:active
Progress:
91%

1. Contact

Name:Mateo Silva
Email:mateo@wg.dev

2. Role & Team

Role:Platform Engineer
Department:Core Platform

3. Metrics

Status:pending
Progress:
76%

Section-level visual differentiation is supported through SectionConfig.className. Apply classes per section, then style backgrounds, outlines, and spacing in your app or docs CSS.

item: {
  cardOptions: {
    backgroundColor: '#1f2430',
    borderColor: '#3b4252',
    borderRadius: '10px',
    padding: '14px',
  },
  fields: [
    { key: 'name', label: 'Name' },
    { key: 'email', label: 'Email', type: 'email' },
    { key: 'role', label: 'Role', renderAs: 'badge' },
    { key: 'department', label: 'Department' },
    { key: 'status', label: 'Status', renderAs: 'badge' },
    { key: 'progress', label: 'Progress', renderAs: 'progress' },
  ],
  layout: {
    type: 'sections',
    sections: [
      {
        title: '1. Contact',
        className: 'wg-item-section wg-item-section--contact',
        fields: ['name', 'email'],
        layout: { type: 'grid', grid: { columns: '1fr', gap: '0.35rem' } },
      },
      {
        title: '2. Role & Team',
        className: 'wg-item-section wg-item-section--team',
        fields: ['role', 'department'],
        layout: { type: 'grid', grid: { columns: '1fr', gap: '0.35rem' } },
      },
      {
        title: '3. Metrics',
        className: 'wg-item-section wg-item-section--metrics',
        fields: ['status', 'progress'],
        layout: { type: 'grid', grid: { columns: '1fr', gap: '0.35rem' } },
      },
    ],
  },
}
.wg-item-section {
  border: 1px solid var(--ifm-border-color);
  border-radius: 8px;
  padding: 0.6rem;
}

.wg-item-section--contact {
  background: rgba(45, 212, 191, 0.14);
}

.wg-item-section--team {
  background: rgba(34, 197, 94, 0.12);
}

.wg-item-section--metrics {
  background: rgba(245, 158, 11, 0.12);
}

See Also​