Field Widgets Reference

Form input widgets for entity fields in the Layout Designer

Overview

Field widgets are the individual form inputs that render entity fields in the editor. Each widget handles a specific data type — from simple text inputs to color palette pickers, vector inputs, and media asset selectors.

There are two ways to control which widget renders a field:

field_config in templates — Template authors declare the widget and its options in YAML frontmatter
Layout Designer — Users drag fields and configure widget types visually

When the system determines which widget to use for a field, it checks in this order:

Custom layout — Widget type set in the Layout Designer (highest priority)
field_config — Widget declared in the template’s field_config section
Pattern inference — Field names ending in _color → color-picker, etc.
Type inference — Schema type → default widget (string → text, boolean → checkbox)

Widgets vs Component Blocks

	Field Widgets	Component Blocks
What	Form inputs for a single field	Self-contained layout sections
Examples	text, color-picker, entity-selector	Asset Browser, AI Chat, Timeline
Data	Read/write one field value	Read full entity data
Placement	Inside a section, alongside other fields	ARE a section (full width)

field_config Reference

Add field_config to your template’s YAML frontmatter to declare widgets:

field_config:
  field_name:
    widget: widget-name
    # ... widget-specific options

field_config is template metadata — it’s never stored in entity data. The selected values ARE stored in entity data.

Text & Content

text

Single-line text input.

Category: text

Option	Type	Default	Description
`placeholder`	string	—	Placeholder text shown when empty
`max_length`	number	—	Maximum character count

Value format: string

Example:

field_config:
  title:
    widget: text
    placeholder: "Enter a title..."
    max_length: 120

textarea

Multi-line text input.

Category: text

Option	Type	Default	Description
`placeholder`	string	—	Placeholder text shown when empty
`rows`	number	—	Visible row height of the textarea
`max_length`	number	—	Maximum character count

Value format: string

Example:

field_config:
  summary:
    widget: textarea
    placeholder: "Write a short summary..."
    rows: 4

rich-text

Markdown/rich text editor with toolbar.

Category: text

Option	Type	Default	Description
`toolbar`	string[]	—	Toolbar button IDs to display (e.g. `bold`, `italic`, `link`, `heading`)

Value format: string (HTML or markdown depending on editor mode)

Example:

field_config:
  description:
    widget: rich-text
    toolbar:
      - bold
      - italic
      - link
      - heading
      - bullet-list

code

Code editor with syntax highlighting and a language badge.

Category: text

Option	Type	Default	Description
`language`	string	—	Syntax language (`json`, `lua`, `yaml`, `glsl`, etc.)
`rows`	number	—	Visible row height of the editor

Value format: string

Example:

field_config:
  shader_source:
    widget: code
    language: glsl
    rows: 20

read-only

Display-only text field that cannot be edited.

Category: text

Option	Type	Default	Description
`help`	string	—	Helper text shown below the value

Value format: string (not editable through this widget)

Example:

field_config:
  generated_id:
    widget: read-only
    help: "Auto-assigned by the system"

url

URL input with format validation and an external link button.

Category: text

Option	Type	Default	Description
`placeholder`	string	—	Placeholder text shown when empty
`protocols`	string[]	`["https", "http"]`	Allowed URL protocols

Value format: string

Example:

field_config:
  website:
    widget: url
    placeholder: "https://example.com"
    protocols:
      - https

email

Email input with format validation.

Category: text

Option	Type	Default	Description
`placeholder`	string	—	Placeholder text shown when empty

Value format: string

Example:

field_config:
  contact_email:
    widget: email
    placeholder: "name@domain.com"

slug

Auto-slugified text input that produces lowercase, underscore-separated identifiers.

Category: text

Option	Type	Default	Description
`source_field`	string	—	Field name to derive the slug from automatically

Value format: string (lowercase, underscores, no spaces)

Example:

field_config:
  entity_key:
    widget: slug
    source_field: title

Numbers & Ranges

number

Integer or float number input.

Category: number

Option	Type	Default	Description
`min`	number	—	Minimum allowed value
`max`	number	—	Maximum allowed value
`step`	number	—	Increment step

Value format: number

Example:

field_config:
  hit_points:
    widget: number
    min: 0
    max: 9999
    step: 1

