Retts Dynamic Form

A powerful Vue 3 dynamic form builder with base components library, built with PrimeVue and VeeValidate.

Features

• 🎨 Dynamic Form Generation - Create forms dynamically from configuration
• 🧩 Rich Component Library - 35+ pre-built base components
• ✅ Form Validation - Built-in validation with VeeValidate
• 🎯 Type Safety - Full TypeScript support
• 🚀 PrimeVue Integration - Leverages PrimeVue component library
• � Tree-shakeable - Import only what you need
• 🔌 Plugin System - Easy validator setup with Vue plugins
• �📝 Field Types - Support for text, select, date, file upload, signature pad, rich text editor, code editor, and more

Installation

npm install retts-dynamic-form

Required Peer Dependencies

npm install vue@^3.5 primevue@^3.53 primeicons@^7.0 vee-validate@^4.13

Optional Dependencies (for specific features)

# For validation rules and i18n
npm install @vee-validate/rules @vee-validate/i18n

# For styling
npm install primeflex@^3.3

# For TinyMCE editor
npm install @tinymce/tinymce-vue tinymce

# For Code editor
npm install vue-codemirror6 @codemirror/lang-javascript @codemirror/lang-json

# For signature pad
npm install signature_pad

Quick Start

1. Setup PrimeVue and Services

In your main.ts:

import { createApp } from 'vue'
import PrimeVue from 'primevue/config'
import ToastService from 'primevue/toastservice'
import DialogService from 'primevue/dialogservice'
import ConfirmationService from 'primevue/confirmationservice'

// Import PrimeVue styles
import 'primevue/resources/themes/lara-light-blue/theme.css'
import 'primeicons/primeicons.css'

// Import component styles
import 'retts-dynamic-form/style.css'

import App from './App.vue'

const app = createApp(App)

app.use(PrimeVue)
app.use(ToastService)
app.use(DialogService)
app.use(ConfirmationService)

app.mount('#app')

2. Setup Validators (Optional but Recommended)

import { createApp } from 'vue'
import { ValidatorPlugin } from 'retts-dynamic-form'

const app = createApp(App)

// Install all validation rules (built-in + custom)
app.use(ValidatorPlugin)

// Or with options
app.use(ValidatorPlugin, {
  installBuiltInRules: true,  // Install @vee-validate/rules (default: true)
  installCustomRules: true,   // Install custom validators (default: true)
  i18n: yourI18nInstance,     // Optional: for translated error messages
  locales: { en, id }         // Optional: VeeValidate locales
})

3. Use in Your Components

<template>
  <DynamicForm
    :form-state="formState"
    :schema="formSchema"
    @handle-submit="handleSubmit"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { DynamicForm, initialFormState } from 'retts-dynamic-form'
import type { FormSchemaWithFields, IFormState } from 'retts-dynamic-form'

const formState = ref<IFormState>(initialFormState)

const formSchema: FormSchemaWithFields = {
  fields: [
    {
      name: 'username',
      component: 'BaseInputText',
      label: 'Username',
      rules: 'required|min:3',
      componentProps: {
        placeholder: 'Enter your username'
      }
    },
    {
      name: 'email',
      component: 'BaseInputText',
      label: 'Email',
      rules: 'required|email',
      componentProps: {
        type: 'email'
      }
    },
    {
      name: 'password',
      component: 'BasePassword',
      label: 'Password',
      rules: 'required|min:8'
    }
  ]
}

const handleSubmit = (data: any) => {
  console.log('Form submitted:', data)
}
</script>

Usage Examples

Import Styles

// Main CSS (required)
import 'retts-dynamic-form/style.css'

Import Components

// Option 1: Import from main entry
import { 
  DynamicForm,
  DynamicField,
  BaseInputText,
  BaseButton,
  BaseDropdown
} from 'retts-dynamic-form'

// Option 2: Import specific components via subpath exports
import DynamicForm from 'retts-dynamic-form/dynamicform'
import BaseInputText from 'retts-dynamic-form/baseinputtext'
import BaseButton from 'retts-dynamic-form/basebutton'

