Component Configuration Items

The following configuration options apply to each object in the config array.

config.type

The type field controls which modules Formkit loads. Field type: String. Valid values for type are described below.

Type	Valid Values	Default
String	See Formkit Modules	-

config.label

Form item label, type: String

<formkit
    :config="[
        {
            type: 'input',
            label: 'Here is the label',
            key: 'labelTestKey'
        }
    ]"
    v-model="dataset">
</formkit>

config.key

Form item binding key value, type: String

Form item current binding key value for testKey:

<formkit
    :config="[
        {
            type: 'input',
            key: 'testKey'
        }
    ]"
    v-model="dataset">
</formkit>
<p>Form item current binding key value for testKey: {{ dataset.testKey }}</p>

The props field is a custom property. Note that this field accepts data of type Object. If config.props is not empty, Formkit will use v-bind to bind config.props to all modules, including custom modules you register using the registerModule method.

Type	Optional Values	Default
Object	See the description below	{}

If you need to modify the native element-plus form component attributes, you can directly write them in the props field. For example:

To modify the clear-icon, placeholder, and maxlength attributes of element-plus input attributes, you can do the following:

<formkit
    :config="[
        {
            type: 'input',
            label: 'Name',
            key: 'name',
            props: { placeholder: 'Please enter name', clearable: true, maxlength: 10 }
        }
    ]"
    v-model="dataset">
</formkit>

value-key

Type	Default
String	id

As the unique identifier key name for value, you may need to specify it when config.options is an array type or when the config.requester returns an array type.

输出:

<formkit
    :config="[
        {
            type: 'select',
            label: 'Select Student',
            key: 'studentid',
            props: { placeholder: 'Please select student', clearable: true, valueKey: 'studentid' },
            options: [
                { name: 'Student One', studentid: 1 },
                { name: 'Student Two', studentid: 2 },
                { name: 'Student Three', studentid: 3 }
            ]
        }
    ]"
    v-model="dataset">
</formkit>

Output: {{ dataset.studentid }}

label-key

Type	Default
String	name

Specify the label of the option node in the data source of the option as the property value of the node object, when config.options is an array type or when the config.requester returns an array type. You may need to specify it.

<formkit
    :config="[
        {
            type: 'select',
            label: 'Select Student Name',
            key: 'studentname',
            props: { placeholder: 'Please select student name', clearable: true, labelKey: 'studentname' },
            options: [
                { studentname: 'Student One', id: 1 },
                { studentname: 'Student Two', id: 2 },
                { studentname: 'Student Three', id: 3 }
            ]
        }
    ]"
    v-model="dataset">
</formkit>

config.hint

The hint message for the current form field; the default value is empty. Type: String | HTML String

<formkit
    :config="[
        {
            type: 'input',
            label: 'Name',
            key: 'nameHint',
            hint: 'This is the form field hint message',
            props: { placeholder: 'Please enter your name', clearable: true }
        }
    ]"
    v-model="dataset">
</formkit>

config.disabled

Whether the current form field is disabled; default value: false; type: Boolean

<formkit
    :config="[
        {
            type: 'input',
            label: 'Name',
            key: 'nameDisabled',
            disabled: true,
            props: { placeholder: 'Please enter your name', clearable: true }
        }
    ]"
    v-model="dataset">
</formkit>

config.span

The number of columns occupied by the current form item. The default value is 24. Type: Number

Formkit will automatically adjust the module width based on the config.span value. For example, when config.span is 12, the module width is 12/24.

If columns is set, the config.span value will default to an integer multiple of columns. For example, when columns is 2, the config.span value is 12, and the module width is 12/24.

The number of columns occupied by the current form item cannot exceed 24; otherwise, it will not work.

<formkit
    :config="[
        {
            type: 'input',
            label: 'Name1',
            key: 'name1',
            span: 8,
            props: { placeholder: 'Please enter your name1', clearable: true }
        },
        {
            type: 'input',
            label: 'Name2',
            key: 'name2',
            span: 8,
            props: { placeholder: 'Please enter your name2', clearable: true }
        },
        {
            type: 'input',
            label: 'Name3',
            key: 'name3',
            span: 8,
            props: { placeholder: 'Please enter your name3', clearable: true }
        },
        {
            type: 'input',
            label: 'Name4',
            key: 'name4',
            span: 24,
            props: { placeholder: 'Please enter your name4', clearable: true }
        }
    ]"
    v-model="dataset">
</formkit>

config.labelWidth

