Skip to main content

Custom Field Types

A custom field type is a semantic extension.

Use it when a value should behave like a reusable first-class field category rather than a one-off visual formatting choice.

When to Use a Custom Field Type​

SituationPrefer custom field type?Why
A domain value should read naturally as type: '...'YesType conveys semantics in config
Multiple widgets should reuse the same field behaviorYesOne registration supports many configs
Only visual output changesNoUse custom renderAs instead
The layout strategy changes for the whole content areaNoUse a custom mode

Registration Contract​

registerWidgemoFieldType accepts a FieldTypeRegistryEntry:

FieldTypeDescription
namestringRegistry key referenced from item.fields[].type
render(value, config, entity) => ReactNodeField renderer
defaultConfigPartial<FieldConfig>Default field config
validate(value, config) => boolean | stringOptional validation hook

Register a custom field type​

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

widgemoRegistry.registerWidgemoFieldType({
  name: 'swatch',
  render: (value, config) => (
    <span
      title={String(value)}
      style={{
        display: 'inline-block',
        width: 18,
        height: 18,
        borderRadius: 3,
        backgroundColor: String(value),
        border: '1px solid #dee2e6',
        verticalAlign: 'middle',
      }}
    />
  ),
  defaultConfig: { type: 'swatch' },
});

// Use in fields:
{ key: 'brandColor', label: 'Color', type: 'swatch' }

Registration Order​

Register custom types before any Widgemo component renders. A safe place is module scope in your app entry file.

Best Practices​

  • Use namespaced names (acme.swatch, ops.health-band) to reduce collisions.
  • Keep defaultConfig minimal and only set defaults that should apply everywhere.
  • Prefer field types when the extension changes meaning as well as presentation.
  • Use validation when malformed values should be caught early.

Collision Behavior​

Collision semantics are defined in Extension API: Registration Collisions.

See Also​