Common Props documentation scope
The documented generic properties apply to most Ant Design components. Components that do not support particular properties document this separately.
components/common-props
165 notes in this subject, read out of this brain and free to use. This is page 1 of 3.
Common Props - style className rootClassName autoFocus
Most Ant Design components support these generic properties: style (CSSProperties, default -), className (string, default -), rootClassName (string, default -), and autoFocus (boolean, default false). The style property provides additional inline styles. The className property adds additional CSS classes. The rootClassName property adds a class name to the root element. The autoFocus property auto focuses the component when mounted, but only works on focusable elements like forms and links.
Common props applicable to most Ant Design components
The following common properties apply to most Ant Design components. Components that do not support these properties will be documented separately. Common properties table: - style: CSSProperties type, no default value. Custom styling. - className: string type, no default value. Custom class name. - rootClassName: string type, no default value. Class name added to the outermost layer of the component. - autoFocus: boolean type, default value false. Auto-focus behavior applies only to form elements, links, interactive containers, and other focusable elements.
Do not access component internal props or state with ref
Only access official documented APIs through ref. Directly accessing internal props or state is not recommended as it creates strong coupling with the current version. Any refactor like migrating to Hooks, deleting or renaming internal props or state, or adjusting internal node constructor will break code that accesses internals.
Unifying pop component display name to open prop
For historical reasons, pop components used both open and visible props. In v5, the attribute name is being unified to open for consistency. The original visible prop will still work for backward compatibility but is removed from documentation.
Static methods lose styles when setting prefixCls on ConfigProvider
Static methods like message, notification, and Modal.confirm are not using the same render tree as Button and are rendered to independent DOM nodes created by ReactDOM.render, which cannot access React context from ConfigProvider. Solutions: (1) Replace with hooks like message.useMessage, notification.useNotification, and Modal.useModal. (2) Use App.useApp to get message/notification/modal instances.
Get type definitions not exported from antd
antd exposes basic component definitions. For unexposed props, use utility types provided by antd. Example: import type { Checkbox, CheckboxProps, GetProp, GetProps, GetRef, Input } from 'antd'; type CheckboxGroupProps = GetProps<typeof Checkbox.Group>; type CheckboxValue = GetProp<CheckboxProps, 'value'>; type InputRef = GetRef<typeof Input>;
Controlled Input/Select value cannot be changed by user
If you set the value of an Input or Select component but it cannot be changed by user action, use onChange to update the value in state. This is the React pattern for controlled components as documented in React's controlled input documentation.
undefined vs null in controlled components
In antd controlled components, undefined is treated as uncontrolled, while null is treated as controlled with an empty value. When value is converted from a valid value to undefined or null, the component is no longer controlled. To deal with cases like allowClear that clear non-primitive values, set the value explicitly to null if you need a component controlled with a valid value. For Select-like components, strongly avoid using undefined or null as value in options; use string or number instead.
DatePicker/RangePicker mode prop does not create YearPicker or MonthPicker
The mode prop on DatePicker or RangePicker does not create YearPicker or MonthPicker behavior. The mode property controls the displayed panel but does not change the original date picking behavior. You still need to click date cell to finish selection in DatePicker regardless of mode. The disabledDate prop cannot work on year/month panels of DatePicker mode="year/month", only on date panel cells. To create YearPicker or MonthRangePicker, upgrade to antd@4.0 or later where dedicated picker components were added. Alternatively, encapsulate mode and onPanelChange to create custom pickers.
defaultValue only works on first render
The defaultXxxx props (e.g. defaultValue) on Input, Select, and similar components only work on the first render. This is a React specification. To change the value dynamically, use controlled components with onChange and state.
message and notification are lowercase functions, not components
message and notification are lowercase because they are functions, not React Components. This is not a typo. Other antd components are capitalized because they are React components.
Date-related components locale not working with dayjs
If date-related components locale is not working, verify dayjs locale is imported correctly with import 'dayjs/locale/zh-cn'; and dayjs.locale('zh-cn');. Check for multiple versions of dayjs installed with npm ls dayjs. A mismatched dayjs version with antd's dayjs will cause locale to not work.
Popup components disappear when clicking nested popups
This was an old bug fixed since antd v3.11.x. For older versions, use getPopupContainer prop like <Select getPopupContainer={trigger => trigger.parentElement}> to render the component inside the parent container. This applies to Select, Dropdown, DatePicker, TimePicker, Popover, and Popconfirm components.
Prevent Select, DatePicker, and similar popups from scrolling with page
Use the getPopupContainer prop: <Select getPopupContainer={trigger => trigger.parentElement}> to render the popup inside a scroll area. To configure this globally, use <ConfigProvider getPopupContainer={trigger => trigger.parentElement}>. Ensure the parentElement has position: relative or position: absolute CSS.
Props changes with mutable modification do not trigger updates
antd uses shallow comparison of props to optimize performance. When updating state, always pass a new object instead of mutating the existing one. Mutating objects in place will not trigger component updates.
Form setFieldsValue null type error with strictNullChecks
When using Form.setFieldsValue with an object containing null values and receiving a TypeScript error, check tsconfig.json for strictNullChecks: true. If this setting is causing issues, set it to false (if project doesn't require strict null checking) or design types to avoid null, using other types like undefined instead.
Should not access component internal props and state via ref
When using refs, only use documented methods provided in official documentation. Do not directly read internal props and state as this creates tight coupling to component internals. Any refactoring, such as converting to Hooks, renaming internal props/state, or restructuring internal React nodes, could break your code.
Popup disappears when clicking nested popup in Select/DatePicker/etc
When a popup component inside Select, Dropdown, DatePicker, TimePicker, Popover, or Popconfirm is clicked, it may disappear. This issue was fixed in version 3.11.0. For older versions, use the getPopupContainer prop (e.g., getPopupContainer={trigger => trigger.parentElement}) or other getXxxxContainer parameters to render components inside the parent element.
Icon files not accessible in network environment
If icon files cannot be accessed in your network environment, deploy the iconfont files to your own network. In antd version 3.9.x and later, SVG icons are used instead of iconfont, eliminating the need for local deployment.
Multiple components in a row not vertically aligned
Use the Space component to vertically align multiple components placed in a row.
Input/Select value cannot be modified when set
When setting the value prop on Input, Select, or similar components, the component becomes read-only if you don't update the value via onChange. Use onChange to update the value state. This follows React's controlled component pattern.
Getting unexported property definitions from antd
Use Ant Design utility types to get unexported properties. Import GetProp, GetProps, and GetRef from antd. GetProps extracts the Props type of a component, GetProp extracts a specific prop type, and GetRef extracts the Ref type. Example: type CheckboxGroupProps = GetProps<typeof Checkbox.Group>; type CheckboxValue = GetProp<CheckboxProps, 'value'>; type InputRef = GetRef<typeof Input>;
Component doesn't update when passing object or array props
Ant Design performs shallow comparison of props for performance optimization. When state changes, always pass a new object rather than mutating the existing one.
Dynamically changing defaultValue doesn't work
The defaultValue (and other defaultXxxx props) of Input, Select, and similar components only take effect on the first render. This is React's standard behavior. Refer to React documentation on controlling inputs with state variables.
message is lowercase, other components are capitalized
message and notification are lowercase because they are functions, not React components. Other components are named with capital letters because they are React components.
Why unified open property for overlay components
Overlay components (Popover, Popconfirm, Dropdown, etc.) historically used inconsistent naming with both open and visible properties. In antd v5, the open property is preferred for consistency, though visible remains supported for backward compatibility. The open property naming will be the standard going forward.
undefined vs null in controlled components
In Ant Design, undefined is the marker for uncontrolled components, while null is used as an explicit controlled empty value. This differs from React's standard where both are treated as uncontrolled markers. When you need a controlled component with an empty value (such as with allowClear), set the value to null, not undefined. For Select component options, it is strongly recommended not to use undefined or null as the option value; use string or number instead.
Popup scrolls with scrollbar
Select, Dropdown, DatePicker, TimePicker, Popover, and Popconfirm may move with scrollbars. Solution: use getPopupContainer prop (e.g., getPopupContainer={trigger => trigger.parentElement}) to render components within the scroll area, or use other getXxxxContainer parameters. For a global solution, use ConfigProvider with getPopupContainer. Ensure the parentElement has position: relative or position: absolute.
Next.js App Router error with antd sub-components
When using Next.js App Router, accessing sub-components like Select.Option, Form.Item, Typography.Title may error: 'Cannot access .Option on the server'. Two workarounds: (1) Create a wrapper component that re-exports sub-components with 'use client' directive, or (2) Add 'use client' directive to your page component to render entirely on the client side.
DatePicker mode property doesn't allow year/month selection
Setting the mode property on DatePicker or RangePicker (e.g., mode="year" or mode="month") does not change the interaction behavior. DatePicker still completes selection only on day click, and RangePicker on date click. The mode property only controls panel display, not interaction. disabledDate only works on the day panel, not on year/month panels when mode is set. Use dedicated components YearPicker, MonthPicker, or encapsulate your own using mode and onPanelChange. In antd 4.0+, dedicated picker components are available for this purpose.
ConfigProvider for locale configuration
ConfigProvider is used to wrap the application and set the locale, such as Chinese (zhCN) from 'antd/locale/zh_CN'. Antd components use English text by default and require ConfigProvider to display text in other languages.
Input component bordered deprecation in v6
In v6, Input component bordered prop is deprecated and replaced by variant.
Image component API deprecations in v6
In v6, Image deprecations: wrapperStyle replaced by styles.root; visible replaced by open; onVisibleChange replaced by onOpenChange; maskClassName replaced by classNames.cover; rootClassName replaced by classNames.root; toolbarRender replaced by actionsRender.
FloatButton component description deprecation in v6
In v6, FloatButton component description prop is deprecated and replaced by content.
Empty component imageStyle deprecation in v6
In v6, Empty component imageStyle prop is deprecated and replaced by styles.image.
Dropdown.Button deprecated in v6
In v6, Dropdown.Button is deprecated and replaced by Space.Compact + Dropdown + Button.
Drawer component API deprecations in v6
In v6, Drawer deprecations: headerStyle replaced by styles.header; bodyStyle replaced by styles.body; footerStyle replaced by styles.footer; contentWrapperStyle replaced by styles.wrapper; maskStyle replaced by styles.mask; drawerStyle replaced by styles.section; classNames.content replaced by classNames.section; styles.content replaced by styles.section; destroyInactivePanel replaced by destroyOnHidden; width replaced by size; height replaced by size. Starting from 6.3.0, maskClosable is replaced by mask.closable.
Divider component API deprecations in v6
In v6, Divider deprecations: type is replaced by orientation; orientationMargin is replaced by styles.content.margin.
Descriptions component API deprecations in v6
In v6, Descriptions deprecations: children is replaced by items; labelStyle is replaced by styles.label; contentStyle is replaced by styles.content. Starting from 6.3.2, size="default" is replaced by size="large" and size="middle" is replaced by size="medium".
DatePicker component API deprecations in v6
In v6, DatePicker deprecations: dropdownClassName replaced by classNames.popup.root; popupClassName replaced by classNames.popup.root; popupStyle replaced by styles.popup.root; bordered replaced by variant; onSelect replaced by onCalendarChange.
ConfigProvider component dropdownMatchSelectWidth deprecation in v6
In v6, ConfigProvider dropdownMatchSelectWidth prop is deprecated and replaced by popupMatchSelectWidth.
Collapse.Panel component disabled deprecation in v6
In v6, Collapse.Panel disabled prop is deprecated and replaced by collapsible="disabled".
Collapse component API deprecations in v6
In v6, Collapse deprecations: destroyInactivePanel is replaced by destroyOnHidden; expandIconPosition is replaced by expandIconPlacement.
Cascader component API deprecations in v6
In v6, Cascader deprecations: dropdownClassName replaced by classNames.popup.root; dropdownStyle replaced by styles.popup.root; dropdownRender replaced by popupRender; dropdownMenuColumnStyle replaced by styles.popup.listItem; onDropdownVisibleChange replaced by onOpenChange; onPopupVisibleChange replaced by onOpenChange; bordered replaced by variant; showArrow is deprecated and will become default behavior, set suffixIcon to null to hide.
Carousel component dotPosition deprecation in v6
In v6, Carousel dotPosition prop is deprecated and replaced by dotPlacement.
Card component API deprecations in v6
In v6, Card deprecations: headStyle is replaced by styles.header; bodyStyle is replaced by styles.body; bordered is replaced by variant; tab is replaced by label.
Calendar component API deprecations in v6
In v6, Calendar deprecations: dateFullCellRender is replaced by fullCellRender; dateCellRender is replaced by cellRender; monthFullCellRender is replaced by fullCellRender; monthCellRender is replaced by cellRender.
Button component iconPosition deprecation in v6
In v6, Button component iconPosition prop is deprecated and replaced by iconPlacement.
Button.Group deprecated in v6
In v6, Button.Group is deprecated and replaced by Space.Compact.
Breadcrumb component API deprecations in v6
In v6, Breadcrumb deprecations: routes is replaced by items; Breadcrumb.Item and Breadcrumb.Separator are replaced by items; breadcrumbName is replaced by title; items.children is replaced by menu.
Badge component size="default" deprecation in v6
In v6 starting from 6.3.2, Badge size="default" is deprecated and replaced by size="medium".
BackTop component deprecated in v6
In v6, BackTop component is deprecated and replaced by FloatButton.BackTop.
Dropdown component API deprecations in v6
In v6, Dropdown deprecations: dropdownRender replaced by popupRender; destroyPopupOnHide replaced by destroyOnHidden; overlayClassName replaced by classNames.root; overlayStyle replaced by styles.root; placement: xxxCenter is replaced by placement: xxx.
Avatar.Group component API deprecations in v6
In v6, Avatar.Group deprecations: maxCount is replaced by max={{ count: number }}; maxStyle is replaced by max={{ style: CSSProperties }}; maxPopoverPlacement is replaced by max={{ popover: PopoverProps }}; maxPopoverTrigger is replaced by max={{ popover: PopoverProps }}.
Avatar component size="default" deprecation in v6
In v6 starting from 6.3.0, Avatar size="default" is deprecated and replaced by size="medium".
AutoComplete component API deprecations in v6
In v6, AutoComplete deprecations: dropdownMatchSelectWidth replaced by popupMatchSelectWidth; dropdownStyle replaced by styles.popup.root; dropdownClassName replaced by classNames.popup.root; popupClassName replaced by classNames.popup.root; dropdownRender replaced by popupRender; onDropdownVisibleChange replaced by onOpenChange; dataSource replaced by options.
Input.Group deprecated in v6
In v6, Input.Group is deprecated and replaced by Space.Compact.
Anchor component API deprecations in v6
In v6, Anchor children prop is deprecated and replaced by items prop.
Alert component API deprecations in v6
In v6, Alert component deprecations: closeText is replaced by closable.closeIcon; closeIcon is replaced by closable.closeIcon; message is replaced by title; onClose is replaced by closable.onClose; afterClose is replaced by closable.afterClose.