// Option 3: Import types
import type { 
  FormSchemaWithFields,
  IFormField,
  IFormState 
} from 'retts-dynamic-form/types'

Using Base Components Directly

<template>
  <div>
    <BaseInputText
      v-model="username"
      label="Username"
      placeholder="Enter username"
    />
    
    <BaseDropdown
      v-model="country"
      :options="countries"
      label="Country"
      option-label="name"
      option-value="code"
    />
    
    <BaseButton
      label="Submit"
      icon="pi pi-check"
      @click="handleSubmit"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { BaseInputText, BaseDropdown, BaseButton } from 'retts-dynamic-form'

const username = ref('')
const country = ref('')
const countries = ref([
  { name: 'United States', code: 'US' },
  { name: 'Indonesia', code: 'ID' }
])

const handleSubmit = () => {
  console.log({ username: username.value, country: country.value })
}
</script>

Available Components

Dynamic Form Components

• DynamicForm - Main dynamic form component with validation
• DynamicField - Individual field renderer
• DynamicFailMsg - Validation error message display

Base Input Components

• BaseInputText - Text input field
• BaseTextArea - Multi-line text area
• BaseInputNumber - Number input with formatting
• BasePassword - Password input with visibility toggle
• BaseInputMask - Masked input (phone, date, etc.)
• BaseInputOTP - One-time password input
• BaseInputChips - Tag/chip input
• BaseInputSwitch - Toggle switch
• BaseInputFile - File upload with preview

Base Selection Components

• BaseDropdown - Single select dropdown
• BaseMultiSelect - Multi-select dropdown
• BaseAutoComplete - Autocomplete/typeahead
• BaseListBox - List selection
• BaseCascadeSelect - Cascading select
• BaseTreeSelect - Tree structure select
• BaseCheckbox - Checkbox input
• BaseRadioButton - Radio button input
• BaseSelectButton - Toggle button group
• BaseToggleButton - Single toggle button

Base Date/Time Components

• BaseCalendar - Date/time picker

Base UI Components

• BaseButton - Action button
• BaseSlider - Range slider
• BaseKnob - Circular knob input
• BaseRating - Star rating input
• BaseColorPicker - Color selection

Advanced Components

• BaseSignaturePad - Signature capture canvas
• BaseTextEditor - Rich text WYSIWYG editor (TinyMCE)
• BaseCodeEditor - Code editor with syntax highlighting (CodeMirror)
• BaseCronInput - Cron expression builder
• BaseFieldArray - Dynamic field array/repeater
• BaseInputGroup - Grouped inputs with addons
• BaseTabs - Tabbed form sections

Validation

Built-in Validators

The package includes VeeValidate integration with common validation rules:

• required - Field is required
• email - Valid email format
• min:3 - Minimum length
• max:10 - Maximum length
• confirmed - Match another field
• phone - Valid phone number
• url - Valid URL
• And all @vee-validate/rules

Custom Validators

You can add custom validators:

import { defineRule } from 'retts-dynamic-form'

defineRule('customRule', (value: any) => {
  if (value === 'expected') {
    return true
  }
  return 'Value must be "expected"'
})

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type { 
  // Form types
  FormSchemaWithFields,
  FormSchemaWithTabs,
  IFormField,
  IFormState,
  IFormTabsModes,
  
  // Component props
  IMessage,
  SignaturePadProps,
  
  // Helpers
  formatPhoneNumber,
  capitalizeFirstLetter
} from 'retts-dynamic-form'

Exports

Subpath Exports

All components are available via subpath exports:

// Components
import DynamicForm from 'retts-dynamic-form/dynamicform'
import BaseInputText from 'retts-dynamic-form/baseinputtext'
import BaseButton from 'retts-dynamic-form/basebutton'
// ... and all other components

// Types
import type { FormSchemaWithFields } from 'retts-dynamic-form/types'

// Validators
import { ValidatorPlugin } from 'retts-dynamic-form/validators'

// Styles
import 'retts-dynamic-form/style.css'

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and feature requests, please use the GitHub issue tracker.