# How to Integrate Formily with Ant Design: A Complete Developer Guide

> Integrate Formily with Ant Design using FormProvider and pre-wrapped components. Install packages and simplify your form development with this developer guide.

- Repository: [Alibaba/formily](https://github.com/alibaba/formily)
- Tags: how-to-guide
- Published: 2026-02-24

---

**To integrate Formily with Ant Design, install the `@formily/antd` package alongside `@formily/core` and `@formily/react`, then use `FormProvider` to supply the form context and render fields using the pre-wrapped Ant Design components.**

Integrating Formily with Ant Design allows you to build powerful, reactive forms using Alibaba's open-source form solution while leveraging Ant Design's comprehensive UI component library. This integration relies on three distinct layers: the core reactive engine, React bindings for context management, and the Ant Design UI layer that wraps native AntD components. By following the patterns established in the `alibaba/formily` repository, you can create everything from simple login forms to complex, schema-driven data entry interfaces.

## Installation and Dependencies

Before writing any components, you must install the required peer dependencies and Formily packages. The Ant Design integration requires `antd` and `moment` as peer dependencies, plus the three core Formily modules.

Run the following commands to set up your project:

```bash

# Install peer dependencies

npm install --save antd moment

# Install Formily core, React bindings, and AntD UI layer

npm install --save @formily/core @formily/react @formily/antd

```

As documented in [[`packages/antd/docs/index.md`](https://github.com/alibaba/formily/blob/main/packages/antd/docs/index.md)](https://github.com/alibaba/formily/blob/formily_next/packages/antd/docs/index.md#L26-L30), the `@formily/antd` package re-exports all Ant Design components wrapped with Formily's decorators, making them compatible with the form engine out-of-the-box.

## Creating the Form Instance

Every Formily form starts with a reactive form instance created by the core package. In [`packages/core/src/createForm.ts`](https://github.com/alibaba/formily/blob/main/packages/core/src/createForm.ts), the `createForm()` factory function initializes the form's state management, validation engine, and effect runners.

```tsx
import { createForm } from '@formily/core'

const form = createForm()

```

This `form` object acts as the single source of truth for all field values, validation states, and reactive effects. It is implemented in [[`packages/core/src/createForm.ts`](https://github.com/alibaba/formily/blob/main/packages/core/src/createForm.ts)](https://github.com/alibaba/formily/blob/formily_next/packages/core/src/createForm.ts) and provides methods for submitting, resetting, and querying field states.

## Setting Up the React Context

To make the form instance accessible throughout your component tree, wrap your application with `FormProvider` from `@formily/react`. This provider, defined in [[`packages/react/src/FormProvider.tsx`](https://github.com/alibaba/formily/blob/main/packages/react/src/FormProvider.tsx)](https://github.com/alibaba/formily/blob/formily_next/packages/react/src/FormProvider.tsx), injects the form instance into React's context API.

```tsx
import { FormProvider, FormConsumer } from '@formily/react'

<FormProvider form={form}>
  {/* Your form components here */}
</FormProvider>

```

`FormProvider` supplies the form context to all child components, while `FormConsumer` allows read-only access to the current form state for rendering computed values or form-wide UI elements.

## Using Ant Design Components from @formily/antd

The `@formily/antd` package exports pre-configured versions of Ant Design components that automatically bind to Formily's field state. All components are re-exported from [[`packages/antd/src/index.ts`](https://github.com/alibaba/formily/blob/main/packages/antd/src/index.ts)](https://github.com/alibaba/formily/blob/formily_next/packages/antd/src/index.ts), including `FormItem`, `Input`, `Select`, `NumberPicker`, and others.

Key components include:
- **FormItem**: The standard decorator that wraps inputs with labels, validation messages, and layout logic.
- **NumberPicker**: A thin wrapper around Ant Design's `<InputNumber>` that handles numeric value binding.
- **Select**: Wraps Ant Design's `<Select>` with support for dynamic options and async data sources.

### Declarative JSX Approach

In the declarative pattern, you use the `Field` component from `@formily/react` to define each form field, specifying the `decorator` (usually `FormItem`) and the `component` (such as `NumberPicker`).

```tsx
import { Field } from '@formily/react'
import { NumberPicker, FormItem, Space } from '@formily/antd'

<FormProvider form={form}>
  <Space>
    <Field
      name="price"
      title="Price"
      initialValue={5.2}
      decorator={[FormItem]}
      component={[
        NumberPicker,
        { placeholder: 'Please enter', style: { width: 100 } },
      ]}
    />
    <FormItem>×</FormItem>
    <Field
      name="count"
      title="Quantity"
      initialValue={100}
      decorator={[FormItem]}
      component={[
        NumberPicker,
        { placeholder: 'Please enter', style: { width: 100 } },
      ]}
    />
    <FormConsumer>
      {(form) => <FormItem>{` ${form.values.price * form.values.count} 元`}</FormItem>}
    </FormConsumer>
  </Space>
</FormProvider>

```

This example, adapted from [[`packages/antd/docs/index.md`](https://github.com/alibaba/formily/blob/main/packages/antd/docs/index.md)](https://github.com/alibaba/formily/blob/formily_next/packages/antd/docs/index.md#L33-L88), demonstrates how `FormConsumer` can reactively compute derived values from form state.

### Schema-Driven JSON Approach

For dynamic forms or configuration-driven UIs, use `createSchemaField` to build a schema-aware component tree. This approach defines the form structure using JSON-compatible objects rather than JSX.

```tsx
import { createSchemaField } from '@formily/react'
import { Select, FormItem, FormButtonGroup, Submit } from '@formily/antd'

const SchemaField = createSchemaField({
  components: { Select, FormItem },
})

<FormProvider form={form}>
  <SchemaField>
    <SchemaField.String
      name="city"
      title="City"
      x-decorator="FormItem"
      x-component="Select"
      enum={[
        { label: 'Beijing', value: 'bj' },
        { label: 'Shanghai', value: 'sh' },
      ]}
    />
  </SchemaField>
  <FormButtonGroup>
    <Submit onSubmit={console.log}>Submit</Submit>
  </FormButtonGroup>
</FormProvider>

```

The schema API supports all Ant Design props via `x-component-props`, as documented in the Select component docs at [[`packages/antd/docs/components/Select.md`](https://github.com/alibaba/formily/blob/main/packages/antd/docs/components/Select.md)](https://github.com/alibaba/formily/blob/formily_next/packages/antd/docs/components/Select.md).

## Handling Reactive Data and Effects

Formily's core provides reactive hooks like `onFieldInit` and `onFieldReact` from [[`packages/core/src/onField.ts`](https://github.com/alibaba/formily/blob/main/packages/core/src/onField.ts)](https://github.com/alibaba/formily/blob/formily_next/packages/core/src/onField.ts) to handle asynchronous data loading and inter-field dependencies. These hooks enable you to wire Ant Design components with dynamic data sources.

For example, to load async options into a Select component, you would define an effect in your form configuration that reacts to field initialization and fetches data. The `Select` component supports standard Ant Design props like `showSearch` and `filterOption`, allowing you to implement searchable dropdowns with server-side filtering.

## Complete Code Examples

### Minimal Login Form

This example demonstrates a basic username and password form using the declarative approach:

```tsx
import React from 'react'
import { createForm } from '@formily/core'
import { FormProvider, Field } from '@formily/react'
import { Input, FormItem, Space } from '@formily/antd'

const form = createForm()

export default function App() {
  return (
    <FormProvider form={form}>
      <Space direction="vertical">
        <Field
          name="username"
          title="Username"
          decorator={[FormItem]}
          component={[
            Input,
            { placeholder: 'Enter username', style: { width: 200 } },
          ]}
        />
        <Field
          name="password"
          title="Password"
          decorator={[FormItem]}
          component={[
            Input.Password,
            { placeholder: 'Enter password', style: { width: 200 } },
          ]}
        />
      </Space>
    </FormProvider>
  )
}

```

### Schema-Driven Form with Async Select

This advanced example shows how to structure a form using JSON schema patterns:

```tsx
import React from 'react'
import { createForm } from '@formily/core'
import { FormProvider, createSchemaField } from '@formily/react'
import { Select, FormItem, FormButtonGroup, Submit } from '@formily/antd'

const form = createForm()
const SchemaField = createSchemaField({ components: { Select, FormItem } })

export default () => (
  <FormProvider form={form}>
    <SchemaField>
      <SchemaField.String
        name="product"
        title="Product"
        x-decorator="FormItem"
        x-component="Select"
        x-component-props={{
          showSearch: true,
          filterOption: false,
          style: { width: 300 },
        }}
      />
    </SchemaField>
    <FormButtonGroup>
      <Submit onSubmit={(values) => console.log(values)}>Submit</Submit>
    </FormButtonGroup>
  </FormProvider>
)

```

To populate the Select with async data, wire up `form.effects` using `onFieldReact` when creating the form instance, targeting the specific field name to trigger data fetching on mount or value changes.

## Summary

- **Install the trilogy**: You need `@formily/core` for state management, `@formily/react` for context providers, and `@formily/antd` for the UI component wrappers.
- **Initialize with createForm**: Always start by creating a form instance using `createForm()` from the core package.
- **Provide context**: Wrap your form components with `FormProvider` to inject the form instance into the React tree.
- **Use wrapped components**: Import components like `FormItem`, `Input`, and `Select` from `@formily/antd` rather than directly from `antd` to ensure proper value binding.
- **Choose your paradigm**: Formily supports both declarative JSX fields and JSON schema-driven forms via `createSchemaField`.
- **Leverage reactivity**: Use core effects like `onFieldReact` from [`packages/core/src/onField.ts`](https://github.com/alibaba/formily/blob/main/packages/core/src/onField.ts) to handle async data sources and dynamic validation.

## Frequently Asked Questions

### Do I need to install Ant Design separately when using @formily/antd?

Yes, Ant Design and Moment.js are peer dependencies of `@formily/antd`. You must install them separately using `npm install antd moment` because they are not bundled with the Formily packages. The `@formily/antd` package only provides the integration layer between Formily's core engine and Ant Design's components.

### What is the difference between decorator and component in Formily fields?

The **decorator** property (typically set to `FormItem`) controls the layout, labeling, and validation message display around the input. The **component** property specifies the actual input control (such as `Input`, `Select`, or `NumberPicker`) that handles user interaction. This separation allows you to mix different layout decorators with various input types while maintaining consistent styling.

### Can I use standard Ant Design components with Formily?

You should use the components exported from `@formily/antd` rather than standard Ant Design components. The `@formily/antd` versions are pre-wrapped with the necessary logic to connect to Formily's reactive form state, handle value binding, and display validation errors. Using standard AntD components directly would require manual wiring to the form context.

### How do I load async options into a Formily Select component?

Use Formily's effect system by defining `form.effects` when calling `createForm`, then implement `onFieldInit` or `onFieldReact` from [`packages/core/src/onField.ts`](https://github.com/alibaba/formily/blob/main/packages/core/src/onField.ts) to fetch data when the field mounts or reacts to other field changes. The Select component accepts standard Ant Design props like `loading` and `onSearch`, allowing you to implement debounced search and loading states while the async operation resolves.