Current form item label width, default value is 120px, type: String

By default, FormKit will automatically adjust the label width according to labelWidth Attribute. This does not conflict with labelWidth Attribute, as FormKit prioritizes the config.labelWidth value.

config.events

Event field, used to listen to module events, type: Object

<formkit
    :config="[
        {
            type: 'input',
            label: 'Name',
            key: 'password',
            props: { placeholder: 'Please enter name', clearable: true },
            events: {
                'mouseenter': (event) => {
                    console.log('Mouse enter event:', event);
                }
            }
        }
    ]"
    v-model="dataset">
</formkit>

Warning

The current function must return a Promise object, otherwise it will fail.

config.handler

Handler function used to process data returned by the requester. The handler serves as an additional auxiliary field. After the requester completes, the module will invoke the handler with the return value as an argument. The handler's return value ultimately becomes the module's data source. Type: Function

template

<formkit
    :config="[
        {
            type: 'select',
            label: 'Remotely retrieve radio button option data',
            key: 'requesterSelect',
            props: {
                labelKey: 'name',
                valueKey: 'id',
                placeholder: 'Please select an option'
            },
            requester: () => {
                // return useAxios().get('/default/xxx')
                return fetchOptions()
            },
            handler: (response: any) => response?.items || []
        }
    ]"
    v-model="dataset">
</formkit>

script

<script setup lang="ts">
import formkit from 'element-plus-formkit';
import { ref, computed } from 'vue';

const dataset = ref({})

function fetchOptions() {
    return new Promise((r, j) => {
        setTimeout(() => {
           r({
            code: 200,
            items: [
                { name: 'Option One', id: 1 },
                { name: 'Option Two', id: 2 },
                { name: 'Option Three', id: 3 }
            ]
           })
        }, 2000)
    })
}
</script>

config.visible

visible field is used to control whether the current item is visible, of course you can also use it to complete complex form linkage effects.

Type	Description	Example
undefined	The current item is not visible	-
Boolean	`true`: The current item is visible; `false`: The current item is not visible	`visible: true`
Object	You need to set the `visible` object type in a fixed format, see the FormKit Visible Object table below for details.	`visible: { key: 'name', value: 1 }`
Array	Multiple `visible` Object type validations, as long as one of them is met, the current item is visible.	`visible: [{ key: 'name', value: 1 }, { key: 'name', value: 2 }]`

FormKit Visible Object

When the visible is of type Object, you need to specify the key and value values.

key

Type	Description
String	The key of the Formkit component v-model binding value.

value

Type	Description
Any	The value of the Formkit component v-model binding value key.

Warning

When the visible is of type Object, the current Formkit component v-model binding key value is equal to the specified value value, then the current item is visible, otherwise it is not visible.

html

<formkit
    :config="visibleExampleConfig"
    v-model="dataset">
</formkit>

script

<script setup lang="ts">
import formkit from 'element-plus-formkit';
import { ref, computed } from 'vue';

const dataset = ref({})

const visibleExampleConfig = computed(() => [
    {
        type: 'switch',
        label: 'Boolean-type visible item switch',
        key: 'switchValue',
        props: {
            'inline-prompt': true,
            'active-text': 'true',
            'inactive-text': 'false'
        }
    },
    { type: 'input', label: 'Boolean-type item visible when true', key: 'booleans', visible: dataset.value.switchValue, disabled: true },
    {
        type: 'radio',
        label: 'Visible item selector',
        key: 'radioValue',
        options: [
            { name: 'Array-type item visible', id: 1 },
            { name: 'Array-type item and object-type item visible', id: 2 },
            { name: 'Both not visible', id: 3 }
        ]
    },
    { type: 'input', label: 'Object-type item visible when 2', key: 'objects', visible: { key: 'radioValue', value: 2 }, disabled: true },
    {
        type: 'input',
        label: 'Array-type item visible when 1',
        key: 'arrays',
        visible: [
            { key: 'radioValue', value: 1 },
            { key: 'radioValue', value: 2 }
        ],
        disabled: true 
    }
])
</script>

config.rules

Form element validation rule set. For specific validation parameters, please refer to ElementPlus Form Validation.

<formkit
    v-model="dataset"
    :config="[
        {
            type: 'input',
            label: 'Input number',
            rules: [
                { required: true, message: 'Input number cannot be empty' }
            ],
            key: 'input',
            props: {
                placeholder: 'Please input number'
            }
        }
    ]"
/>

Combined with the component to implement complete form item validation, refer to Expose