range

Slider input for selecting a value within a range.

Category: number

Option	Type	Default	Description
`min`	number	`0`	Minimum value
`max`	number	`100`	Maximum value
`step`	number	`1`	Slider increment
`show_value`	boolean	`true`	Show the current numeric value beside the slider

Value format: number

Example:

field_config:
  volume:
    widget: range
    min: 0
    max: 1
    step: 0.01
    show_value: true

rating

Star or point rating input.

Category: number

Option	Type	Default	Description
`max`	number	`5`	Maximum rating value
`icon`	string	`star`	Icon shape (`star`, `heart`, `circle`)

Value format: number (0 to max)

Example:

field_config:
  threat_level:
    widget: rating
    max: 5
    icon: star

vector2

2D vector input with labeled X and Y fields.

Category: number

Option	Type	Default	Description
`min`	number	—	Minimum value for both axes
`max`	number	—	Maximum value for both axes
`step`	number	—	Increment step for both axes
`labels`	string[]	`["X", "Y"]`	Labels for each axis input

Value format: [number, number]

Example:

field_config:
  spawn_position:
    widget: vector2
    labels: ["Longitude", "Latitude"]

vector3

3D vector input with labeled X, Y, and Z fields.

Category: number

Option	Type	Default	Description
`min`	number	—	Minimum value for all axes
`max`	number	—	Maximum value for all axes
`step`	number	—	Increment step for all axes
`labels`	string[]	`["X", "Y", "Z"]`	Labels for each axis input

Value format: [number, number, number]

Example:

field_config:
  world_position:
    widget: vector3
    step: 0.1
    labels: ["X", "Y", "Z"]

angle

Rotation input combining a dial, slider, and number field.

Category: number

Option	Type	Default	Description
`min`	number	`0`	Minimum angle value
`max`	number	`360`	Maximum angle value
`step`	number	—	Increment step
`unit`	string	`deg`	Unit display (`deg` or `rad`)

Value format: number

Example:

field_config:
  rotation:
    widget: angle
    min: 0
    max: 360
    unit: deg

duration

Time duration input.

Category: number

Option	Type	Default	Description
`format`	string	`hms`	Display format (`hms`, `frames`, `seconds`)
`fps`	number	`24`	Frames-per-second, used when `format` is `frames`

Value format: number (stored as seconds)

Example:

field_config:
  clip_length:
    widget: duration
    format: frames
    fps: 30

Selection

select

Single-value dropdown selector.

Category: selection

Option	Type	Default	Description
`options`	`{value, label}[]`	—	The list of selectable options

Value format: string

Example:

field_config:
  rarity:
    widget: select
    options:
      - value: common
        label: Common
      - value: uncommon
        label: Uncommon
      - value: rare
        label: Rare
      - value: legendary
        label: Legendary

multi-select

Multi-choice chip selector from a constrained option set.

Category: selection

Option	Type	Default	Description
`options`	`{value, label}[]`	—	The list of selectable options
`max_selections`	number	—	Maximum number of selections allowed

Value format: string[]

Example:

field_config:
  genres:
    widget: multi-select
    max_selections: 3
    options:
      - value: action
        label: Action
      - value: rpg
        label: RPG
      - value: strategy
        label: Strategy

checkbox

Boolean toggle rendered as a checkbox.

Category: selection

Option	Type	Default	Description
—	—	—	No configuration options

Value format: boolean

Example:

field_config:
  is_active:
    widget: checkbox

checkbox-group

Multiple named boolean checkboxes rendered as a group.

Category: selection

Option	Type	Default	Description
`sub_fields`	`{key, label}[]`	—	List of named boolean sub-fields

Value format: { [key]: boolean }

Example:

field_config:
  abilities:
    widget: checkbox-group
    sub_fields:
      - key: can_fly
        label: Can Fly
      - key: can_swim
        label: Can Swim
      - key: can_climb
        label: Can Climb

radio-group

Single-choice selector with all options visible simultaneously.

Category: selection

Option	Type	Default	Description
`options`	`{value, label}[]`	—	The list of selectable options
`layout`	string	`vertical`	Arrangement of options (`horizontal` or `vertical`)

Value format: string

Example:

