Reference Fields

ReferenceField lets users select from a list of reference options, such as entity records, with multiple layout and data provider options.

Basic Configuration

ReferenceField(
  name: 'instructor',
  title: 'Instructor',
  provider: StaticReferenceProviderConfiguration(
    options: [
      ReferenceOption(id: 'INS001', title: 'Dr. Alice Smith'),
      ReferenceOption(id: 'INS002', title: 'Prof. Bob Jones'),
      ReferenceOption(id: 'INS003', title: 'Dr. Carol Williams'),
    ],
  ),
  allowMultiple: false,
  allowCreate: false,
)

Properties

Property	Type	Default	Description
provider	ReferenceDataProviderConfiguration?	null	Data source for options
allowMultiple	bool	false	Multi-select mode
maxSelections	int?	null	Maximum selections (0 = unlimited)
minSelections	int?	null	Minimum selections required
allowCreate	bool	false	Allow creating new items

Data Providers

Reference fields use provider configurations to fetch options. The built-in provider is StaticReferenceProviderConfiguration for static option lists. Every provider can implement option search, fetch by id, fetch many by id, and optionally creation.

At runtime, custom providers are registered through the vyuh_feature_forms ReferenceFieldDescriptor with provider TypeDescriptors:

ReferenceFieldDescriptor(
  providers: [
    StaticReferenceProviderConfiguration.typeDescriptor,
    MyEntityProviderConfiguration.typeDescriptor,
  ],
)

For the visual editor, vyuh_form_editor uses editor-side ProviderType factories instead:

FormEditorDescriptor.withDefaults(
  fieldTypes: [
    ReferenceFieldDescriptor(
      providers: [
        staticProviderType(),
        myEntityProviderType(['course', 'instructor']),
      ],
    ),
  ],
)

ProviderType keeps visual-authoring state self-contained and converts to or from a runtime ReferenceDataProviderConfiguration during import/export.

Layout Options

ReferenceField supports 6 different layouts:

Autocomplete (Default)

Type-ahead search with suggestions dropdown:

ReferenceField(
  name: 'instructor',
  title: 'Instructor',
  provider: provider,
  layout: AutocompleteReferenceLayout(
    minSearchLength: 1,
    searchDelay: 300,
    maxSuggestions: 10,
    showSubtitle: true,
    clearable: true,
  ),
)

Dropdown

Standard dropdown select:

ReferenceField(
  name: 'department',
  title: 'Department',
  provider: provider,
  layout: DropdownReferenceLayout(
    showSearch: true,
    dropdownMaxHeight: 300,
    clearable: true,
    dense: false,
  ),
)

Chips

Chip/tag selection, especially good for multi-select:

ReferenceField(
  name: 'prerequisites',
  title: 'Prerequisites',
  provider: provider,
  allowMultiple: true,
  layout: ChipsReferenceLayout(
    wrapChips: true,
    chipSize: 'medium',
    useAutocomplete: true,
    showCount: true,
  ),
)

Radio

Radio button group for single selection with limited options:

ReferenceField(
  name: 'exam_center',
  title: 'Exam Center',
  provider: provider,
  layout: RadioReferenceLayout(
    direction: 'vertical',
    showDescription: true,
  ),
)

Checkbox

Checkbox group for multi-select with limited options:

ReferenceField(
  name: 'electives',
  title: 'Elective Courses',
  provider: provider,
  allowMultiple: true,
  layout: CheckboxReferenceLayout(
    direction: 'vertical',
    showDescription: true,
    columns: 2,
  ),
)

Barcode Scanner

Scan a barcode or QR code to select a reference:

ReferenceField(
  name: 'equipment',
  title: 'Equipment',
  provider: provider,
  layout: BarcodeScannerReferenceLayout(
    fullscreenScanner: true,
    showTorchButton: true,
    showSelectedValue: true,
    clearable: true,
    validationPattern: r'^EQ-\d{6}$',
  ),
)

Multi-Select Configuration

ReferenceField(
  name: 'enrolled_courses',
  title: 'Enrolled Courses',
  provider: courseProvider,
  allowMultiple: true,
  minSelections: 1,
  maxSelections: 5,
)

When allowMultiple is true, the FormControl type becomes FormControl<List<String>>.

Field Dependencies

Providers can declare formFieldDependencies to feed current form values into option queries. The reference field container watches those dependency controls and refreshes options when they change.

DSL Usage

.reference('instructor', title: 'Instructor')
  .required()
  .help('Select the lead instructor')

Registration

Reference fields with custom providers require descriptor registration:

// In feature registration
ReferenceFieldDescriptor(
  layouts: [
    AutocompleteReferenceLayout.typeDescriptor,
    DropdownReferenceLayout.typeDescriptor,
    ChipsReferenceLayout.typeDescriptor,
    RadioReferenceLayout.typeDescriptor,
    CheckboxReferenceLayout.typeDescriptor,
    BarcodeScannerReferenceLayout.typeDescriptor,
  ],
  providers: [
    StaticReferenceProviderConfiguration.typeDescriptor,
    // Add custom providers here
  ],
)

When the same provider should be configurable in the visual editor, register the matching editor ProviderType in the form editor descriptor as shown above.

Next Steps

• Visual Editor -- Building forms with the drag-drop editor
• Field Types -- All 12 field types
• Building Forms -- Step-by-step form construction