Skip to main content

Field Config

FieldConfig defines how each field is rendered. Most options are cross-mode, while some are mode-specific, such as sortable, width, and align in table mode and span in grid layouts.

For host-level table CSS caveats (striping overrides, grouped-control contrast, and overflow behavior), see Host CSS and Table Layout.

The gallery below shows the built-in renderAs outputs documented on this page.

Renderer Gallery

A core-only visual reference for the built-in renderAs options on this page.

Renderer Gallery

Core renderAs options shown with live output

Name
Currency
Progress
Rating
Link
JSON
Delta
Status
Spark Trend
Health Score
Confidence Score
Composition
Date
Time
Datetime
Timestamp
Duration
Aurora Chen$184,250.00
86%
Open profile↗
"team": "Design"
"region": "EMEA"
UP +12.4%posted
+12.0%
Healthy92
96%High
01:01:01
Mateo Silva($5,210.00)
38%
Open profile↗
"team": "Platform"
"region": "NA"
DOWN -4.6%pending
-6.0%
Watch61
72%Good
00:15:15
Priya Nair$89,400.00
69%
Open profile↗
"team": "Operations"
"region": "APAC"
FLAT 0.0%watch
+2.0%
Watch48
58%Medium
00:02:52
item: {
  fields: [
    { key: 'name', label: 'Name' },
    {
      key: 'salary',
      label: 'Currency',
      renderAs: 'currency',
      renderAsOptions: {
        currency: 'USD',
        compact: true,
        colorize: true,
        negativeFormat: 'parentheses',
      },
    },
    {
      key: 'status',
      label: 'Status',
      renderAs: 'badge',
      renderAsOptions: {
        style: 'badge',
        size: 'sm',
      },
    },
    {
      key: 'settlementDate',
      label: 'Date',
      type: 'date',
      renderAs: 'date',
      renderAsOptions: {
        parseMode: 'iso-date',
        locale: 'en-US',
      },
    },
    {
      key: 'processingLatencySec',
      label: 'Duration',
      type: 'duration',
      renderAs: 'duration',
      renderAsOptions: {
        unit: 'sec',
        format: 'clock',
      },
    },
  ],
  layout: { type: 'auto' },
}
// Type-first baseline (semantic type only)
{ key: 'joinedAt', label: 'Joined', type: 'date' }

// renderAs override (visual renderer takes precedence)
{
  key: 'joinedAt',
  label: 'Joined',
  type: 'date',
  renderAs: 'badge',
  renderAsOptions: { style: 'soft' },
}

All built-in renderAs option objects also accept className from BaseRenderAsOptions.

FieldConfig Interface​

interface FieldConfig {
  key: string;                    // entity property key (required)
  label?: string;                 // display label
  type?: 'text' | 'number' | 'date' | 'time' | 'datetime' | 'timestamp' | 'duration' | 'boolean' | 'select' | 'relation' | 'textarea' | 'email' | 'url' | 'image' | 'swatch';
  sortable?: boolean;
  width?: number | string;        // table column width
  align?: 'left' | 'center' | 'right';
  showLabel?: boolean;            // show label next to value in card views
  wrap?: boolean;                 // true = wrap, false = truncate + tooltip (default)
  visible?: boolean;              // false = hide entirely
  condition?: (entity) => boolean; // per-row hide condition
  formatter?: (value, entity) => unknown; // transform raw value before rendering
  span?: number;                  // grid column span
  booleanTrueLabel?: string;
  booleanFalseLabel?: string;
  imageOptions?: { circular?, width?, height?, objectFit?, border?, shadow?,
    backgroundColor?, borderRadius?, lightbox?, lazy?, alt? };
  renderAs?: string;
  renderAsOptions?: RenderAsOptions;
}

Implementation Notes​

  • renderAs takes precedence over type.
  • Temporal contract: date, time, datetime, and timestamp require renderAsOptions.parseMode; duration requires renderAsOptions.unit.
  • booleanTrueLabel and booleanFalseLabel are applied only for type: 'boolean' fallback rendering.
  • formatter runs before type rendering. For domain-specific boolean wording or logic, prefer a formatter plus renderAs or type: 'text' instead of relying on boolean labels.
  • visible is currently enforced in table mode field filtering.
  • span applies to item layouts that use CSS grid field placement.

Built-in type Categories​

Use Components field-type pages for practical usage patterns:

Precedence reminder:

  • type expresses data semantics.
  • renderAs controls visual output when present.

Built-in renderAs Options​

Use the Components renderer pages for per-renderer usage guidance and examples:

Renderer Contract Notes​

  • renderAs takes precedence over type.
  • Temporal contract: date, time, datetime, and timestamp require renderAsOptions.parseMode; duration requires renderAsOptions.unit.
  • All built-in renderer option objects accept className from BaseRenderAsOptions.
  • RenderAsOptions in core types is the canonical option union, including custom renderer option support.

Item Layout​

ItemConfig.layout has moved to Item Config to keep this page focused on field-level schema and renderer contracts.

Use Field Rendering Reference for type vs renderAs guidance.

See Also​