field_config:
  alignment:
    widget: radio-group
    layout: horizontal
    options:
      - value: lawful
        label: Lawful
      - value: neutral
        label: Neutral
      - value: chaotic
        label: Chaotic

toggle

Styled boolean switch with optional on/off labels.

Category: selection

Option	Type	Default	Description
`on_label`	string	—	Label shown when the toggle is on
`off_label`	string	—	Label shown when the toggle is off

Value format: boolean

Example:

field_config:
  is_published:
    widget: toggle
    on_label: Published
    off_label: Draft

icon-picker

Emoji or icon grid picker with search.

Category: selection

Option	Type	Default	Description
`library`	string	`lucide`	Icon set to use (`lucide`, `emoji`, or `custom`)
`options`	string[]	—	Custom icon identifiers when `library` is `custom`

Value format: string (icon name or emoji character)

Example:

field_config:
  entity_icon:
    widget: icon-picker
    library: emoji

Date & Time

date

Date picker input.

Category: date

Option	Type	Default	Description
`min`	string	—	Minimum selectable date (ISO format)
`max`	string	—	Maximum selectable date (ISO format)

Value format: string (ISO date: YYYY-MM-DD)

Example:

field_config:
  release_date:
    widget: date
    min: "2000-01-01"

datetime

Combined date and time picker.

Category: date

Option	Type	Default	Description
`min`	string	—	Minimum selectable datetime (ISO format)
`max`	string	—	Maximum selectable datetime (ISO format)
`timezone`	string	—	IANA timezone identifier (e.g. `America/Chicago`)

Value format: string (ISO datetime: YYYY-MM-DDTHH:MM:SS)

Example:

field_config:
  scheduled_at:
    widget: datetime
    timezone: America/New_York

time

Time-only picker.

Category: date

Option	Type	Default	Description
`min`	string	—	Earliest selectable time (`HH:MM`)
`max`	string	—	Latest selectable time (`HH:MM`)
`step`	number	—	Minute increment for the picker

Value format: string (HH:MM)

Example:

field_config:
  start_time:
    widget: time
    min: "08:00"
    max: "22:00"
    step: 15

year

Year-only number picker.

Category: date

Option	Type	Default	Description
`min`	number	—	Minimum year
`max`	number	—	Maximum year

Value format: number

Example:

field_config:
  founding_year:
    widget: year
    min: 1800
    max: 2100

date-range

Start and end date pair picker.

Category: date

Option	Type	Default	Description
`min`	string	—	Minimum selectable date for either bound
`max`	string	—	Maximum selectable date for either bound

Value format: { start: string, end: string } (ISO dates)

Example:

field_config:
  campaign_window:
    widget: date-range
    min: "2024-01-01"
    max: "2030-12-31"

Color

color-picker

Free-form hex color input with swatch preview.

Category: color

Option	Type	Default	Description
—	—	—	No configuration options

