Defaults

A Default is a prop value declared once, app-wide, for a component. Every instance of that component starts from it — whether written inline in a template or coming from a schema — and a prop set on the instance still wins. Forms that share a validation trigger, a request format, or a column layout shouldn't have to repeat it on every instance.

Setting Defaults

Defaults live under the defaults key of createVueform, keyed by component name. Each entry holds that component's props:

createVueform({
  defaults: {
    VfForm: {
      validateOn: ['change', 'submit'],
    },
  },
})

Every VfForm in the app now validates on change and submit, unless an instance sets its own validateOn.

Keys inside an entry are camelCase prop names, exactly as in a schema entry — a kebab-case key like 'validate-on' is silently ignored.

Any prop can be defaulted, including component-valued ones like template or layout (see Templates) and namespaced part:<key> overrides. The class:<key> / reclass:<key> shorthands are the exception — they're only read from the instance, so default them through the classes / reclass object props instead.

Defaults belong to components. They resolve when a component instance is created, so a headless useModel instance never reads them — a VfForm Default like json: true shapes mounted forms' submissions, not model.submit() on an unattached Model (see Submitting Through a Model).

Defaults are also app-wide and fixed at createVueform. For prop bundles that only some instances or one subtree should get, use Presets.

Wildcard Targets

Two keys target groups of components instead of one. '*' targets every component, and '*element' targets every element — components flagged element: true in their definition, which covers every field plus Containers like VfGroup and VfList, as well as Custom Components that carry the flag. What '*element' skips is the short list — VfForm, VfTabs, VfSteps, VfNav, and the layout pieces (VfLayout, VfRow, VfCol, VfAddon).

A wildcard value only affects components that declare the prop; elsewhere it has no effect. Be careful with '*' though — it reaches VfForm too, so a '*': { disabled: true } disables whole forms. Prefer '*element' for field-level props.

Wildcards and component keys layer freely:

createVueform({
  defaults: {
    '*element': {
      columns: 6,
    },
    VfText: {
      placeholder: 'Type here...',
    },
  },
})

A VfText gets both values, a VfSelect only columns, and VfForm neither. Layers combine per prop in the order '*' → '*element' → component key, following the rules of Merging Behavior — a later layer overrides a primitive, shallow-merges into a plain object, and concatenates presets.

Resolution Order

For each prop of an instance, sources apply from lowest to highest priority:

1. Built-in Default — the value the component itself declares. It only participates when the instance doesn't set the prop; a local value never merges with it.
2. '*' — the all-components wildcard.
3. '*element' — skipped for non-elements.
4. Component key — VfText, VfForm, ….
5. Presets — from the instance's presets prop or cascaded from an ancestor.
6. Local prop — what the instance sets.

Merging Behavior

The rule is closer wins:

• A local value overrides even when falsy — false, 0, '', and null are real values.
• undefined counts as not set, so the Default applies.
• Arrays, primitives, non-plain objects (Date, Map, Set, File, refs and other class instances), and component definitions (a template, layout, or slot component) replace whole.

Plain objects are the refinement — they shallow-merge, so a Default keeps contributing the keys the instance doesn't set:

createVueform({
  defaults: {
    VfForm: {
      headers: { 'X-App-Version': '1.0.0' },
    },
  },
})

<VfForm endpoint="/api/save" :headers="{ Authorization: 'Bearer xyz' }" />

This form's requests carry both headers — Authorization from the instance and X-App-Version from the Default. To make local objects replace Defaults instead, set mergeObjectProps: false.

Merging presets

The presets prop concatenates instead of replacing. Presets arriving from Defaults apply first, then the instance's own list, and a name that arrives from both applies once:

createVueform({
  defaults: {
    '*element': {
      presets: ['compact'],
    },
  },
})

<VfText name="email" :presets="['branded']" />

Both Presets apply to this element, compact first. What Presets are and how they stack among themselves is covered in Presets.

Merging class and classes

The classes prop merges across every level — Defaults, Presets, and the local prop all contribute. The full class resolution chain, reclass included, lives at Override Priority.

class follows closer-wins like any other string prop, so a local class replaces a Default one. For root classes that should survive a local class, Default classes: { root: '…' } instead.

TypeScript

The defaults object is fully typed with no helper needed. Component keys autocomplete against the registered components, and each entry is checked against that component's props — a misspelled prop name or a wrong value type fails at compile time.

Wildcard entries are looser by necessity. Known prop names autocomplete and their values are checked ('*element' against the element prop surface), but unknown keys are accepted, since a wildcard spans components with different props.