Dynamic Form

Generate forms from a JSON field schema. Supports nested models, masks, regex inputs, currency, date pickers, and every VeloxUI input component — all powered by VxForm under the hood.

Nested Model

Dot-notation paths like user.username auto-generate nested reactive objects.

Username

Password

Description

Optional, max 200 characters

<script setup>
const formRef = ref()
const model = reactive({
  user: { username: '', password: '' },
  description: '',
})

const fields = [
  {
    field: 'user.username',
    label: 'Username',
    placeholder: 'Enter username',
    rules: [
      { required: true, message: 'Username is required' },
      { min: 3, max: 20, message: '3-20 characters' },
      { type: 'alphanumeric', message: 'Letters and numbers only' },
    ],
  },
  {
    field: 'user.password',
    label: 'Password',
    type: 'password',
    placeholder: 'Enter password',
    rules: [{ required: true }, { min: 8, message: 'At least 8 characters' }],
  },
  {
    field: 'description',
    label: 'Description',
    type: 'textarea',
    rows: 3,
    help: 'Optional, max 200 characters',
    rules: [{ max: 200, message: 'Max 200 characters' }],
  },
]
</script>

<template>
  <VxDynamicForm ref="formRef" :fields="fields" :model="model">
    <template #actions="{ validate, reset }">
      <VxButton @click="validate()">Submit</VxButton>
      <VxButton variant="outline" @click="reset()">Reset</VxButton>
    </template>
  </VxDynamicForm>
</template>

All Field Types

Every supported input type in a single form: text, password, textarea, mask, regex, currency, autocomplete, select, segment, radio, checkbox, switch, slider, rating, date, date-range, date-time, time, color.

Full Name

Email

Password

Bio

0 / 300

Phone

Credit Card

Zip Code

SSN

Hex Color Code

Only hex characters allowed

Salary

Price (EUR)

City

Role

Select a role

Plan

Gender

MaleFemaleOther

Skills

JavaScriptTypeScriptPythonGo

Newsletter

Agreement

I accept the terms and conditions

Experience (years)

Satisfaction

4

Birthday

Vacation Range

–

Appointment

Wake Up Time

Theme Color

#6366f1

