📋 RFC: Introduce PropsInjector for flexible props forwarding

Summary

Introduce a new utility component, PropsInjector, to solve the problem of forwarding props from Form.Item to deeply nested form controls within layout components like Space.Compact or Flex or any other layer wrapper. This component uses the Render Props pattern to provide a flexible and explicit way to pass props like value and onChange to the desired target.

Basic example

import { Form, Input, Space, Button } from 'antd';

const Demo = () => (
  <Form>
    <Form.Item name="coupon" label="Coupon Code">
      <PropsInjector>
        {(props) => (
          <Space.Compact>
            <Input {...props} placeholder="Enter your coupon" />
            <Button type="primary">Apply</Button>
          </Space.Compact>
        )}
      </PropsInjector>
    </Form.Item>
  </Form>
);

In this example, Form.Item passes value, onChange, etc., to PropsInjector. The injector then passes these props as an object to its children function, which can be explicitly spread onto the target <Input /> component.

Motivation

A major pain point when composing forms in Ant Design is using layout components like Space.Compact inside a Form.Item. The props injected by Form.Item (such as value and onChange) are passed to the top-level child, which is the layout component (Space.Compact), not the actual form control (Input, Select, etc.) inside it.

The current workarounds are inconvenient and lead to boilerplate code:

1. Creating Higher-Order Components (HOCs): Developers must wrap their component group in a custom HOC to manually forward props. This is verbose and not easily reusable.
2. Using React.cloneElement: This involves complex and imperative logic that clutters the component's render method.

As one developer put it, "If I use it with a Form, I have to create an HOC to pass props to the Input. This is very inconvenient."

PropsInjector provides a standardized, declarative, and highly flexible solution to this common problem, eliminating the need for custom wrappers and making complex form layouts clean and intuitive.

Detailed Design

We will introduce a new component, PropsInjector, which will be statically attached to Form.Item. It is designed as a generic utility that implements the Render Props pattern.

API

Its API is minimal and powerful:

type PropsInjector<T> = (props: {
  children: (injectedProps: T) => React.ReactNode;
  // It also accepts any props from its parent (e.g., Form.Item)
  [key: string]: any;
}) => JSX.Element;

Implementation Details

1. The PropsInjector component collects all props passed to it, except for children.
2. It validates that its children prop is a function.
3. It invokes this function, passing the collected props as the first argument.
4. It renders the result of the function call. The component itself does not render any wrapper DOM element.

Alternatives Considered

• Compound Components (<Injector.Target />): We considered an API like:

<Injector>
  <Space.Compact>
    <Injector.Target>
      <Input />
    </Injector.Target>
  </Space.Compact>
</Injector>

While highly declarative, this approach is less flexible. The Render Props pattern gives the user full control to pass props to multiple children, modify them, or use them for conditional rendering, which is a significant advantage in complex scenarios.

• Prop-based Targeting (targetKey): An API like <Injector targetKey="myInput">... was also considered. This feels "magical," is prone to stringly-typed errors, and has poor IDE support. The Render Props pattern is far more explicit and type-safe.

The Render Props pattern was chosen for its superior flexibility, explicitness, and simplicity of implementation.

Drawbacks

1. Slightly more verbose JSX: The {(props) => (...) } syntax introduces an extra layer of nesting compared to direct component composition, which might feel slightly cluttered to developers unfamiliar with the pattern.
2. Cognitive Overhead: While a standard React pattern, Render Props might require a brief learning moment for junior developers or those who have primarily used Hooks.

However, we believe the trade-off is well worth it for the explicitness and power it provides.

Adoption strategy

This is a new, non-breaking, and additive feature.

1. Implement PropsInjector as util component.
2. Update the documentation for Form and Space.Compact with examples demonstrating this new, recommended pattern for composing complex inputs.
3. No migration is needed for existing code. This component will serve as a best-practice solution for new development and for refactoring existing complex form structures.