• Encapsulated based on NForm

Basic Usage

vue

<template>
  <FormPro ref="formPro" v-model="modelValue" :form-config="formConfig">
    <template #operation>
      <n-flex>
        <n-button type="primary" @click="submit">Submit</n-button>
        <n-button @click="reset">Reset</n-button>
      </n-flex>
    </template>
  </FormPro>
</template>

<script lang="ts" setup>
/** Form field types */
interface FormFields {
  name?: string;
  age?: number;
}

/** Form configuration */
const formConfig: FormPro.FormItemConfig[] = [
  { name: "name", label: "Name" },
  { name: "age", label: "Age", component: "number" },
];

/** Form data */
const modelValue = ref<FormFields>({});

/** Form instance */
const formProRef = useTemplateRef("formPro");

/** Submit */
const submit = async () => {
  await formProRef.value?.validate(); // Validate
  console.log("Form submitted:", modelValue.value);
};

const reset = () => formProRef.value?.reset();
</script>

Form Validation

• Pass rules in form-props to enable form validation.
• Supports all Form Props parameters except model.

vue

<template>
  <FormPro
    ref="formPro"
    v-model="modelValue"
    :form-config="formConfig"
    :form-props="formProps"
  >
    ...
  </FormPro>
</template>

<script lang="ts" setup>
import { type FormProps } from "naive-ui";

/** Form validation */
const formProps: FormProps = {
  rules: {
    name: [{ required: true, message: "Please enter your name" }],
    age: [{ required: true, message: "Please enter your age" }],
  },
};
</script>

Form Item Configuration

You can configure props, slots, and formItemProps for each form item individually.

⚠️ Note

props and slots depend on the component you use.

• If component is not set, the default is NInput's Input-Props and Input-Slots.
  
• If component is set to select, only NSelect props and slots are available.
• Even if you don't know what configurations are available for each component's props and slots, you don't need to worry as there will be TS prompts. If code prompts don't appear, simply type " to list all available properties. Or visit the Naïve UI official website to view them.

formItemProps accepts all FormItem and GridItem props except path, span, and label.

/** Form configuration */
const formConfig: FormPro.FormItemConfig[] = [
  {
    name: "name",
    label: "Name",
    props: {
      // Custom attribute
      placeholder: "Please enter your name",
    },
    // Render slots
    slots: {
      // prefix: () => <NEl>😁</NEl>, // Using tsx
      prefix: () => [h(NEl, {}, () => "😁")],
      suffix: () => [h("span", null, "😎")],
    },
    // Form item configuration
    formItemProps: {
      showFeedback: false,
    },
  },
  { name: "age", label: "Age", component: "number" },
];

Dynamic Data

In some cases, such as when options are fetched from an API, you can use computed to return the configuration.

import { type SelectOption } from "naive-ui";

onMounted(async () => {
  loading.value = true;
  options.value = await asyncOptions();
  loading.value = false;
});

/** Default options */
const options = ref<SelectOption[]>([{ label: "Eat", value: 1 }]);

/** Option loading state */
const loading = ref(false);

/** Simulate fetching dynamic options */
const asyncOptions = () => {
  return new Promise<SelectOption[]>((resolve) =>
    setTimeout(
      () =>
        resolve([
          { label: "Eat", value: 1 },
          { label: "Sleep", value: 2 },
          { label: "Play games", value: 3, disabled: true },
        ]),
      2000
    )
  );
};

/** Form configuration */
const formConfig = computed((): FormPro.FormItemConfig[] => [
  {
    name: "hobby",
    label: "Hobby",
    component: "select",
    props: {
      multiple: true, // Enable multiple selection
      loading: loading.value, // Loading state
      options: options.value, // Dynamic options
    },
  },
]);

Dynamic Show/Hide

If you need to show or hide a form item based on certain conditions, use the hidden property.

/** Form data */
const modelValue = ref<FormFields>({
  age: 18,
});

/** Form configuration */
const formConfig = computed((): FormPro.FormItemConfig[] => [
  { name: "age", label: "Age", component: "number" },
  {
    name: "hobby",
    label: "Hobby",
    component: "select",
    hidden: modelValue.value.age <= 18,
    props: {
      multiple: true, // Enable multiple selection
      loading: loading.value, // Loading state
      options: options.value, // Dynamic options
    },
  },
]);

Using Dictionary

If you need to use dictionary data as a data source, add the dict property to the form item configuration and specify the dictionary key. The data source will be automatically fetched from the dictionary.

⚠️ Note

Currently, only select, radio, and checkbox components support dictionaries.
If the options property is set in props, the dict property will be ignored.