Value format: string (#RRGGBB)

Example:

field_config:
  primary_color:
    widget: color-picker

color-palette

Pick from a template-defined set of named color options. Supports compound swatches for skin tones or palette families.

Category: color

Option	Type	Default	Description
`options`	object[]	—	Array of color entries. Simple: `{label, hex}`. Compound: `{label, base, midtone, shadow, highlight}`
`multi_swatch`	boolean	`false`	Enable compound swatch display for palette families

Value format:

Simple: { name: string, hex: string }
Compound: { palette: string, base: string, midtone: string, shadow: string, highlight: string }

Example:

field_config:
  skin_tone:
    widget: color-palette
    multi_swatch: true
    options:
      - label: Fair
        base: "#f5d5b8"
        midtone: "#e8b89a"
        shadow: "#c8926a"
        highlight: "#fde8d4"
      - label: Medium
        base: "#c68642"
        midtone: "#a0522d"
        shadow: "#7a3b1e"
        highlight: "#d4a574"

color-group

Named group of free-form color pickers.

Category: color

Option	Type	Default	Description
`sub_fields`	`{key, label}[]`	`primary`, `secondary`, `accent`	Named color pickers within the group

Value format: { [key]: string } (each value is #RRGGBB)

Example:

field_config:
  brand_colors:
    widget: color-group
    sub_fields:
      - key: primary
        label: Primary
      - key: secondary
        label: Secondary
      - key: accent
        label: Accent

Entity References

entity-selector

Pick one or many entity references, with optional typed relationship labels.

Category: entity

Option	Type	Default	Description
`reference_type`	string	—	Entity type to filter the picker by
`max_selections`	number	—	Set to `1` for a single-entity selector
`relationship_types`	`{value, label}[]`	—	Optional relationship type labels attached to each selection

Value format:

Single (max_selections: 1): string (entity ID)
Multi: string[] (entity IDs)
With relationship types: [{ id: string, relationship: string }]

Example:

field_config:
  allies:
    widget: entity-selector
    reference_type: character
    relationship_types:
      - value: ally
        label: Ally
      - value: mentor
        label: Mentor

ordered-entity-list

Reorderable list of typed entity references.

Category: entity

Option	Type	Default	Description
`reference_type`	string	—	Entity type to filter the picker by
`max_items`	number	—	Maximum number of entries
`relationship_types`	`{value, label}[]`	—	Optional relationship type labels

Value format: string[] (ordered entity IDs)

Example:

field_config:
  party_order:
    widget: ordered-entity-list
    reference_type: character
    max_items: 6

Arrays & Structures

tag-input

Free-form string tag entry with optional autocomplete suggestions.

Category: array

Option	Type	Default	Description
`max_items`	number	—	Maximum number of tags
`suggestions`	string[]	—	Suggested tag values for autocomplete

Value format: string[]

Example:

field_config:
  keywords:
    widget: tag-input
    max_items: 20
    suggestions:
      - fantasy
      - sci-fi
      - horror

textarea-array

Newline-separated list that stores as an array.

Category: array

Option	Type	Default	Description
`placeholder`	string	—	Placeholder text shown when empty

Value format: string[]

Example:

field_config:
  bullet_points:
    widget: textarea-array
    placeholder: "One item per line..."

object-array

Rows of structured objects with defined sub-fields.

Category: array

Option	Type	Default	Description
`sub_fields`	object[]	—	Field definitions for each row object

Value format: object[]

Example:

field_config:
  inventory:
    widget: object-array
    sub_fields:
      - key: item_name
        label: Item Name
        widget: text
      - key: quantity
        label: Quantity
        widget: number

nested-object

Inline sub-field editor for a single embedded object.

Category: array

Option	Type	Default	Description
`sub_fields`	object[]	—	Field definitions for the nested object

Value format: object

Example:

field_config:
  stats:
    widget: nested-object
    sub_fields:
      - key: strength
        label: Strength
        widget: number
      - key: dexterity
        label: Dexterity
        widget: number

percentage-group

Multiple percentage number inputs rendered as a group.

Category: array

Option	Type	Default	Description
`sub_fields`	`{key, label}[]`	—	Named percentage fields

Value format: { [key]: number }

Example:

field_config:
  elemental_resistances:
    widget: percentage-group
    sub_fields:
      - key: fire
        label: Fire
      - key: ice
        label: Ice
      - key: lightning
        label: Lightning

key-value

Arbitrary key-value pair editor.

Category: array

Option	Type	Default	Description
`key_label`	string	`Key`	Label for the key column
`value_label`	string	`Value`	Label for the value column
`max_items`	number	—	Maximum number of pairs

Value format: [{ key: string, value: string }]

Example:

field_config:
  metadata:
    widget: key-value
    key_label: Property
    value_label: Value
    max_items: 10

ordered-list

Reorderable list of free-form string items.

Category: array

Option	Type	Default	Description
`max_items`	number	—	Maximum number of list items

Value format: string[]

Example:

field_config:
  chapter_order:
    widget: ordered-list
    max_items: 50

Media References

asset-ref

Unified asset picker with type filter and inline preview.

Category: media

Option	Type	Default	Description
`allowed_types`	string[]	all	Asset types to allow (`image`, `audio`, `video`, `model`, `file`)
`max_selections`	number	`1`	Maximum number of assets to select

Value format: string (file path) or string[] when max_selections > 1

Example:

field_config:
  attachments:
    widget: asset-ref
    allowed_types:
      - image
      - file
    max_selections: 5

image-ref

Asset picker restricted to image files. Shorthand for asset-ref with allowed_types: ["image"].

Category: media

Option	Type	Default	Description
`accept`	string	—	File extension filter (e.g. `.png,.jpg,.webp`)
`max_selections`	number	`1`	Maximum number of images to select

Value format: string

Example:

field_config:
  portrait:
    widget: image-ref
    accept: ".png,.jpg,.webp"

audio-ref

Asset picker restricted to audio files. Shorthand for asset-ref with allowed_types: ["audio"].

Category: media

Option	Type	Default	Description
`accept`	string	—	File extension filter (e.g. `.mp3,.wav,.ogg`)

Value format: string

Example:

field_config:
  theme_music:
    widget: audio-ref
    accept: ".mp3,.wav,.ogg"

video-ref

Asset picker restricted to video files. Shorthand for asset-ref with allowed_types: ["video"].

Category: media

Option	Type	Default	Description
`accept`	string	—	File extension filter (e.g. `.mp4,.webm`)

Value format: string

Example:

field_config:
  cutscene:
    widget: video-ref
    accept: ".mp4,.webm"

model-3d-ref

Asset picker restricted to 3D model files. Shorthand for asset-ref with allowed_types: ["model"].

Category: media

Option	Type	Default	Description
`accept`	string	—	File extension filter (e.g. `.glb,.gltf,.fbx,.obj`)

Value format: string

Example:

field_config:
  character_mesh:
    widget: model-3d-ref
    accept: ".glb,.gltf,.fbx"

file-ref

General-purpose asset picker with no type restriction. Shorthand for asset-ref with allowed_types: ["*"].

Category: media

Option	Type	Default	Description
`accept`	string	—	File extension filter (e.g. `.pdf,.zip`)

Value format: string

Example:

field_config:
  design_doc:
    widget: file-ref
    accept: ".pdf,.docx"

Layout Helpers

heading

Static heading or visual divider in the form layout. Does not store a value.

Category: layout

Option	Type	Default	Description
`text`	string	—	Heading text to display
`level`	string	`h3`	HTML heading level (`h2`, `h3`, `h4`)

Value format: none (display only)

Example:

field_config:
  combat_section_header:
    widget: heading
    text: Combat Stats
    level: h3

Document

nested-section

Document outline editor with reorderable named sections.

Category: document

Option	Type	Default	Description
—	—	—	No configuration options

Value format: section[] where each section has a title and content

Example:

field_config:
  chapters:
    widget: nested-section

doc-ref

Reference to a document file with an inline preview or embed.

Category: document

Option	Type	Default	Description
`accept`	string	—	Allowed file extensions (e.g. `.md,.csv,.pdf`)
`render`	string	`link`	How to display the referenced file (`preview`, `link`, `embed`)

Value format: string (file path)

Example:

field_config:
  design_notes:
    widget: doc-ref
    accept: ".md,.pdf"
    render: preview

Plugin Widgets

Plugin developers can register custom field widgets. See Building a Custom Field Widget for a complete tutorial.

Plugin widgets use the ID format plugin:{pluginId}:{widgetId} and appear in the Layout Designer widget dropdown under the “Plugin” category.

field_config:
  my_field:
    widget: "plugin:advanced-color-tools:gradient-picker"

Widget System Architecture — resolution pipeline, inference, and extension model
Widget Registry Reference — SDK API signatures and full built-in widget table
Building Field Widgets — plugin development tutorial with examples

Component Blocks Reference Widget Registry Reference

Field Widgets Reference

Overview

Widget Resolution Order

Widgets vs Component Blocks

field_config Reference

Widget Catalog

Text & Content

text

textarea

rich-text

code

read-only

url

email

slug

Numbers & Ranges

number

range

rating

vector2

vector3

angle

duration

Selection

select

multi-select

checkbox

checkbox-group

radio-group

toggle

icon-picker

Date & Time

date

datetime

time

year

date-range

Color

color-picker

color-palette

color-group

Entity References

entity-selector

ordered-entity-list

Arrays & Structures

tag-input

textarea-array

object-array

nested-object

percentage-group

key-value

ordered-list

Media References

asset-ref

image-ref

audio-ref

video-ref

model-3d-ref

file-ref

Layout Helpers

heading

Document

nested-section

doc-ref

Plugin Widgets

Related Documentation