Prepopulating Select Boxes with Values

Select (dropdown) widgets display options that come from your backend at load time. You supply these via the fieldAllowedValues dictionary in your response.

---

Response structure

fieldAllowedValues is a Dictionary<string, Dictionary<string, string>>:

• Outer key — the widget Name as set in the Form Builder.
• Inner dictionary — { "optionKey": "Display Label", ... }.

The selected value stored in formData is the option key, not the display label.

---

Loading options on form open

public async Task Form_onInit(bool isInitialLoad)
{
    // Load status options from the database
    var statuses = await _db.Statuses
        .OrderBy(s => s.SortOrder)
        .ToDictionaryAsync(s => s.Id.ToString(), s => s.Name);

    SetFieldAllowedValues("status", statuses);

    // Load a static list for currency
    SetFieldAllowedValues("currency", new Dictionary<string, string>
    {
        { "USD", "US Dollar" },
        { "EUR", "Euro" },
        { "GBP", "British Pound" },
        { "CAD", "Canadian Dollar" }
    });

    // Load countries
    var countries = await _db.Countries
        .OrderBy(c => c.Name)
        .ToDictionaryAsync(c => c.Code, c => c.Name);

    SetFieldAllowedValues("country", countries);
}

---

Cascading dropdowns

Update a dependent dropdown when a parent field changes using onChange:

public async Task country_onChange(string? value)
{
    // Reload the region dropdown based on the selected country
    var regions = await _db.Regions
        .Where(r => r.CountryCode == value)
        .OrderBy(r => r.Name)
        .ToDictionaryAsync(r => r.Id.ToString(), r => r.Name);

    SetFieldAllowedValues("region", regions);

    // Clear the currently selected region since the list changed
    record.SetField("region", "");
}

public async Task region_onChange(string? value)
{
    var cities = await _db.Cities
        .Where(c => c.RegionId.ToString() == value)
        .OrderBy(c => c.Name)
        .ToDictionaryAsync(c => c.Id.ToString(), c => c.Name);

    SetFieldAllowedValues("city", cities);
    record.SetField("city", "");
}

---

Refreshing options after an action

You can update a dropdown's options after any backend action — not just onChange. For example, after adding a new category from a modal, refresh the parent form's category dropdown:

public async Task Form_onClick(string widgetName)
{
    if (widgetName == "savecategorybtn")
    {
        await SaveCategory(record.GetData());

        // Refresh the categories dropdown in the parent
        var categories = await _db.Categories
            .ToDictionaryAsync(c => c.Id.ToString(), c => c.Name);

        SetFieldAllowedValues("categoryId", categories);
        ShowMessage("success", "Category saved.");
    }
}

---

Empty/placeholder option

If you want a "Please select..." placeholder, include an empty key at the start of your dictionary:

var options = new Dictionary<string, string>
{
    { "",   "— Please select —" },
    { "1",  "Option A" },
    { "2",  "Option B" }
};
SetFieldAllowedValues("mySelect", options);