Field
Description
As the React implementation of createField from @silver-formily/core, it is a bridge component dedicated to binding a ViewModel to an input control. See IFieldFactoryProps for the Field component props.
The name attribute is required.
Field uses the same lifecycle handling as ArrayField, ObjectField, and VoidField. Synchronous StrictMode effect replay does not emit extra onFieldMount / onFieldUnmount events. Replacing the field instance or actually unmounting it still performs cleanup. Real unmount cleanup is deferred to a microtask, so do not synchronously read unmounted immediately after removing the component to determine whether cleanup has finished.
Usage
import type { ReactNode } from 'react'
import { createForm } from '@silver-formily/core'
import { Field, FormProvider } from '@silver-formily/react'
import { Input } from 'antd'
import { StrictMode, useState } from 'react'
function Decorator({ content, children }: { content?: ReactNode, children?: ReactNode }) {
return (
<label>
{children}
<small>{content}</small>
</label>
)
}
export default function Demo() {
const [form] = useState(() => createForm({
initialValues: { input: '初始值' },
}))
return (
<StrictMode>
<FormProvider form={form}>
<Field
name="input"
component={[Input, { placeholder: '请输入' }]}
decorator={[Decorator]}
decoratorContent={['提示：', <span key="help">请输入内容</span>]}
/>
<Field name="zero" content={0} />
</FormProvider>
</StrictMode>
)
}import type { ReactNode } from 'react'
import { createForm } from '@silver-formily/core'
import { Field, FormProvider } from '@silver-formily/react'
import { Input } from 'antd'
import { StrictMode, useState } from 'react'
function Decorator({ content, children }: { content?: ReactNode, children?: ReactNode }) {
return (
<label>
{children}
<small>{content}</small>
</label>
)
}
export default function Demo() {
const [form] = useState(() => createForm({
initialValues: { input: '初始值' },
}))
return (
<StrictMode>
<FormProvider form={form}>
<Field
name="input"
component={[Input, { placeholder: '请输入' }]}
decorator={[Decorator]}
decoratorContent={['提示：', <span key="help">请输入内容</span>]}
/>
<Field name="zero" content={0} />
</FormProvider>
</StrictMode>
)
}API
Field Properties
| Attribute | Description | Type | Default |
|---|---|---|---|
| name | Path of the field in the Form, must be unique | FormPathPattern | — |
| basePath | Base path for resolving name, commonly used for partial forms or array items | FormPathPattern | Parent field address, otherwise form root |
| title | Field display title, usually mapped to the label of the decorator component | any | — |
| description | Auxiliary description of the field | any | — |
| value | Current field value (controlled mode) | any | — |
| initialValue | Initial field value, interpreted by Core | any | — |
| required | Whether the field is required; drives validation and UI state | boolean | false |
| display | Display state: visible, hidden, none | enum | visible |
| pattern | Interaction pattern: editable, readOnly, disabled, readPretty | enum | editable |
| hidden | Hide rendering while retaining values (display: hidden) | boolean | false |
| visible | false sets display: none; true sets display: visible | boolean | true |
| editable | Whether editing is allowed | boolean | true |
| disabled | Whether disabled (the component is not interactive) | boolean | false |
| readOnly | Whether read-only (still focusable but not editable) | boolean | false |
| readPretty | Whether to enter the read-pretty display state (often used with mapReadPretty) | boolean | false |
| loading | Field loading state | boolean | false |
| dataSource | Component option data: an array of objects with extensible properties | FieldDataSource (from @silver-formily/core) | - |
| validateFirst | Whether to stop the remaining rules immediately when a validation fails | boolean | Form setting when omitted |
| validatePattern | Validation that only triggers under the specified pattern | FieldPatternTypes[] | form setting, then ['editable'] |
| validateDisplay | Validation that only triggers under the specified display | FieldDisplayTypes[] | form setting, then ['visible'] |
| validator | Custom validator, with the same signature as the Formily validator | FieldValidator | — |
| decorator | Decorator component and its props, in the form [Decorator, props] | [] | [D] | [D, Partial<React.ComponentProps<D>>] | — |
| decoratorContent beta | Decorator content: plain content (string / ReactNode) is passed to the decorator as the conventional content prop, object maps are spread into multiple decorator props and take precedence over same-named decorator props | string | React.ReactNode | Record<string, React.ReactNode> | — |
| component | Input component and its props, in the form [Component, props] | [] | [C] | [C, Partial<React.ComponentProps<C>>] | — |
| reactions | Reactive reactions, supports a function or an array of functions | FieldReaction[] | FieldReaction | — |
| mountedReactions 1.0.0 | Reactive reactions that start once the first batch of form fields has fully mounted, and stop automatically when the field unmounts | FieldReaction[] | FieldReaction | — |
| content | Child nodes passed to the input component | any | — |
| data | Pass-through extension data, readable in reactions or components | any | — |
| children | Render function or child nodes; the render function receives (field, form) | Function | React.ReactNode | — |
TIP
Only component / decorator tuple props are forwarded to their components; arbitrary top-level Field props are not spread into UI components. Data fields inject value, onChange, onFocus, and onBlur. Each event updates the model before calling the latest matching component callback. Explicit component disabled / readOnly props override the defaults derived from the field pattern. Adapt checkbox-like value props with connect / mapProps when necessary.
Both hidden and none suppress rendering. Core retains values for hidden, while none removes values and restores cached values when shown again. The field model's mount lifecycle is distinct from whether its inner UI is visible.
Children from children (including its render-function result) are combined with field.content ?? field.componentProps.children; zero is valid content. A field without a component still renders its content. Component and decorator references can be intrinsic tag names or React components; schema registry names are resolved through SchemaComponentsContext.
Core declares title, description, and content as any; values placed in the rendered React tree must still be valid ReactNode values. Display/pattern defaults in the table assume no overriding parent or form state.