/** Form configuration */
const formConfig: FormPro.FormItemConfig[] = [
  {
    name: "sex",
    label: "Gender",
    component: "select",
    dict: "gender", // Use dictionary
  },
];

Using Slots

If you need to use custom slots for rendering, you can do so as follows:

💡 Note

• The slot name must match the name property in the form-config.
• Slot content takes priority and will override the component property.

vue

<template>
  <FormPro v-model="modelValue" :form-config="formConfig">
    <!-- Custom slot -->
    <template #name>Custom content</template>
  </FormPro>
</template>

<script lang="ts" setup>
const formConfig: FormPro.FormItemConfig[] = [
  {
    name: "name",
    label: "Name",
    // The component property is ignored when using a slot
    component: "input", 
  },
];
</script>

Custom Component

• Some users may ask: "What if I want to render my own custom component?"
• Of course you can!

💡 Note

The component property can accept not only basic component types, but also a function that returns a component, or you can directly pass a component object.

/** Simple component to render msg info */
const MyComponent = defineComponent({
  props: {
    msg: { type: String, default: "Default message" },
  },
  setup(props) {
    return () => h("div", props.msg);
  },
});

/** Form configuration */
const formConfig: FormPro.FormItemConfig[] = [
  {
    name: "msg",
    label: "Message",
    // component: () => <MyComponent msg="hello" />, // Using tsx
    component: () => h(MyComponent, { msg: "hello" }), // Using h function
  },
];

Props

Name	Type	Required	Default	Description
v-model or model-value	object	No		Form binding data
operation-span	number	No	4	Operation column width
form-config	FormItemConfig[]	No		Form item configuration
form-props	FormProps	No	see below	Form properties (except model)
grid-props	GridProps	No	see below	Form layout properties

• form-props default: { labelPlacement: "left", labelWidth: 80 }
• grid-props default: { xGap: 16 }

FormItemConfig

Name	Type	Required	Default	Description
name	string	Yes		Field name
label	string	No		Label (not shown if not set)
span	number	No	4	Grid width
dict	string	No		Dictionary
hidden	boolean	No	false	Whether hidden
label-message	string	No		Tip message
label-reverse	boolean	No	false	Reverse label layout
block-message	string	No		Block message
component	component Type	No	input	Component
props	component Props	No	{}	Component props
slots	component Slots	No	{}	Component slots
form-item-props	FormItemGi Props	No	{}	FormItemGi props

💡 Note

• label-reverse defaults to false, with the prompt information in front and the label behind; when true, the prompt information is behind and the label is in front.

• block-message supports both Component and () => VNode types. This configuration is invalid in TablePro for aesthetic reasons, please use label-message instead

• form-item-props excludes path, label, and span properties.

Component Types

Supported component types:

• input Input
• textarea Textarea
• number Number input
• password Password input
• select Select
• radio Radio group
• radio-button Radio button group
• checkbox Checkbox group
• date Date picker
• time Time picker
• switch Switch
• tree-select Tree select
• color-picker Color picker
• slider Slider
• text Plain text
• Component Custom component
• () => VNode Custom component

Component Props and Slots

Component	Props	Slots
input textarea password	Input Props	Input Slots
select	Select Props	Select Slots
radio radio-button	RadioGroup Props	undefined
checkbox	Checkbox Props	Checkbox Slots
date	DatePicker Props	DatePicker Slots
time	TimePicker Props	TimePicker Slots
switch	Switch Props	Switch Slots
tree-select	TreeSelect Props	TreeSelect Slots
color-picker	ColorPicker Props	ColorPicker Slots
slider	Slider Props	Slider Slots
text	Text Props	Text Slots

Slots

Name	Params	Description
operation	()	Operation area buttons
[name]	()	Form item slot

Expose

Name	Type	Description
validate	() => Promise<void>	Trigger validation
reset	() => void	Reset form

Contributors

nuyoah

Changelog

Last edited 2 months ago

View full history

c31a643-docs(en/form-pro): Optimize component property descriptions

53b5836-feat(en/form-pro): Add the label-reverse attribute to reverse the label

60804f3-docs(en/form-pro): Add the properties and slot descriptions of the slider component

ca38cdc-docs(en/form-pro): Add color selection box component support

c72a55a-docs(form-pro): Update component type descriptions and property links

35a2dda-docs(form-pro): Add radio-button component type description

78595ce-fix(en/form-pro): Fixed the link address error

83d5b5e-feat(form-Pro): Add the block-message property and optimize form validation

84a9cad-docs(en/form-pro): Additional Instructions for Using Custom Components

e51aec5-docs(form-pro): update component documentation title

1b7ac77-refactor(en): FormPro component and documentation

b4eb45c-docs(en): Add a trailing blank line

eb9fd23-docs(en): Add FormPro component documentation