Form Builder for Quasar

🇪🇸 Versión en español | 🇧🇷 Versão em português

Quasar extension for building declarative forms in Vue 3 + Quasar apps.

Table of contents

• In 30 seconds
• What it is and what it includes
• Requirements and compatibility
• Install in a Quasar app
• What the extension adds to the host
• Global defaults (boot)
• Scaffold commands in the host
• Quick start
• Language (i18n)
• TypeScript in your IDE
• Form configuration guide
• Field presets (reusable fields)
• Public API
• Supported field catalog
• Registered directives
• Store and conceptual state/error map
• SlotField and ref usage
• Related optional extensions
• Customize scaffold template
• Public entrypoints
• Troubleshooting

In 30 seconds

Recommended flow:

1. Define the payload type.
2. Build config with useFormBuilder().defineForm(...).
3. Render <FormBuilder> with that config.
4. Handle submit/reset via events.

The extension installs boots, directives, and scripts in the host project for immediate use.

What it is and what it includes

Form Builder builds declarative forms on Quasar: one Pinia model per formName, typed fields, and reusable validation.

• defineForm + <FormBuilder> — typed config; dynamic props with FormAwareValue.
• ~30 field types (text, dates, local/remote selects, files, FormList, …) — catalog; prop details in the IDE.
• inputRules, requiredOn, selectFormStore, directives v-form-builder-*.
• FormList and InputFileMultiple use DataTable (@benjaminor-dev/datatable); for declarative listings use Table Builder.
• Global boot defaults (configureFormBuilderDefaults); scaffold bor:help, bor:make-form, bor:make-formlist, bor:make-field.

Requirements and compatibility

The host Pinia boot must run before this extension's store boot.

Install in a Quasar app

Install DataTable before Form Builder (required peer — FormList, InputFileMultiple, and the compatibility check require it):

quasar ext add @benjaminor-dev/datatable
quasar ext add @benjaminor-dev/form-builder

Recommended extension: file preview

With InputFile / InputFileMultiple, install dialog-file-preview (optional). showPreview defaults to true: with the extension, view/download opens the modal; without it, the field behaves like standard QFile.

quasar ext add @benjaminor-dev/dialog-file-preview

Boot order (full stack): see Related optional extensions.

Remove extension:

quasar ext remove @benjaminor-dev/form-builder

What the extension adds to the host

Install (quasar ext add / invoke): creates src/boot/bor/bor-form-builder-defaults.ts (or .js) and registers it in quasar.config → boot: [] automatically. You do not need to edit it manually in a normal install. Package boots (boot/store, boot/directives) and CSS are injected by the extension on every dev/build (they do not appear as short entries in quasar.config).

Remove (quasar ext remove): removes generated scaffolds, the defaults boot, its entry in quasar.config, and this extension's bor:* npm scripts (only if they still point to install files).

If you delete the defaults boot, the app still uses built-ins (filled, stacked, lazy, md).

Boot order (this extension): Pinia → DataTable (CSS) → FB store boot → bor/bor-form-builder-defaults → rest.

Global defaults (boot)

Avoid repeating fieldDesign, labelPosition, validationMode, and gap in every defineForm. Priority: defineForm / <FormBuilder> props → boot (configureFormBuilderDefaults) → built-in (filled, stacked, lazy, md).

After quasar ext add, review src/boot/bor/bor-form-builder-defaults.ts — full template with defaultFieldProps, // recommended comments, etc.

// src/boot/bor/bor-form-builder-defaults.ts (excerpt)
import { configureFormBuilderDefaults } from "@benjaminor-dev/quasar-app-extension-form-builder";

configureFormBuilderDefaults({
  fieldDesign: "filled",
  labelPosition: "stacked",
  validationMode: "lazy",
  gap: "md",
  // defaultFieldProps: { InputSelect: { clearable: true, fieldUi: { color: "primary" } } }
  // defaultFormListUi: { addBtnColor: { light: "white", dark: "primary" } }
});

configureFormBuilder is an alias of configureFormBuilderDefaults.

Scaffold commands in the host

The extension registers npm scripts in the host for forms and list forms (FormList). Each runner in scripts/bor/bor-make-*.mjs delegates to the npm /scaffold API (runBorHelp, runBorMakeForm, …). Run npm run bor:help to see all scaffolds installed in the project, options, and usage guide.

Help (bor:help)

Lists installed generators, -- syntax, and common options (--force):

npm run bor:help

Forms (bor:make-form)

After -- goes the name or path of the form to generate.

npm run bor:make-form -- <form-name-or-path>

