PxSchemaForm

A fully schema-driven form engine. Renders a flat array of field definitions — text, number, date, select, checklists, and more — into a responsive grid. Powers Praxis's form builder.

Usage

Demo

First Name *

Last Name *

Date of Birth

Gender

Select...

Form Data: { "first_name": "", "last_name": "", "dob": "", "gender": "" }

<script setup>
import { ref } from 'vue'
import { PxSchemaForm } from 'praxis-vue-ui'

const schema = [
  { key: 'first_name', label: 'First Name', type: 'text', required: true },
  { key: 'last_name', label: 'Last Name', type: 'text', required: true },
  { key: 'dob', label: 'Date of Birth', type: 'date' },
  {
    key: 'gender',
    label: 'Gender',
    type: 'select',
    options: [
      { label: 'Male', value: 'male' },
      { label: 'Female', value: 'female' },
    ],
    option_source: { label_field: 'label', value_field: 'value' },
  },
]

const formData = ref({})
</script>

<template>
  <PxSchemaForm :schema="schema" v-model="formData" :zod-schema="myZodSchema" />
</template>

Zod Integration

You can natively validate the schema using Zod. Just pass a zod-schema prop to the component and PxSchemaForm will internally wrap the fields inside a Vee-Validate <Form> that processes your schema safely.

import { z } from 'zod';

const myZodSchema = z.object({
  first_name: z.string().min(2, "Must be at least 2 characters"),
  last_name: z.string().min(2, "Must be at least 2 characters")
});

Props

Prop	Type	Default	Description
schemarequired	FormSchemaField[]	—	Flat array of field definitions to render.
modelValue	Record<string, any>	{}	Current form data, keyed by field.key. Use with v-model.
existingData	Record<string, unknown>	undefined	Pre-existing values used to initialize fields not yet present in modelValue.
loading	boolean	false	Passed down to select-type fields to show a loading state.
cleanedResults	string[]	[]	v-model:cleanedResults — tracks keys touched by multiselect_list fields.
calculatedNumbers	any[]	[]	v-model:calculatedNumbers — tracks fields of type calculated_number.
zodSchema	ZodSchema<any>	undefined	A Zod schema for automatic type-safe form validation using Vee-Validate.

FormSchemaField Interface

interface FormSchemaField {
  key?: string
  label?: string
  type: 'text' | 'number' | 'integer' | 'double' | 'textarea' | 'select' | 'select_list'
      | 'multiselect_list' | 'date' | 'time' | 'checkbox' | 'row' | 'check_list'
      | 'check_list_input' | 'calculated_number' | 'divider_with_components' | 'hidden'
  required?: boolean
  value?: unknown
  placeholder?: string
  readonly?: boolean
  multiple?: boolean
  options?: unknown[]
  option_source?: { label_field?: string; value_field?: string; type?: string; search_field?: string }
  components?: FormSchemaField[]   // sub-fields for the 'row' type
  [key: string]: unknown
}

Emits

Event	Payload	Description
update:modelValue	Record<string, any>	Emitted on any field change with the updated form data.
update:cleanedResults	string[]	Emitted when multiselect_list selections change.
update:calculatedNumbers	any[]	Emitted when calculated_number fields change.
scroll-bottom	FormSchemaField	Emitted when a select-type field's dropdown is scrolled near the bottom, for pagination.
search	{ query: string, fieldKey: string }	Emitted when search input changes in searchable select-list fields.

NOTE

PxSchemaForm is the most complex component in the library. See PxFormRow, PxSchemaMultiSelect, and PxGridSelect for the sub-field types rendered by the row, multiselect_list, and select_list field types, respectively.