@formitiva/vue

Vue 3 adapter for Formitiva — build dynamic, schema-driven forms with a single component.

Features

• Single component — render any form from a JSON schema with <Formitiva />
• Vue 3 Composition API — composables for context, validation, debouncing, and more
• 25+ built-in field types — text, email, phone, dropdown, date, file, rating, slider, unit values, and more
• Dynamic validation — onEdit, onBlur, or onSubmission modes with built-in and custom validators
• Conditional visibility — show/hide fields based on other field values via parent-child relationships
• Computed values — derive field values from other fields automatically
• Plugin system — register custom components, validators, submission handlers, and visibility rules
• Theming — CSS variable-based theming with light/dark support
• Localization — 29+ languages with CDN-based translation loading
• TypeScript — fully typed API

Installation

npm install @formitiva/vue
# or
pnpm add @formitiva/vue

Peer dependencies: vue >=3.3

Quick Start

<script setup lang="ts">
import { Formitiva } from "@formitiva/vue";

const definition = {
  name: "contactForm",
  version: "1.0.0",
  displayName: "Contact Form",
  properties: [
    { name: "fullName", displayName: "Full Name", type: "text", defaultValue: "", required: true },
    { name: "email", displayName: "Email", type: "email", defaultValue: "", required: true },
    { name: "message", displayName: "Message", type: "multiline", defaultValue: "" },
  ],
};

const handleSubmit = (_def: any, _instanceName: any, values: any) => {
  console.log("Submitted:", values);
  return undefined;
};
</script>

<template>
  <Formitiva :definition-data="definition" :on-submit="handleSubmit" />
</template>

Props

| Prop | Type | Default | Description | |---|---|---|---| | definitionData | string \| object \| FormitivaDefinition | — | Form schema (JSON string, object, or typed definition) | | instance | FormitivaInstance | — | Optional saved instance with pre-filled values | | language | string | "en" | Language code for localization | | theme | string | "light" | Theme name ("light" or "dark") | | fieldValidationMode | FieldValidationMode | "onEdit" | When to validate: "onEdit", "onBlur", or "onSubmission" | | displayInstanceName | boolean | true | Show an editable instance name field | | onSubmit | FormSubmissionHandler | — | Callback on form submission | | onValidation | FormValidationHandler | — | Cross-field validation callback | | className | string | — | Additional CSS class for the container | | style | object | — | Inline styles for the container |

Composables

| Composable | Description | |---|---| | useFormitivaContext() | Access the current form context (language, theme, t, etc.) via provide/inject | | useFieldValidator(field) | Returns a validation function respecting the current validation mode | | useDebouncedCallback(fn, wait) | Debounced callback with leading/trailing options | | useUncontrolledValidatedInput(props) | Manages uncontrolled inputs with validation and DOM sync | | useDropdownPosition(ref) | Calculates safe popup positioning for dropdowns | | useUnitValueField(props) | Manages unit value state with normalization |

Extending

Custom Components

import { registerComponent } from "@formitiva/vue";

registerComponent("my-custom-field", MyCustomFieldComponent);

Custom Validators

import { registerFieldValidator, registerTypeValidator } from "@formitiva/vue";

// Per-definition field validator
registerFieldValidator("myForm", "validateAge", (fieldName, value, t) => {
  if (Number(value) < 18) return t("Must be at least 18");
  return undefined;
});

// Global type validator
registerTypeValidator("currency", (field, input, t) => {
  if (Number.isNaN(Number(input))) return t("Must be a valid number");
  return undefined;
});

Plugins

import { registerPlugin } from "@formitiva/vue";

registerPlugin({
  name: "my-plugin",
  version: "1.0.0",
  components: { "my-field": MyFieldComponent },
  fieldTypeValidators: { "my-field": myValidator },
});

Themes

Import a built-in theme CSS file from @formitiva/core:

import "@formitiva/core/themes/material-dark.css";

Or customize via CSS variables:

:root {
  --formitiva-color-primary: #3b82f6;
  --formitiva-color-error: #ef4444;
  --formitiva-border-radius: 8px;
}

Links

• Documentation
• Visual Form Builder
• GitHub
• Monorepo README

License

MIT