The argument is normalized to PascalCase and the generated file always ends in Form.vue.

Example — create a login form (LoginForm.vue):

npm run bor:make-form -- login

Result:

• src/components/FormBuilder/LoginForm.vue

Subfolder example — create users/RegisterForm.vue and overwrite if it already exists:

npm run bor:make-form -- users/register --force

Result:

• src/components/FormBuilder/users/RegisterForm.vue

Naming rules:

• The final file name is normalized to PascalCase.
• Always ends in Form.vue.
• If you pass RegisterForm, it does not duplicate FormForm.
• formName in the scaffold: PascalCase aligned with the file (e.g. LoginForm, TempForm).
• You can force overwrite with --force (or -f).
• The scaffold includes selectFormStore, a submit button, and (optional) “Clear (store)” via the handle's reset().

List forms (bor:make-formlist)

Generates a Vue scaffold with FormBuilder, an embedded FormList field, and submit buttons (SlotField) in src/components/FormBuilder/ — same path and naming convention as bor:make-form; only the template differs:

npm run bor:make-formlist -- <form-name-or-path>

Example:

npm run bor:make-formlist -- temp
npm run bor:make-formlist -- users/TeamRegister

• Always ends in Form.vue (e.g. temp → TempForm.vue, same as bor:make-form temp).
• If you pass TeamRegisterForm or TeamRegisterList, it does not duplicate suffixes.
• formName in the scaffold: PascalCase aligned with the file (e.g. TempForm).
• You can force overwrite with --force (or -f).
• Host template override: scripts/bor/stubs/bor-make-formlist.stub.
• The scaffold includes selectFormStore and a “Clear list (store)” button that clears the embedded FormList array.

Field presets (bor:make-field)

Generates a reusable file in src/components/FormBuilder/Fields/ with defineFieldPreset — for selects, server fields, or other fields you repeat across many forms.

npm run bor:make-field -- <NombrePreset> [FieldType]

Example — country preset (local select):

npm run bor:make-field -- CountrySelect InputSelect

Edit the generated file (service, options, icons) and use it in any defineForm — see Field presets.

Host template override: scripts/bor/stubs/bor-make-field.stub.

Quick start

Minimal example of the corporate client onboarding scenario (identity + submit). The integrated example below shows the near-complete reference form.

<script setup lang="ts">
import FormBuilder, {
  useFormBuilder,
} from "@benjaminor-dev/quasar-app-extension-form-builder";

type CorporateIdentityForm = {
  legalName: string | null;
  tradeName: string | null;
  taxId: string | null;
  brandColor: string | null;
  corporateEmail: string | null;
  acceptContract: boolean;
};

const { defineForm, inputRules } = useFormBuilder();

const config = defineForm<CorporateIdentityForm>({
  formName: "corporateIdentityForm",
  fieldDesign: "filled",
  labelPosition: "stacked",
  fields: [
    {
      type: "InputText",
      model: "legalName",
      label: "Legal name",
      requiredOn: () => true,
      rules: [
        inputRules.legalTextExtendedRule(),
      ],
      props: {
        placeholder: "E.g. Acme Services Inc.",
      },
    },
    {
      type: "InputText",
      model: "tradeName",
      label: "Trade name",
      readonlyOn: (form) => !form?.legalName,
      props: {
        placeholder: "Optional — how the brand is known",
      },
    },
    {
      type: "InputText",
      model: "taxId",
      label: "Tax ID",
      requiredOn: (form) => !!form?.legalName,
      rules: [
        inputRules.rfc(),
      ],
      props: {
        placeholder: "E.g. ACME850101ABC",
        maxLength: 13,
      },
    },
    {
      type: "InputColor",
      model: "brandColor",
      label: "Brand color",
      props: {
        defaultColor: "#1976D2",
        placeholder: "#RRGGBB",
      },
    },
    {
      type: "InputEmail",
      model: "corporateEmail",
      label: "Corporate email",
      requiredOn: () => true,
      props: {
        placeholder: "contact@company.com",
      },
    },
    {
      type: "ToggleButton",
      model: "acceptContract",
      label: "I accept master agreement and data processing",
      requiredOn: () => true,
    },
    {
      type: "SlotField",
      props: {
        slotName: "actions",
      },
    },
  ],
});

function onSubmit(payload: CorporateIdentityForm) {
  console.log("submit", payload);
}
</script>

<template>
  <FormBuilder :config="config" @submit="onSubmit">
    <template #slot-field-actions>
      <div class="flex justify-end q-gutter-sm">
        <q-btn type="reset" flat label="Clear" />
        <q-btn type="submit" color="primary" label="Submit request" />
      </div>
    </template>
  </FormBuilder>