<script setup>
const fields = [
  // ── Text Inputs ──
  { field: 'name', label: 'Full Name', clearable: true, trim: true, rules: { required: true } },
  { field: 'email', label: 'Email', type: 'email', clearable: true, rules: [{ required: true }, { type: 'email' }] },
  { field: 'password', label: 'Password', type: 'password', rules: [{ required: true }, { min: 8 }] },
  { field: 'bio', label: 'Bio', type: 'textarea', rows: 3, maxlength: 300, showWordLimit: true },

  // ── Masked Inputs ──
  { field: 'phone', label: 'Phone', type: 'tel', mask: '+# (###) ###-####' },
  { field: 'creditCard', label: 'Credit Card', mask: '#### #### #### ####' },
  { field: 'zipCode', label: 'Zip Code', mask: '#####' },
  { field: 'ssn', label: 'SSN', mask: '###-##-####' },

  // ── Regex-Restricted Input ──
  { field: 'hexCode', label: 'Hex Code', regex: /^#?[0-9A-Fa-f]{0,6}$/ },

  // ── Currency ──
  { field: 'salary', label: 'Salary (USD)', type: 'currency', currencyOptions: { prefix: '$ ', thousands: ',' } },
  { field: 'price', label: 'Price (EUR)', type: 'currency', currencyOptions: { prefix: '€ ', decimal: ',' } },

  // ── Autocomplete ──
  { field: 'city', label: 'City', type: 'autocomplete', options: ['New York', 'LA', 'Chicago', ...] },

  // ── Select ──
  { field: 'role', label: 'Role', type: 'select', options: [...], rules: { required: true } },

  // ── Segment ──
  { field: 'plan', label: 'Plan', type: 'segment', options: [...], defaultValue: 'free' },

  // ── Radio Group ──
  { field: 'gender', label: 'Gender', type: 'radio-group', options: [...] },

  // ── Checkbox Group ──
  { field: 'skills', label: 'Skills', type: 'checkbox-group', options: [...], defaultValue: [] },

  // ── Switch ──
  { field: 'newsletter', label: 'Newsletter', type: 'switch', defaultValue: true },

  // ── Checkbox ──
  { field: 'terms', label: 'Agreement', type: 'checkbox', placeholder: 'I accept the terms' },

  // ── Slider ──
  { field: 'experience', label: 'Experience', type: 'slider', props: { min: 0, max: 20, showInput: true } },

  // ── Rating ──
  { field: 'satisfaction', label: 'Satisfaction', type: 'rating', props: { allowHalf: true, showValue: true } },

  // ── Date & Time ──
  { field: 'birthday', label: 'Birthday', type: 'date', clearable: true },
  { field: 'vacation', label: 'Vacation Range', type: 'date-range', defaultValue: [] },
  { field: 'appointment', label: 'Appointment', type: 'date-time', clearable: true },
  { field: 'wakeUp', label: 'Wake Up Time', type: 'time', clearable: true },

  // ── Color Picker ──
  { field: 'theme', label: 'Theme Color', type: 'color', defaultValue: '#6366f1', props: { showInput: true } },
]
</script>

Grid Layout

Use columns + per-field span for multi-column forms. Mask and currency work in grid too.

First Name

Last Name

Email

Phone

Salary

Department

Select

Start Date

Level

Notes

Active

<script setup>
const fields = [
  { field: 'firstName', label: 'First Name', rules: { required: true } },
  { field: 'lastName', label: 'Last Name', rules: { required: true } },
  { field: 'email', label: 'Email', type: 'email' },
  { field: 'phone', label: 'Phone', type: 'tel', mask: '+# (###) ###-####' },
  { field: 'salary', label: 'Salary', type: 'currency', currencyOptions: { prefix: '$ ' } },
  { field: 'department', label: 'Department', type: 'select', options: [...] },
  { field: 'startDate', label: 'Start Date', type: 'date' },
  { field: 'level', label: 'Level', type: 'segment', options: [...] },
  { field: 'notes', label: 'Notes', type: 'textarea', rows: 3, span: 2 }, // spans 2 columns
  { field: 'active', label: 'Active', type: 'switch', defaultValue: true },
]
</script>

<template>
  <VxDynamicForm :fields="fields" :columns="2" :gutter="20">
    <template #actions><VxButton>Submit</VxButton></template>
  </VxDynamicForm>
</template>

Conditional Fields

Use hidden: (model) => boolean to show/hide fields reactively.

Account Type

Full Name

Email

<script setup>
const fields = [
  {
    field: 'accountType', label: 'Account Type', type: 'segment',
    options: [{ label: 'Personal', value: 'personal' }, { label: 'Business', value: 'business' }],
    defaultValue: 'personal',
  },
  { field: 'fullName', label: 'Full Name', hidden: (m) => m.accountType === 'business' },
  { field: 'companyName', label: 'Company', hidden: (m) => m.accountType !== 'business' },
  { field: 'taxId', label: 'Tax ID', mask: '##-#######', hidden: (m) => m.accountType !== 'business' },
  { field: 'email', label: 'Email', type: 'email' },
]
</script>

JSON from API

Load field schema dynamically and render the form instantly.

<script setup>
const schema = ref(null)

// Fetched from API — all fields are plain JSON-serializable objects
// {
//   field: 'ticket.title', label: 'Title',
//   rules: [{ required: true, message: 'Title is required' }]
// }

async function loadSchema() {
  schema.value = await fetch('/api/form-schema').then(r => r.json())
}
</script>

<template>
  <VxButton v-if="!schema" @click="loadSchema">Load Schema</VxButton>
  <VxDynamicForm v-if="schema" :fields="schema">
    <template #actions="{ validate }">
      <VxButton @click="validate()">Submit</VxButton>
    </template>
  </VxDynamicForm>
</template>

Custom Field Slot

Override any field's rendering using a named slot matching the field key.

<template>
  <VxDynamicForm :fields="fields">
    <!-- Override 'avatar' field with custom component -->
    <template #avatar="{ value, set }">
      <MyAvatarUploader :value="value" @change="set" />
    </template>

    <template #actions="{ validate }">
      <VxButton @click="validate()">Submit</VxButton>
    </template>
  </VxDynamicForm>
</template>

Props

Prop	Type	Default	Description
fields	DynamicFormField[]	required	Field schema array
model	Record<string, any>	—	Reactive model (auto-created if omitted)
rules	FormRules	—	Form-level rules (merged with per-field)
columns	number	0	Grid columns (0 = no grid)
gutter	number	16	Grid gap in px
layout	'vertical' | 'horizontal' | 'inline'	'vertical'	Form layout
labelWidth	string | number	—	Label width for horizontal layout
labelAlign	'left' | 'right'	'right'	Label text alignment
labelSuffix	string	''	Suffix after labels
size	'sm' | 'default' | 'lg'	'default'	Form size
disabled	boolean	false	Disable entire form
loading	boolean	false	Loading state
showRequiredMark	boolean	true	Show required asterisk
requiredMarkPosition	'left' | 'right'	'left'	Asterisk position
validateOnChange	boolean	true	Auto-validate on change
validateOnBlur	boolean	true	Auto-validate on blur
hideErrorMessage	boolean	false	Hide error messages
scrollToError	boolean	false	Scroll to first error
statusIcon	boolean	false	Show status icons
showAllErrors	boolean	false	Show all rule errors

DynamicFormField

Property	Type	Description
field	string	Field key — supports dot notation (user.name)
label	string	Label text
type	DynamicFormFieldType	Input type (see table below)
placeholder	string	Placeholder text
rules	FormRule | FormRule[]	Validation rules
required	boolean	Force required mark
help	string	Help text below field
description	string	Tooltip on label
dependencies	string[]	Re-validate when these change
defaultValue	any	Default value
options	{ label, value }[]	For select, radio, checkbox, segment, autocomplete, transfer
rows	number	Textarea rows
disabled	boolean	Disable this field
readonly	boolean	Read-only this field
hidden	boolean | (model) => boolean	Conditionally hide
span	number	Column span in grid mode
mask	string	Input mask pattern (###-####, +# (###))
regex	RegExp	Restrict input to regex matches
clearable	boolean	Show clear button
maxlength	number	Max character length
showWordLimit	boolean	Show word count
trim	boolean	Auto-trim whitespace
lazy	boolean	Update on blur only
debounce	number	Debounce input (ms)
currencyOptions	object	Currency format { prefix, suffix, decimal, thousands, precision }
props	Record<string, any>	Pass-through to underlying component
component	Component	Custom component (when type: 'custom')

Field Types

Type	Component	Notes
text (default)	VxInput	Supports mask, regex, trim, lazy, debounce
password	VxInput type="password"
textarea	VxInput type="textarea"	Supports rows, maxlength, showWordLimit
number	VxInput
email	VxInput
search	VxInput type="search"
tel	VxInput	Best with mask for phone patterns
url	VxInput
select	VxSelect	Needs options
checkbox	VxCheckbox	Single boolean; placeholder used as label
checkbox-group	VxCheckboxGroup	Needs options
radio / radio-group	VxRadioGroup	Needs options
switch	VxSwitch
slider	VxSlider	Pass min, max, showInput via props
rating	VxRating	Pass allowHalf, showValue via props
date	VxDatePicker
date-range	VxDateRangePicker
date-time	VxDateTimePicker
time	VxTimePicker
color	VxColorPicker	Pass showInput, presets via props
currency	VxCurrencyInput	Configure via currencyOptions
autocomplete	VxAutocomplete	Pass string[] or option objects
segment	VxSegment	Needs options
transfer	VxTransfer	Needs options (as data)
upload	VxUpload	Configure via props
custom	Your component	Set component prop

Exposed Methods

Method	Signature	Description
validate	() => Promise<{ valid, errors }>	Validate all fields
validateFields	(fields: string[]) => Promise<{ valid, errors }>	Validate specific fields
resetFields	() => void	Reset validation state
clearValidation	(fields?: string[]) => void	Clear errors
getModel	() => Record<string, any>	Deep copy of current model

Slots

Slot	Props	Description
actions	{ validate, reset, model }	Form actions (buttons)
[field]	{ field, value, set }	Override any field's rendering