README
Simple, lightweight, and flexible schema-based form for Vue.js
Features
𧽠Flexible: Easily to handle from basic to nested forms, group of forms...
βοΈ Dynamically: Generate form components dynamically.
π Schema: Build faster form by schema.
π Lightweight: Small built size. Gzip: ~5 KB
β Validation: Validate form elements with built-in Rules that covers most needs in most web applications
𧩠Plugins: Extend functionally by third-party plugins or your own plugins.
π΅ Extensibility: Easily to make your own custom form element by extending the core elements.
Links
Installation
CDN
You can use vue-formily with a script tag and a CDN, import the library like this:
<!-- vue 3.x -->
<script src="https://unpkg.com/@vue-formily/formily@next"></script>
<!-- vue 2.x -->
<script src="https://unpkg.com/@vue-formily/formily@latest"></script>
This will inject a VueFormily
global object, which you will use to access the various components, funtions exposed by vue-formily.
If you are using native ES Modules, there is also an ES Modules compatible build:
<script type="module">
// vue 3.x
import Vue from 'https://unpkg.com/@vue-formily/formily@next/dist/formily.esm.js'
// vue 2.x
import Vue from 'https://unpkg.com/@vue-formily/formily@latest/dist/formily.esm.js'
</script>
NPM
# install with yarn
# vue 3.x
yarn add @vue-formily/formily@next
# vue 2.x
yarn add @vue-formily/formily
# install with npm
# vue 3.x
npm install @vue-formily/formily@next --save
# vue 2.x
npm install @vue-formily/formily --save
Set Up
Vue 3.x
import { createApp } from 'vue'
import { createFormily } from '@vue-formily/formily';
const formily = createFormily();
const app = createApp(App)
app.use(formily, {
// By default, vue-formily will execute the
// validation silently when changing element's value.
// To disable it, just set the `silent` to `false`.
// When disabled, the element has to be validated manually
// by calling the `element.validate()` method.
silent?: boolean;
// The default rules want to apply to the form.
// With rules that have the `cascade = true`,
// then thay can apply to all the child elements.
rules: [];
// The alias of the object contains all the form references
// that will be injected to Vue instance
alias: 'forms';
});
Vue 2.x
import Vue from 'vue';
import { createFormily } from '@vue-formily/formily';
const formily = createFormily();
Vue.use(formily, {
// By default, vue-formily will execute the
// validation silently when changing element's value.
// To disable it, just set the `silent` to `false`.
// When disabled, the element has to be validated manually
// by calling the `element.validate()` method.
silent?: boolean;
// The default rules want to apply to the form.
// With rules that have the `cascade = true`,
// then thay can apply to all the child elements.
rules: [];
// The alias of the object contains all the form references
// that will be injected to Vue instance
alias: 'forms';
});
Vue Version Support
The main v2 version supports Vue 3.x only, for previous versions of Vue, check the following the table
Vue Version | vue-formily version |
---|---|
2.x |
1.x |
3.x |
2.x |
Basic Usage
Let's start with a simple login form:
Defining Form Schema
vue-formily
need a form schema to work with, so let's define one:
import { defineSchema } from '@vue-formily';
import { required, email } from "@vue-formily/rules";
const loginForm = defineSchema({
formId: 'login',
formType: 'group',
fields: [
{
formId: 'email',
formType: 'field',
type: 'string',
format: '{raw}',
value: '',
rules: [
{
...required,
message: 'Please enter email address.'
},
{
...email,
message: 'Please enter valid email address.'
}
],
props: {
label: 'email',
inputType: 'email'
}
},
{
formId: 'password',
formType: 'field',
type: 'string',
rules: [
{
...required,
message: 'Please enter password.'
}
],
value: '',
props: {
label: 'password',
inputType: 'password'
}
}
]
});
Create New Form
Then we call $formily.add
to create new form element and injects it to Vue instance's forms
object.
<template>
<form class="login">
<div v-for="(field, i) in forms.login.fields" :key="i" class="field">
<label :for="field.formId">{{ field.label }}</label>
<input v-model="field.raw" :type="field.props.inputType" :name="field.name" :id="field.formId" />
</div>
</form>
</template>
<script>
// Vue 2.x
export default {
created() {
// Create new form element and injects it to `forms` object.
this.$formily.add(loginForm);
}
}
// Vue 3.x
import { useFormily } from '@vue-formily';
export default {
setup() {
const formily = useFormily();
// Create newΓ₯ form element and injects it to `forms` object.
formily.add(loginForm);
}
}
</script>
Here is the live demo.
Contributing
You are welcome to contribute to this project, but before you do, please make sure you read the Contributing Guide.