</template>

Language (i18n)

Built-in en, es, and pt. By default input chrome, FormList, and file-field strings follow Quasar language ($q.lang.isoName); if Quasar has no language, fallback is en.

Locale resolution: boot locale → $q.lang.isoName prefix (es* → es, pt* → pt) → en.

Quasar config example (Spanish for the whole app):

// quasar.config.ts
framework: {
  lang: "es",
},

Boot template (after install):

configureFormBuilderDefaults({
  // locale: "es", // pins only Form Builder language
  // messages: { formListAdd: "Add" },
});

i18n keys cover common actions (clear, save, cancel, preview), input aria (showHidePassword, openDatePicker, clearField), editor toolbar, FormList chrome (formListAdd, formListValidationTitle, formListMinimized, …), and file rejections (fileRejectionMaxSize, fileCapacityOverLimit with {max}, {name}, {reason} templates). See FormBuilderMessages in /types for the full catalog.

Message priority: boot messages merges over the active locale built-in catalog.

Runtime API: useFormBuilderI18n() returns reactive messages tied to $q.lang.isoName. For imperative access (tests, non-Vue code), use resolveFormBuilderMessages(isoName?) — same resolution as boot → $q.lang → en.

import {
  configureFormBuilderDefaults,
  resolveFormBuilderMessages,
  useFormBuilderI18n,
} from "@benjaminor-dev/quasar-app-extension-form-builder";

configureFormBuilderDefaults({ locale: "es" });
const msgs = resolveFormBuilderMessages(); // boot locale

// Inside a component:
const { messages } = useFormBuilderI18n();
// messages.value.formListAdd, messages.value.clear, …

TypeScript in your IDE

You do not need to memorize every prop: typing and autocomplete show the contract as you write.

