Getting Started with Formily

Formily is a powerful, unified form solution that provides a complete ecosystem for building complex forms in React applications.

What is Formily?

Formily is not just another form library - it’s a comprehensive form solution that includes:

• Core Libraries: Reactive state management and form logic
• UI Bridges: Framework-specific integrations (React, Vue)
• Component Ecosystem: Pre-built components for popular UI libraries
• Developer Tools: Form designer and Chrome extension

Architecture Overview

Formily follows the MVVM (Model-View-ViewModel) pattern:

• @formily/core: The core form state management engine
• @formily/react: React bridge for connecting UI components
• @formily/antd: Ant Design component integration
• Additional packages: Support for various UI libraries

Installation

Step 1: Install Core Library

The core library is essential for all Formily applications:

npm install --save @formily/core

Step 2: Install UI Bridge

For React applications:

npm install --save @formily/react

For Vue applications:

npm install --save @formily/vue

Step 3: Install Component Library

Choose based on your preferred UI library:

For Ant Design:

npm install --save antd @formily/antd

For Alibaba Fusion:

npm install --save @alifd/next @formily/next

Basic Usage

Let’s start with a simple example to understand Formily’s core concepts:

import React from 'react'
import { createForm } from '@formily/core'
import { FormProvider, FormConsumer, Field } from '@formily/react'
import {
  FormItem,
  FormLayout,
  Input,
  FormButtonGroup,
  Submit
} from '@formily/antd'

// Create form instance
const form = createForm()

export default () => {
  return (
    <FormProvider form={form}>
      <FormLayout layout="vertical">
        <Field
          name="input"
          title="Input Field"
          required
          initialValue="Hello Formily"
          decorator={[FormItem]}
          component={[Input]}
        />
      </FormLayout>

      <FormConsumer>
        {() => (
          <div style={{
            marginBottom: 20,
            padding: 5,
            border: '1px dashed #666'
          }}>
            Real-time value: {form.values.input}
          </div>
        )}
      </FormConsumer>

      <FormButtonGroup>
        <Submit onSubmit={console.log}>Submit</Submit>
      </FormButtonGroup>
    </FormProvider>
  )
}

Key Concepts Explained

1. Form Creation with createForm

The createForm function creates the core form model that manages:

• Form state
• Validation rules
• Field relationships
• Submission logic

const form = createForm({
  initialValues: {
    username: '',
    email: ''
  },
  validateFirst: true
})

2. FormProvider Component

FormProvider acts as the bridge between the form model and React components:

<FormProvider form={form}>
  {/* Your form fields go here */}
</FormProvider>

3. Field Component

The Field component is the building block for form fields:

<Field
  name="fieldName"           // Field path in form data
  title="Field Label"        // Display label
  required                   // Validation rule
  initialValue="default"     // Default value
  decorator={[FormItem]}     // UI wrapper component
  component={[Input]}        // Input component
/>

4. Decorator vs Component

• Decorator: Wraps the field with UI elements (labels, validation messages)
• Component: The actual input control (Input, Select, etc.)

// FormItem provides label, validation styling
decorator={[FormItem, { tooltip: 'Help text' }]}

// Input is the actual form control
component={[Input, { placeholder: 'Enter value' }]}

5. Reactive Updates with FormConsumer

FormConsumer enables reactive UI updates based on form state changes:

<FormConsumer>
  {(form) => (
    <div>
      Current values: {JSON.stringify(form.values)}
      Is valid: {form.valid ? 'Yes' : 'No'}
    </div>
  )}
</FormConsumer>

Advanced Features

Form Validation

Formily provides multiple validation approaches:

<Field
  name="email"
  title="Email"
  required
  validator="email"  // Built-in validator
  decorator={[FormItem]}
  component={[Input]}
/>

// Custom validation
<Field
  name="password"
  title="Password"
  validator={(value) => {
    if (value.length < 8) {
      return 'Password must be at least 8 characters'
    }
  }}
  decorator={[FormItem]}
  component={[Input.Password]}
/>

Dynamic Forms

Create dynamic forms that respond to user input:

<Field
  name="userType"
  title="User Type"
  decorator={[FormItem]}
  component={[Select]}
  dataSource={[
    { label: 'Admin', value: 'admin' },
    { label: 'User', value: 'user' }
  ]}
/>

<FormConsumer>
  {(form) => (
    form.values.userType === 'admin' && (
      <Field
        name="adminCode"
        title="Admin Code"
        required
        decorator={[FormItem]}
        component={[Input]}
      />
    )
  )}
</FormConsumer>

Form Layout

Control form layout with FormLayout:

<FormLayout
  layout="vertical"     // vertical, horizontal, inline
  size="large"          // small, medium, large
  colon={false}         // Hide colons after labels
>
  {/* Your fields */}
</FormLayout>

Best Practices

1. Form State Management

Keep form logic separate from component logic:

// forms/userForm.js
import { createForm } from '@formily/core'

export const createUserForm = () => createForm({
  initialValues: {
    name: '',
    email: '',
    role: 'user'
  },
  validateFirst: true
})

// components/UserForm.jsx
import { createUserForm } from '../forms/userForm'

const UserForm = () => {
  const form = useMemo(() => createUserForm(), [])

  return (
    <FormProvider form={form}>
      {/* Form fields */}
    </FormProvider>
  )
}

2. Reusable Field Components

Create reusable field components:

const EmailField = ({ name = 'email', required = true, ...props }) => (
  <Field
    name={name}
    title="Email Address"
    required={required}
    validator="email"
    decorator={[FormItem]}
    component={[Input, { placeholder: 'Enter email address', ...props }]}
  />
)

3. Form Submission Handling

Handle form submission properly:

const handleSubmit = async (values) => {
  try {
    await api.submitForm(values)
    message.success('Form submitted successfully!')
  } catch (error) {
    message.error('Submission failed: ' + error.message)
  }
}

<Submit onSubmit={handleSubmit} loading={submitting}>
  Submit Form
</Submit>

Ecosystem and Tools

Form Designer

Formily provides a visual form designer for building forms without code:

• Designable: Visual form builder
• Chrome Extension: Development tools for debugging
• Community Components: Extended component library

UI Library Support

Formily supports multiple UI libraries:

• Ant Design: @formily/antd and @formily/antd-v5
• Element UI: @formily/element and @formily/element-plus
• Fusion Design: @formily/next
• Mobile: @formily/antd-mobile, @formily/vant

Conclusion

Formily offers a powerful, scalable solution for form management in React applications. Its reactive architecture, comprehensive validation system, and extensive ecosystem make it an excellent choice for complex form requirements.

Key benefits include:

• Reactive State Management: Automatic UI updates based on form state
• Comprehensive Validation: Built-in and custom validation rules
• Rich Ecosystem: Support for popular UI libraries
• Developer Experience: Excellent tooling and documentation
• Performance: Optimized rendering and state updates

Whether you’re building simple contact forms or complex multi-step wizards, Formily provides the tools and flexibility needed to create exceptional form experiences.

Resources

• Official Documentation
• GitHub Repository
• Form Designer
• Community Forum

Start exploring Formily today and transform your form development experience!