v5에서 v6로 마이그레이션

v5에서 v6로 마이그레이션 (From v5 to v6)

이 문서는 antd를 5.x에서 6.x로 업그레이드하는 걸 도와줘요. 이번 릴리스는 주로 기술적 업그레이드라서 대부분의 컴포넌트 API는 호환되지만, 업그레이드 전에 환경이 새 요구사항을 충족하는지 확인해야 해요.

출처: 문서

본문

이 문서는 antd를 버전 5.x에서 6.x로 업그레이드하는 데 도움을 줘요. 이번 릴리스는 주로 기술적 업그레이드로, 대부분의 컴포넌트 API는 호환돼요. 다만 업그레이드 전에 환경이 새 요구사항을 충족하는지 확인해야 해요.

CLI로 업그레이드 지원받기 {#use-cli}

체크리스트를 수동으로 훑기 전에 Ant Design CLI로 업그레이드를 지원받는 걸 권장해요. 이 도구는 코드베이스의 deprecated API, 컴포넌트 사용법, 버전 차이를 검사해 주므로 이 문서를 하나하나 읽는 것에만 의존하지 않아도 돼요. 설치와 사용법은 CLI 문서를 참고하세요.

업그레이드 전에

  1. 먼저 최신 v5 릴리스로 업그레이드하고, 콘솔에 표시된 deprecation 경고를 모두 처리하세요.
  2. 프로젝트가 React 18 이상에서 돌아가는지 확인하세요 — v6는 React 17 이하를 더 이상 지원하지 않아요.
  3. v6는 모던 브라우저만 지원하며 기본적으로 CSS 변수를 사용하므로 IE는 지원하지 않아요.

설치:

npm install --save antd@6
# or
yarn add antd@6
# or
pnpm add antd@6

v6의 비호환 변경 사항

React 버전 지원

  • antd@6는 React >= 18을 요구하며 React 17 이하는 더 이상 지원하지 않아요.
  • React 19를 지원하려고 넣었던 @ant-design/v5-patch-for-react-19 패키지는 더 이상 필요 없어요. 있다면 제거해도 돼요.
- import '@ant-design/v5-patch-for-react-19';

@ant-design/icons 버전 업그레이드

  • antd@6는 @ant-design/icons 버전 >= 6.0.0을 요구해요.
  • ⚠️ 중요: @ant-design/icons@6는 antd@5와 호환되지 않아요. 두 패키지를 반드시 함께 업그레이드하세요.
  • 프로젝트가 @ant-design/icons에 명시적으로 의존한다면 그것도 v6로 업그레이드해야 해요.
npm install --save @ant-design/icons@6
# or
yarn add @ant-design/icons@6
# or
pnpm add @ant-design/icons@6

업그레이드 중 빌드 오류가 발생하면 @ant-design/icons 버전이 antd 버전과 일치하는지 확인해 보세요.

DOM 조정

  • v6는 유지보수성과 일관성을 높이기 위해 많은 컴포넌트의 DOM 구조를 업그레이드하고 최적화해요.
  • 표준 antd 스타일링에 의존하는 대부분의 프로젝트에는 영향이 없을 거예요.
  • ⚠️ 컴포넌트의 내부 DOM 노드를 겨냥한 커스텀 스타일(예: 특정 선택자나 계층 구조에 의존)이 있다면, 업그레이드 후 해당 스타일을 점검하고 조정해야 할 수 있어요.

API 조정

⚠️ 아래 나열된 API는 deprecated로 표시되었어요. 지금은 여전히 동작하지만 콘솔에 deprecation 경고가 표시되고, 7.0 버전에서 제거될 거예요. 코드의 지속 가능성과 호환성을 위해 가능한 한 빨리 대체 API로 마이그레이션하는 것을 강력히 권장해요.

아래의 모든 deprecation은 별도 표기가 없는 한 v6.0.0부터 적용돼요.

  • Alert

    • closeText는 deprecated이며 closable.closeIcon으로 대체돼요.
    • closeIcon는 deprecated이며 closable.closeIcon으로 대체돼요.
    • message는 deprecated이며 title로 대체돼요.
    • onClose는 deprecated이며 closable.onClose로 대체돼요.
    • afterClose는 deprecated이며 closable.afterClose로 대체돼요.

  • Anchor

    • Anchor children은 deprecated이며 items로 대체돼요.

  • AutoComplete

    • dropdownMatchSelectWidth는 deprecated이며 popupMatchSelectWidth로 대체돼요.
    • dropdownStyle은 deprecated이며 styles.popup.root로 대체돼요.
    • dropdownClassName은 deprecated이며 classNames.popup.root로 대체돼요.
    • popupClassName은 deprecated이며 classNames.popup.root로 대체돼요.
    • dropdownRender는 deprecated이며 popupRender로 대체돼요.
    • onDropdownVisibleChange는 deprecated이며 onOpenChange로 대체돼요.
    • dataSource는 deprecated이며 options로 대체돼요.

  • Avatar

    • size="default"는 deprecated이며 size="medium"으로 대체돼요. (6.3.0)

  • Avatar.Group

    • maxCount는 deprecated이며 max={{ count: number }}로 대체돼요.
    • maxStyle은 deprecated이며 max={{ style: CSSProperties }}로 대체돼요.
    • maxPopoverPlacement은 deprecated이며 max={{ popover: PopoverProps }}로 대체돼요.
    • maxPopoverTrigger은 deprecated이며 max={{ popover: PopoverProps }}로 대체돼요.

  • BackTop

    • BackTop은 deprecated이며 FloatButton.BackTop으로 대체돼요.

  • Badge

    • size="default"는 deprecated이며 size="medium"으로 대체돼요. (6.3.2)

  • Breadcrumb

    • routes는 deprecated이며 items로 대체돼요.
    • Breadcrumb.Item과 Breadcrumb.Separator는 deprecated이며 items로 대체돼요.
    • breadcrumbName은 deprecated이며 title로 대체돼요.
    • items.children은 deprecated이며 menu로 대체돼요.

  • Button.Group

    • Button.Group은 deprecated이며 Space.Compact로 대체돼요.

  • Button

    • iconPosition은 deprecated이며 iconPlacement로 대체돼요.

  • Calendar

    • dateFullCellRender는 deprecated이며 fullCellRender로 대체돼요.
    • dateCellRender는 deprecated이며 cellRender로 대체돼요.
    • monthFullCellRender는 deprecated이며 fullCellRender로 대체돼요.
    • monthCellRender는 deprecated이며 cellRender로 대체돼요.

  • Card

    • headStyle은 deprecated이며 styles.header로 대체돼요.
    • bodyStyle은 deprecated이며 styles.body로 대체돼요.
    • bordered는 deprecated이며 variant로 대체돼요.
    • tab은 deprecated이며 label로 대체돼요.

  • Carousel

    • dotPosition은 deprecated이며 dotPlacement로 대체돼요.

  • Cascader

    • dropdownClassName은 deprecated이며 classNames.popup.root로 대체돼요.
    • dropdownStyle은 deprecated이며 styles.popup.root로 대체돼요.
    • dropdownRender는 deprecated이며 popupRender로 대체돼요.
    • dropdownMenuColumnStyle은 deprecated이며 styles.popup.listItem으로 대체돼요.
    • onDropdownVisibleChange는 deprecated이며 onOpenChange로 대체돼요.
    • onPopupVisibleChange는 deprecated이며 onOpenChange로 대체돼요.
    • bordered는 deprecated이며 variant로 대체돼요.
    • showArrow는 deprecated이며 기본 동작이 될 거예요. 숨기려면 suffixIcon을 null로 설정하세요.

  • Collapse

    • destroyInactivePanel은 deprecated이며 destroyOnHidden으로 대체돼요.
    • expandIconPosition은 deprecated이며 expandIconPlacement로 대체돼요.

  • Collapse.Panel

    • disabled는 deprecated이며 collapsible="disabled"로 대체돼요.

  • ConfigProvider

    • dropdownMatchSelectWidth는 deprecated이며 popupMatchSelectWidth로 대체돼요.

  • DatePicker.RangePicker

    • dropdownClassName은 deprecated이며 classNames.popup.root로 대체돼요.
    • popupClassName은 deprecated이며 classNames.popup.root로 대체돼요.
    • popupStyle은 deprecated이며 styles.popup.root로 대체돼요.
    • bordered는 deprecated이며 variant로 대체돼요.
    • onSelect는 deprecated이며 onCalendarChange로 대체돼요.

  • DatePicker

    • dropdownClassName은 deprecated이며 classNames.popup.root로 대체돼요.
    • popupClassName은 deprecated이며 classNames.popup.root로 대체돼요.
    • popupStyle은 deprecated이며 styles.popup.root로 대체돼요.
    • bordered는 deprecated이며 variant로 대체돼요.
    • onSelect는 deprecated이며 onCalendarChange로 대체돼요.

  • Descriptions

    • children은 deprecated이며 items로 대체돼요.
    • labelStyle은 deprecated이며 styles.label로 대체돼요.
    • contentStyle은 deprecated이며 styles.content로 대체돼요.
    • size="default"는 deprecated이며 size="large"로 대체돼요. (6.3.2)
    • size="middle"은 deprecated이며 size="medium"으로 대체돼요. (6.3.2)

  • Divider

    • type은 deprecated이며 orientation으로 대체돼요.
    • orientationMargin은 deprecated이며 styles.content.margin으로 대체돼요.

  • Drawer

    • headerStyle은 deprecated이며 styles.header로 대체돼요.
    • bodyStyle은 deprecated이며 styles.body로 대체돼요.
    • footerStyle은 deprecated이며 styles.footer로 대체돼요.
    • contentWrapperStyle은 deprecated이며 styles.wrapper로 대체돼요.
    • maskStyle은 deprecated이며 styles.mask로 대체돼요.
    • drawerStyle은 deprecated이며 styles.section으로 대체돼요.
    • classNames.content는 deprecated이며 classNames.section으로 대체돼요.
    • styles.content는 deprecated이며 styles.section으로 대체돼요.
    • maskClosable은 deprecated이며 mask.closable로 대체돼요. (6.3.0)
    • destroyInactivePanel은 deprecated이며 destroyOnHidden으로 대체돼요.
    • width는 deprecated이며 size로 대체돼요.
    • height는 deprecated이며 size로 대체돼요.

  • Dropdown.Button

    • Dropdown.Button은 deprecated이며 Space.Compact + Dropdown + Button으로 대체돼요.

  • Dropdown

    • dropdownRender는 deprecated이며 popupRender로 대체돼요.
    • destroyPopupOnHide는 deprecated이며 destroyOnHidden으로 대체돼요.
    • overlayClassName은 deprecated이며 classNames.root로 대체돼요.
    • overlayStyle은 deprecated이며 styles.root로 대체돼요.
    • placement: xxxCenter는 deprecated이며 placement: xxx로 대체돼요.

  • Empty

    • imageStyle은 deprecated이며 styles.image로 대체돼요.

  • FloatButton

    • description은 deprecated이며 content로 대체돼요.

  • Image

    • wrapperStyle은 deprecated이며 styles.root로 대체돼요.
    • visible은 deprecated이며 open으로 대체돼요.
    • onVisibleChange는 deprecated이며 onOpenChange로 대체돼요.
    • maskClassName은 deprecated이며 classNames.cover로 대체돼요.
    • rootClassName은 deprecated이며 classNames.root로 대체돼요.
    • toolbarRender는 deprecated이며 actionsRender로 대체돼요.

  • Input.Group

    • Input.Group은 deprecated이며 Space.Compact로 대체돼요.

  • Input

    • bordered는 deprecated이며 variant로 대체돼요.

  • InputNumber

    • bordered는 deprecated이며 variant로 대체돼요.
    • addonAfter는 deprecated이며 Space.Compact로 대체돼요.
    • addonBefore는 deprecated이며 Space.Compact로 대체돼요.

  • Mentions

    • Mentions.Option은 deprecated이며 options로 대체돼요.

  • Menu

    • children은 deprecated이며 items로 대체돼요.

  • Modal

    • bodyStyle은 deprecated이며 styles.body로 대체돼요.
    • maskStyle은 deprecated이며 styles.mask로 대체돼요.
    • destroyOnClose는 deprecated이며 destroyOnHidden으로 대체돼요.
    • maskClosable은 deprecated이며 mask.closable로 대체돼요. (6.3.0)
    • focusTriggerAfterClose는 deprecated이며 focusable.focusTriggerAfterClose로 대체돼요. (6.2.0)

  • Notification

    • btn은 deprecated이며 actions로 대체돼요.
    • message는 deprecated이며 title로 대체돼요.

  • Progress

    • strokeWidth는 deprecated이며 size로 대체돼요.
    • width는 deprecated이며 size로 대체돼요.
    • trailColor은 deprecated이며 railColor로 대체돼요.
    • gapPosition은 deprecated이며 gapPlacement로 대체돼요.

  • Select

    • dropdownMatchSelectWidth는 deprecated이며 popupMatchSelectWidth로 대체돼요.
    • dropdownStyle은 deprecated이며 styles.popup.root로 대체돼요.
    • dropdownClassName은 deprecated이며 classNames.popup.root로 대체돼요.
    • popupClassName은 deprecated이며 classNames.popup.root로 대체돼요.
    • dropdownRender는 deprecated이며 popupRender로 대체돼요.
    • onDropdownVisibleChange는 deprecated이며 onOpenChange로 대체돼요.
    • bordered는 deprecated이며 variant로 대체돼요.
    • showArrow는 deprecated이며 기본 동작이 될 거예요. 숨기려면 suffixIcon을 null로 설정하세요.

  • Slider

    • tooltipPrefixCls는 deprecated이며 tooltip.prefixCls로 대체돼요.
    • getTooltipPopupContainer는 deprecated이며 tooltip.getPopupContainer로 대체돼요.
    • tipFormatter는 deprecated이며 tooltip.formatter로 대체돼요.
    • tooltipPlacement은 deprecated이며 tooltip.placement로 대체돼요.
    • tooltipVisible은 deprecated이며 tooltip.open으로 대체돼요.
    • onAfterChange는 deprecated이며 onChangeComplete로 대체돼요.
    • handleStyle은 deprecated이며 styles.handle로 대체돼요.
    • trackStyle은 deprecated이며 styles.track으로 대체돼요.
    • railStyle은 deprecated이며 styles.rail로 대체돼요.

  • Space.Compact

    • direction은 deprecated이며 orientation으로 대체돼요.

  • Space

    • direction은 deprecated이며 orientation으로 대체돼요.
    • split은 deprecated이며 separator로 대체돼요.

  • Spin

    • tip은 deprecated이며 description으로 대체돼요. (6.3.0)
    • wrapperClassName은 deprecated이며 classNames.root로 대체돼요.
    • size="default"는 deprecated이며 size="medium"으로 대체돼요. (6.3.2)

  • Splitter

    • layout은 deprecated이며 orientation으로 대체돼요.

  • Countdown

    • <Statistic.Countdown />는 deprecated이며 <Statistic.Timer type="countdown" />으로 대체돼요.

  • Statistic

    • valueStyle은 deprecated이며 styles.content로 대체돼요.

  • Steps

    • labelPlacement은 deprecated이며 titlePlacement으로 대체돼요.
    • progressDot은 deprecated이며 type="dot"으로 대체돼요.
    • direction은 deprecated이며 orientation으로 대체돼요.
    • items.description은 deprecated이며 items.content로 대체돼요.
    • size="default"는 deprecated이며 size="medium"으로 대체돼요. (6.3.2)

  • Table

    • pagination.position은 deprecated이며 pagination.placement로 대체돼요.
    • onSelectInvert는 deprecated이며 onChange로 대체돼요.
    • filterDropdownOpen은 deprecated이며 filterDropdownProps.open으로 대체돼요.
    • onFilterDropdownOpenChange는 deprecated이며 filterDropdownProps.onOpenChange로 대체돼요.
    • filterCheckall은 deprecated이며 locale.filterCheckAll로 대체돼요.
    • onSelectMultiple은 deprecated이며 onChange로 대체돼요.
    • onSelectAll은 deprecated이며 onChange로 대체돼요.
    • onSelectNone은 deprecated이며 onChange로 대체돼요.

  • Tabs

    • popupClassName은 deprecated이며 classNames.popup으로 대체돼요.
    • tabPosition은 deprecated이며 tabPlacement으로 대체돼요.
    • destroyInactiveTabPane은 deprecated이며 destroyOnHidden으로 대체돼요.
    • indicatorSize은 deprecated이며 indicator={{ size: ... }}로 대체돼요.
    • Tabs.TabPane은 deprecated이며 items로 대체돼요.

  • Tag

    • bordered={false}는 deprecated이며 variant="filled"으로 대체돼요.
    • color="xxx-inverse"는 deprecated이며 variant="solid"으로 대체돼요.

  • TimePicker

    • addon은 deprecated이며 renderExtraFooter로 대체돼요.
    • popupClassName은 deprecated이며 classNames.popup으로 대체돼요.
    • popupStyle은 deprecated이며 styles.popup으로 대체돼요.

  • Timeline

    • Timeline.Item은 deprecated이며 items로 대체돼요.
    • Timeline.Item.position은 deprecated이며 placement로 대체돼요. left / right 값은 start / end로 바꿔야 해요.
    • Timeline.Item.label은 deprecated이며 title로 대체돼요.
    • Timeline.Item.children은 deprecated이며 content로 대체돼요.
    • Timeline.Item.dot은 deprecated이며 icon으로 대체돼요.
    • pending은 deprecated이며 items로 대체돼요.
    • pendingDot은 deprecated이며 items로 대체돼요.
    • mode=left|right는 deprecated이며 mode=start|end로 대체돼요.

  • Tooltip

    • overlayStyle은 deprecated이며 styles.root로 대체돼요.
    • overlayInnerStyle은 deprecated이며 styles.container로 대체돼요.
    • overlayClassName은 deprecated이며 classNames.root로 대체돼요.
    • destroyTooltipOnHide는 deprecated이며 destroyOnHidden으로 대체돼요.

  • Transfer

    • listStyle은 deprecated이며 styles.section으로 대체돼요.
    • operationStyle은 deprecated이며 styles.actions로 대체돼요.
    • operations은 deprecated이며 actions로 대체돼요.

  • TreeSelect

    • dropdownMatchSelectWidth는 deprecated이며 popupMatchSelectWidth로 대체돼요.
    • dropdownStyle은 deprecated이며 styles.popup.root로 대체돼요.
    • dropdownClassName은 deprecated이며 classNames.popup.root로 대체돼요.
    • popupClassName은 deprecated이며 classNames.popup.root로 대체돼요.
    • dropdownRender는 deprecated이며 popupRender로 대체돼요.
    • onDropdownVisibleChange는 deprecated이며 onOpenChange로 대체돼요.
    • bordered는 deprecated이며 variant로 대체돼요.
    • showArrow는 deprecated이며 기본 동작이 될 거예요. 숨기려면 suffixIcon을 null로 설정하세요.

오버레이 컴포넌트 (Modal, Drawer 등)

  • v6는 mask 오버레이 옵션을 도입하고 블러(blur) 효과를 지원해요.
  • v6.0.0 – v6.2.x는 블러를 기본으로 활성화했지만, v6.3.0부터는 블러가 기본 비활성화예요. 블러를 켜려면:
import { ConfigProvider, Drawer, Modal } from 'antd';

export default () => (
  <ConfigProvider
    modal={{
      mask: {
        blur: true,
      },
    }}
    drawer={{
      mask: {
        blur: true,
      },
    }}
  >
    <Modal />
    <Drawer />
  </ConfigProvider>
);

Tag 여백 조정

v6는 Tag 컴포넌트의 끝에 붙어 있던 기본 여백을 제거했어요 (이전에는 Tag를 가로로 나열하면 마지막 항목에 margin-inline-end 여백이 남았어요). 레이아웃이나 커스텀 스타일이 그 암묵적인 공백에 의존했다면, ConfigProvider의 tag.styles로 다시 넣어 주세요:

import { ConfigProvider, Tag } from 'antd';

export default () => (
  <ConfigProvider
    tag={{
      styles: {
        root: {
          marginInlineEnd: 8,
        },
      },
    }}
  >
    <Tag>Tag A</Tag>
    <Tag>Tag B</Tag>
    <Tag>Tag C</Tag>
  </ConfigProvider>
);

특정 영역에서만 예전 여백이 필요하다면, 전역 설정 대신 로컬 컨테이너 오버라이드를 선호하세요. 다른 곳에 의도치 않은 영향이 가지 않도록요.

Form onFinish가 더 이상 Form.List의 모든 데이터를 포함하지 않음

v5에서는 Form.List를 단일 Field로 취급해서, 등록된 Form.Item이 없는 항목까지 onFinish에 Form.List 구조 전체의 데이터가 포함됐어요. v6에서는 Form.List가 등록되지 않은 하위 항목의 데이터를 더 이상 포함하지 않아요. 따라서 이제는 getFieldsValue({ strict: true })로 등록되지 않은 필드를 걸러낼 필요가 없어요.

    const onFinish = (values) => {
--    const realValues = getFieldsValue({ strict: true });
++    const realValues = values;

      // ...
    }

    <Form onFinish={onFinish} />

size enum 통일 (6.3.0 – 6.3.2) {#size-enum-unify}

v6는 컴포넌트 size enum을 점진적으로 'large' | 'medium' | 'small'로 통일했어요. 예전 값도 여전히 동작하지만 deprecation 경고가 나오고 v7에서 제거될 거예요.

  • Avatar, Badge, Card, Progress, Steps, Switch, Spin: size는 이제 default 대신 medium을 사용해요.
  • Descriptions: size는 이제 middle 대신 medium, default 대신 large를 사용해요.
  • Table, Divider: size는 이제 middle 대신 medium을 사용해요.
- <Switch size="default" />
+ <Switch size="medium" />

- <Descriptions size="default" />
+ <Descriptions size="large" />

- <Descriptions size="middle" />
+ <Descriptions size="medium" />

- <Table size="middle" />
+ <Table size="medium" />

Splitter collapsibleIcon deprecated (6.4.0) {#splitter-collapsible-icon}

  • Splitter의 collapsibleIcon은 deprecated이며 collapsible.icon으로 대체돼요.

브라우저 지원 변경

  • CSS 변수가 기본으로 활성화되고 모던 브라우저만 지원해요.
  • IE는 더 이상 지원하지 않아요. 일부 오래된 국내 브라우저에서는 호환성 문제가 있을 수 있으니, 배포 전에 타깃 브라우저를 꼭 확인하세요.

원자적 마이그레이션: 패키지 별칭으로 v6 설치

  • 마이그레이션의 영향을 제한하고 싶다면 원자적 마이그레이션을 시도할 수 있어요. 다만 이는 권장되는 업그레이드 경로가 아님을 알아 두세요.

업그레이드 체크리스트

v6로 업그레이드한 뒤 애플리케이션이 올바르게 동작하는지 다음 체크리스트를 확인해 보세요:

  • React 버전: 앱이 React >= 18을 사용하고 @ant-design/v5-patch-for-react-19를 제거했는지 확인하세요.
  • @ant-design/icons 버전: @ant-design/icons가 antd@6에 맞게 >= 6.0.0으로 업그레이드되었는지 확인하세요.
  • 브라우저 호환성: 타깃 사용자 브라우저가 모던하고 CSS 변수를 지원하는지 확인하세요.
  • 커스텀 스타일: 컴포넌트 내부 DOM 노드를 겨냥한 CSS가 있다면 v6에서도 동작하는지 확인하고 필요하면 조정하세요.
  • 오버레이 마스크 설정: Modal, Drawer 등이 마스크 블러를 끌 필요가 있는지 결정하고, 필요 없으면 기본값을 두세요.
  • 빌드 설정: 빌드가 오류 없이 완료되고 CSS 변수 / CSS-in-JS가 올바르게 동작하는지 확인하세요.
  • 콘솔 경고: 앱을 실행하고 콘솔에 표시되는 레거시 API 경고를 해결하세요.

도움이 필요하세요?

업그레이드 중 문제가 생기면 https://new-issue.ant.design/ 에 이슈를 열어 주세요. 가능한 한 빨리 답변하고 문서도 개선할게요.

더 알아보기 (Learn more)