• Import types from @benjaminor-dev/quasar-app-extension-form-builder/types (e.g. FormAwareValue, BootFieldPropsFor, FieldUiConfigFor, each input's types).
• defineForm<MyPayload>({ ... }) — the generic fixes the form shape; *On callbacks receive that typed payload.
• fields accepts an array (usual form) or a callback ({ preset }) => [...] when you use field presets with preset(...). Both forms are valid.
• Inside fields[], use Ctrl+Space (Windows/Linux) or Cmd+Space (macOS):
  • on type: you will see valid inputs (InputText, InputSelect, …);
  • on props: that input's public props, with JSDoc in the tooltip on hover.
• fieldUi (in props or boot defaultFieldProps[type]): visual tokens per type — autocomplete with FieldUiConfigFor<"InputText"> (each type is independent). placeholder, hint, etc. go outside fieldUi.
• FormList → props.listUi: list chrome tokens; global boot with defaultFormListUi.
• The full type catalog lives in FieldTypes; prop details are in the IDE as you write — this README catalog is a quick reference, not a substitute for autocomplete.
• Standalone components: @benjaminor-dev/quasar-app-extension-form-builder/inputs with the same exported types.
• In boot, locale accepts "en" \| "es" \| "pt"; messages accepts Partial<FormBuilderMessages> (inputs, FormList, files, pickers).

If a prop does not appear in autocomplete, it probably does not exist in the public API or the field type does not support it.

Form configuration guide

Field anatomy

Each fields[] entry describes a form control:

// inside defineForm({ fields: [ ... ] })
{
  type: "InputEmail",
  model: "corporateEmail",
  label: "Corporate email",
  requiredOn: () => true,
  rules: [
    inputRules.email(),
  ],
  props: {
    placeholder: "name@company.com",
    clearable: true,
  },
  onChange: (newValue, _oldValue, form) => {
    console.log(newValue, form?.legalName);
  },
},

requiredOn already injects the required rule; do not duplicate it in rules unless you need another independent validation.

Root level vs props: the field object includes type, model, label, rules, conditional callbacks (*On), and lifecycles (onChange, …). Widget presentation (placeholder, hint, helpTooltip, prependIcon) always goes inside props for the corresponding input type. label (root or in props), placeholder, hint, helpTooltip, and prependIcon accept a fixed value or a model-based callback (see table).

Widget presentation props (props)

Native label tooltip: on narrow screens the label text may truncate. Hovering the field or the visible label shows the full label in the browser (HTML title attribute, resolved with FormAware like label). Do not confuse with helpTooltip (the ? popover).

// inside fields: [ ... ]
{
  type: "InputText",
  model: "legalName",
  label: "Legal name",
  requiredOn: () => true,
  props: {
    placeholder: "E.g. Acme Services Inc.",
    hint: "Name registered with tax authority.",
    helpTooltip: "Must match the articles of incorporation.",
  },
},

Conditional callbacks

Signature: (form?: FormBuilderSubmitPayload<T>) => boolean. Use form?.field or () => value when you do not need the model.

Exceptions by field type:

Order fields[] top to bottom: conditional callbacks should depend only on earlier fields (see integrated example).

Initial values (defaultValues)

Optional property. If omitted, each field with model gets the empty value for its type:

You can pass a partial object with only the overrides you need; omitted keys use the table above.

You can also pass a function (sync or async) that returns a partial object. FormBuilder runs it on onMounted — useful for preload or API edit mode. On resolve, it updates the store and the reset baseline (resetForm restores preloaded values, not the intermediate empty state).

defaultValues: async () => {
  const record = await fetchCorporateRecord(id);
  return {
    legalName: record.name,
    corporateEmail: record.email,
    billingCountry: record.country,
  };
},

The form starts with type empties; after preload you may briefly see those empties before values hydrate. You can call defineForm in the parent and pass the resulting config to FormBuilder; preload still runs when the form mounts.

Props and callbacks from the form (FormAware)

Besides field conditional callbacks (requiredOn, hideOn, …), you can read the current model in configuration props and effect callbacks. Three complementary layers:

FormAwareValue — fixed value or (form?) => T. No side effects; ideal for limits, text, and flags. Each field documents its props in the catalog.

Besides per-type limits and flags, label (root), placeholder, hint, helpTooltip, and prependIcon (in props) accept FormAwareValue for text and icons that change with the model.

On FormList, the same presentation props in props use FormListPresentationProp<T> (FormAware equivalent with parentForm / items / draftItem context): callback (data) => … instead of (form) => ….

// inside fields: [ ... ]
{
    type: "InputFile",
    model: "contractPdf",
    label: "Contract",
    props: {
      maxSize: (form) =>
        form?.plan === "enterprise" ? 10 * 1024 * 1024 : 5 * 1024 * 1024,
    },
  },
{
    type: "InputIntlPhone",
    model: "contactIntlPhone",
    label: (form) =>
      form?.billingCountry === "US"
        ? "US contact phone"
        : "International phone",
    props: {
      hint: (form) =>
        form?.billingCountry && form.billingCountry !== "MX"
          ? "Required outside Mexico."
          : undefined,
    },
  },

Callbacks with form — the model snapshot is passed as the optional last argument:

The options pipeline already exposed form in options(form), filterOptions(options, form), and callOptionsOn(form). With optionLabel(option, form?), visible labels recalculate when the model changes without reloading options.

optionLabel: (option, form) => {
    const discount = Number(form?.negotiatedDiscount ?? 0);
    return discount > 0
      ? `${option.label} (desc. ${discount}%)`
      : `${option.label} (${option.meta?.tier ?? "n/a"})`;
  },

Exported types in /types: FormAwareValue, FormSnapshot, FormListAwareValue, FormListPresentationProp, OptionLabelFn.

Advanced patterns: conditional + server + SlotField

Reference form combining chained hideOn, remote catalog, and SlotField sections. Flow is forward-only: each block depends on values already captured. The fragment below is illustrative; combine it with the catalog and IDE autocomplete.

function planOptionsVisible(form?: { priorityScore?: number | null }) {
  return Number(form?.priorityScore ?? 0) >= 5;
}

const config = defineForm<CorporateForm>({
  formName: "corporateOnboardingForm",
  fields: [
    {
      type: "InputNumber",
      model: "priorityScore",
      label: "Priority (1–10)",
      props: { min: 1, max: 10 },
    },
    { type: "SlotField", props: { slotName: "section-location" } },
    {
      type: "InputSelect",
      model: "billingCountry",
      label: "Billing country",
      hideOn: (form) => !planOptionsVisible(form),
      props: {
        callOptionsOn: (form) => form?.priorityScore,
        options: (form) => (planOptionsVisible(form) ? COUNTRY_OPTIONS : []),
      },
    },
    {
      type: "InputIntlPhone",
      model: "contactIntlPhone",
      label: "International phone",
      hideOn: (form) => !form?.billingCountry || form.billingCountry === "MX",
      requiredOn: (form) =>
        form?.billingCountry != null && form.billingCountry !== "MX",
    },
    {
      type: "InputSelectServer",
      model: "headquartersCity",
      label: "Headquarters city (remote catalog)",
      hideOn: (form) => !form?.billingCountry,
      props: {
        callOptionsOn: (form) => form?.billingCountry,
        optionsService: fetchMockCities,
        usePagination: true,
        searchOnServer: true,
        perPage: 50,
      },
    },
    { type: "SlotField", props: { slotName: "actions" } },
  ],
});

In the template, name slots #slot-field-{slotName} (e.g. #slot-field-section-location, #slot-field-actions).

Conditional flow summary (same reference form):

Field presets (reusable fields)

When the same field repeats across many forms (same service, options, icon…), extract the config to a field preset in src/components/FormBuilder/Fields/.

Two fields forms (compatible)

No need to migrate existing forms: the classic array remains valid. The callback applies only to the root defineForm; FormList → itemForm.fields stays an array.

1. Create the preset

npm run bor:make-field -- CountrySelect InputSelect

// src/components/FormBuilder/Fields/CountrySelect.field.ts
import { defineFieldPreset } from "@benjaminor-dev/quasar-app-extension-form-builder";

export const countrySelectField = defineFieldPreset("InputSelect", {
  label: "Country",
  props: {
    prependIcon: "public",
    placeholder: "Select country",
    options: [
      { label: "Mexico", value: "MX" },
      { label: "Colombia", value: "CO" },
    ],
  },
});

2. Use it in the form

import { countrySelectField } from "src/components/FormBuilder/Fields/CountrySelect.field";

defineForm<RegisterForm>({
  formName: "register",
  fields: ({ preset }) => [
    { type: "InputText", model: "legalName", label: "Legal name" },
    preset(countrySelectField, { model: "country" }),
    preset(countrySelectField, {
      model: "billingCountry",
      label: "Billing country",
    }),
  ],
});

Preset API

Overrides follow the same typing as an inline field (hideOn, label: (form) => …, props.placeholder, etc.).

Public API

useFormBuilder() returns:

defineForm(config)

<FormBuilder> prop (not in defineForm):

Global presentation (fieldDesign, labelPosition, validationMode, gap, defaultFieldProps): § Global defaults (boot).

Large forms and children with the model

One FormBuilder per screen (one <q-form>). Split fields across .ts modules or Fields/*.field.ts (presets). To read or mutate the model in composables, headers, or deep children, use selectFormStore:

const { defineForm, selectFormStore } = useFormBuilder();
const formName = "LoginForm";

const config = defineForm<LoginForm>({
  formName,
  fields: [...identityFields, ...billingFields],
  defaultValues: { email: null },
});

// Same state in any component or composable
const loginFormStore = selectFormStore<LoginForm>(formName);

loginFormStore.values.value.email = "a@b.com";
loginFormStore.setValues({ email: "a@b.com" });
if (loginFormStore.hasErrors.value) loginFormStore.clearErrors();
loginFormStore.reset();

FormBuilder (component)

By default fields are spaced with q-gutter-md. For another Quasar size, change the prop; for Tailwind (gap-4), an SCSS class, or style, disable built-in gutter and set gap in the host:

<!-- Default: q-gutter-md -->
<FormBuilder :config="config" @submit="onSubmit" />

<!-- Another Quasar size -->
<FormBuilder :config="config" gap="sm" @submit="onSubmit" />

<!-- Custom spacing (Tailwind, SCSS, style, …) -->
<FormBuilder
  :config="config"
  :gap="false"
  class="flex flex-col gap-4"
  @submit="onSubmit"
/>

<FormBuilder
  :config="config"
  :gap="false"
  :style="{ gap: '1.25rem' }"
  @submit="onSubmit"
/>

Events:

Custom reset example:

<script setup lang="ts">
import type { FormBuilderResetAction } from "@benjaminor-dev/quasar-app-extension-form-builder/types";

function onReset(
  _form: CorporateIdentityForm,
  resetForm: FormBuilderResetAction,
) {
  if (confirm("Discard changes?")) {
    resetForm();
  }
  // If you do not call resetForm(), the form keeps current values
}
</script>

<template>
  <FormBuilder :config="config" @submit="onSubmit" @reset="onReset" />
</template>

inputRules

Rules for each field's rules array. Required goes in requiredOn, not here — inputRules does not expose required. On InputDate, date rules receive the internal YYYY-MM-DD value; on InputNumber, InputDecimal, and InputCurrency the model is string | null.

{
    type: "InputText",
    model: "legalName",
    label: "Legal name",
    requiredOn: () => true,
    rules: [inputRules.legalTextExtendedRule(), inputRules.minLength(3)],
  },

InputFile applies file internally; no need to repeat it unless manual validation outside that field.

selectFormStore

Typed access to the form Pinia state (also available as a standalone function from the main entrypoint).

Outside the template, use selectFormStore<T>(formName) (values, errors, setValues, reset, …) — see Large forms and children with the model and Store and conceptual state/error map.

utils

General utilities for conditional logic in the host, search normalization, and numeric cleanup. Available with const { utils } = useFormBuilder().

cleanText aligns remote search with InputSelect / InputSelectServer and the country selector in InputIntlPhone. isEmpty / isNotEmpty avoid reimplementing empty checks in requiredOn, hideOn, or options. See integrated example (fetchMockCities).

Supported field catalog

Quick reference for fields[].type. Up-to-date props, rules, and examples: IDE autocomplete (type + props with Ctrl/Cmd+Space) and types in /types — see TypeScript in your IDE.

* Design = supports form fieldDesign / labelPosition. — = own presentation (borderless or other).

Per-field types: FieldTypes["InputSelect"], BootFieldPropsFor<"InputSelect">, etc. in @benjaminor-dev/quasar-app-extension-form-builder/types.

Representative examples

Text + local select

// inside fields: [ ... ]
{ type: "InputText", model: "legalName", label: "Legal name", requiredOn: () => true },
{
  type: "InputSelect",
  model: "plan",
  label: "Plan",
  props: {
    options: [
      { label: "Basic", value: "basic" },
      { label: "Pro", value: "pro" },
    ],
    clearable: true,
  },
},

Date with dynamic limits

{
  type: "InputDate",
  model: "startDate",
  label: "Start",
  props: {
    minDate: () => moment().format("YYYY-MM-DD"),
    maxDate: (form) => form?.endDate ?? undefined,
    clearable: true,
  },
},

Clear value (clearable) — on pickers (InputDate, InputDateRange, InputTime, InputColor), InputMacAddress, and InputEditor: FormAwareValue<boolean> prop (default true). Disable per field (clearable: false) or in boot (defaultFieldProps.InputDate: { clearable: false }). InputSelect* uses Quasar native :clearable.

File with preview (optional dialog-file-preview extension in host)

{
  type: "InputFile",
  model: "contract",
  label: "Contract",
  props: {
    accept: ".pdf",
    maxSize: 10 * 1024 * 1024,
    dragDrop: true,
    showPreview: true,
  },
},

Remote select (large catalog / API)

{
  type: "InputSelectServer",
  model: "cityId",
  label: "City",
  props: {
    optionsService: async ({ query, pagination, form }) => {
      const res = await api.searchCities({ q: query, country: form?.country, ...pagination });
      return { items: res.items, pagination: res.meta };
    },
    searchOnServer: true,
    usePagination: true,
    perPage: 50,
  },
},

Embedded FormList

{
  type: "FormList",
  model: "teamMembers",
  label: "Members",
  requiredOn: () => true,
  props: {
    listName: "members",
    itemLabel: "Member",
    itemForm: {
      fields: [
        { type: "InputText", model: "fullName", label: "Name", requiredOn: () => true },
      ],
    },
    columns: [{ name: "fullName", label: "Name", field: "fullName" }],
  },
},

Column slot on the parent FormBuilder: #form-list-members-column-fullName. More detail in integrated example and types FormListConfig, InputFormListProps in /types.

Registered directives

Runtime convention: form-builder-{directiveName}. In Vue templates use as v-form-builder-*.

• v-form-builder-max-length
• v-form-builder-only-numbers
• v-form-builder-only-decimal-number
• v-form-builder-format-number
• v-form-builder-max-number
• v-form-builder-currency-symbol
• v-form-builder-color-input (applied internally by InputColor per formatModel; filters characters on type/paste)
• v-form-builder-only-ip-address-chars (applied internally by InputIpAddress per version; filters to digits, ., :, and allowed hex)
• v-form-builder-only-mac-address-chars (applied internally by InputMacAddress per separator; filters hex and normalizes separators with the Quasar mask)

Store and conceptual state/error map

Access: useFormBuilder().selectFormStore(formName) or selectFormStore(formName) imported from the package.

selectFormStore<T>(formName)

Typed Pinia session view. The same formName in another .vue or composable points to the same state.

Tipo exportado: FormSessionHandle<T> en /types.

Conceptual flow:

1. defineForm creates (if missing) the form structure in the store with type empties or the partial defaultValues object.
2. If defaultValues is a function, FormBuilder runs it on onMounted, hydrates forms, and updates formsDefaults (reset baseline).
3. Each input writes to forms[formName][field].
4. Field errors live in formsErrors[formName][field].
5. resetForm restores formsDefaults and clears errors.

SlotField and ref usage

In SlotField slots with model, model and error are refs and bind with .value.

Canonical pattern in the host:

1. Import SlotFieldBind from @benjaminor-dev/quasar-app-extension-form-builder/types.
2. In the template: #slot-field-{slotName}="attrs: SlotFieldBind".
3. In the child control: v-model="attrs.model.value" (and attrs.error.value if applicable).

Section separators (slotName: "section-…", no model) do not use attrs.model; static markup only.

For custom fields with model, FormBuilder resolves requiredOn / disabledOn / readonlyOn and exposes required, readonly, and disable in the slot; you must wire them in your control and, if using requiredOn, add :rules in the template so q-form validates on submit.

<script setup lang="ts">
import FormBuilder, {
  useFormBuilder,
} from "@benjaminor-dev/quasar-app-extension-form-builder";
import type { SlotFieldBind } from "@benjaminor-dev/quasar-app-extension-form-builder/types";

type DemoForm = {
  customText: string | null;
};

const { defineForm } = useFormBuilder();

const config = defineForm<DemoForm>({
  formName: "demoForm",
  fields: [
    {
      type: "SlotField",
      model: "customText",
      props: {
        slotName: "custom-text",
      },
    },
  ],
});
</script>

<template>
  <FormBuilder :config="config">
    <template #slot-field-custom-text="attrs: SlotFieldBind">
      <q-input
        v-model="attrs.model.value"
        :error="!!attrs.error.value"
        :error-message="attrs.error.value || ''"
        :label="attrs.label"
        :hint="attrs.hint"
        :readonly="attrs.readonly"
        :disable="attrs.disable"
        :rules="attrs.required ? [(v) => !!v || 'Required field'] : undefined"
      >
        <template v-if="attrs.required" #append>
          <span class="text-negative">*</span>
        </template>
      </q-input>
    </template>
  </FormBuilder>
</template>

Embedded list example (recommended pattern — native FormList field):

// inside fields: [ ... ]
{
  type: "FormList",
  model: "teamMembers",
  label: "Members",
  requiredOn: () => true,
  props: {
    listName: "members",
    itemLabel: "Member",
    workflow: "free",
    itemForm: {
      fields: [
        {
          type: "InputText",
          model: "fullName",
          label: "Name",
          requiredOn: () => true,
        },
      ],
    },
    columns: [
      { name: "fullName", label: "Name", field: "fullName" },
    ],
  },
},

The bor:make-formlist scaffold generates a FormBuilder with an embedded FormList field (canonical pattern).

Related optional extensions

Install in the host (additional extensions):

quasar ext add @benjaminor-dev/datatable
quasar ext add @benjaminor-dev/dialog-file-preview

Boot order (full stack):

1. Pinia (host)
2. DataTable — CSS
3. Form Builder — boot/store
4. bor/bor-form-builder-defaults (host)
5. Table Builder — boot/store
6. bor/bor-table-builder-defaults (host)
7. Dialog File Preview — boot/dialog
8. bor/bor-dialog-file-preview-defaults (host)
9. Dialog Loader — boot/dialog
10. bor/bor-dialog-loader-defaults (host)
11. Dialog Message — boot/dialog
12. bor/bor-dialog-message-defaults (host)

Rule: register the defaults boot before first use (defineForm, defineTable, show()). In quasar.config you will see entries such as bor/bor-form-builder-defaults; package boots are injected by the extension at compile time — they do not appear as short entries in your config.

Customize scaffold template

You can replace the template generated by bor:make-form by creating in your host app:

scripts/bor/stubs/bor-make-form.stub

For list forms (bor:make-formlist):

scripts/bor/stubs/bor-make-formlist.stub

For field presets (bor:make-field):

scripts/bor/stubs/bor-make-field.stub

That file takes priority over the template included in the extension.

Public entrypoints

There is no /form-list entrypoint or separate npm package for lists: FormList is a native field type in this package.

Troubleshooting

Conditional callback shows type error

If you declare requiredOn: (form: MyForm) => ..., TypeScript may fail due to contravariance. The real signature accepts optional form.

Use:

requiredOn: (form) =>
  form?.phone === "123";

o:

requiredOn: (
  form?: FormBuilderSubmitPayload<MyForm>,
) => form?.phone === "123";

Duplicating required validation in rules

requiredOn already injects required internally. Do not add manual «required field» rules in rules; reserve them for additional validation (email, rfc, size, etc.).

Defaults boot missing from quasar.config

Under normal conditions install registers it automatically. If missing (old project or manual edit):

npx quasar ext invoke @benjaminor-dev/form-builder

npm command missing in host

Run in the host:

npx quasar ext invoke @benjaminor-dev/form-builder

Pinia not initialized

Ensure the Pinia boot runs before the extension store boot.

@benjaminor-dev/quasar-app-extension-datatable check fails

Form Builder requires the DataTable peer. Install it before this extension:

quasar ext add @benjaminor-dev/datatable

Without it, FormList / InputFileMultiple cannot resolve the component and table styles are missing.

InputDate/InputDateRange/InputTime ignore limits

Check FormAwareValue format:

• minDate / maxDate: "YYYY-MM-DD", () => "YYYY-MM-DD" o (form) => "YYYY-MM-DD"
• maxRange: number, () => number, or (form) => number (days)
• minTime / maxTime: "HH:mm:ss", () => "HH:mm:ss" o (form) => "HH:mm:ss"

gap="false" does not disable Quasar gutter

To remove q-gutter-* use :gap="false" (boolean with v-bind). If you write gap="false" without :, Vue sends the string "false"; since 0.9.7 the runtime treats it as disabled, but in new templates always prefer :gap="false".

validationMode eager is noisy on masked fields

validationMode: 'eager' makes Quasar evaluate rules on every keystroke. On visually formatted fields (dates, phones, currency) the default lazy is usually better — validates on blur or submit.

InputFile / InputFileMultiple do not show preloaded files

InputFile only accepts File | null; InputFileMultiple only accepts File[] (empty = []). If you pass a loose Blob, URL, base64, or { url, name } object, the value normalizes to empty. Create File on the client:

const blob = await fetch(url).then(
  (r) => r.blob(),
);
form.signedContractPdf = new File(
  [blob],
  "document.pdf",
  {
    type:
      blob.type || "application/pdf",
  },
);

On pure create forms, leave the field at null until the user selects the file.

View/download button missing on InputFile / InputFileMultiple

• Check you did not set showPreview: false in field props (true by default).
• Install @benjaminor-dev/dialog-file-preview and verify boots: Pinia → Form Builder → Dialog File Preview.
• On InputFile, append buttons appear only when there is a valid File in the model and the preview extension is available. On InputFileMultiple, preview is on each inline table row.
• With disable, preview is hidden; with readonly, preview or download works (delete/clear does not).
• After npm run build in the host or when linking the extension with file:, restart quasar dev to load the updated Form Builder dist.

Select/radio/checkbox group does not recognize preloaded value

Fields with options compare modelValue with options[].value strictly (===). If the API returns cityId: 1 but options use value: "1", they will not match. Align types in defineForm, defaultValues, and each option value. With numeric values, 0 is a valid selection for required on single select.

File is slow to appear after system dialog selection

This is normal with heavy files: InputFile and InputFileMultiple show a loading indicator while the browser exposes the File to the model. The @benjaminor-dev/dialog-file-preview dialog also shows a loader on open and while the viewer loads content (PDF, large image, etc.).

defaultValues as function does not preload the form

• The function (sync or async) runs on FormBuilder onMounted, not when calling defineForm in the parent.
• Pass the config returned by defineForm to <FormBuilder :config="config" />; do not replace defaultValues with a plain object before mount.
• After preload you will briefly see type empties; expected until the promise resolves.
• Reset restores already preloaded values (they update formsDefaults on hydrate).

List missing from parent form submit

• Declare the array in the form type (teamMembers: Member[]) and use type: "FormList" with model: "teamMembers" in fields[].
• On @submit, the handler receives FormBuilderSubmitPayload<T> — it is the form itself (payload.teamMembers, not payload.form). Same as other fields.
• For an initial scaffold, use npm run bor:make-formlist -- <name>: generates a FormBuilder with a wired FormList field (same path as bor:make-form).
• Before @submit, FormBuilder validates each visible FormList; if invalid rows exist, the event is not emitted.
• With workflow: "review", invalid rows are also highlighted in the table; the built-in dialog lists records to fix with the field label in the header.
• For custom alerts instead of the built-in dialog, define onAfterValidateError in field props (see FormList catalog).

Invalid rows dialog appears only once

• Earlier versions blocked the second submit attempt via QField rules; current runtime shows the error under the field without blocking retries: each Submit pulse revalidates and may reopen the dialog.
• If you defined onAfterValidateError, the built-in dialog does not open: implement retry/alert logic there.

MIT © Benjamín Olvera R.