apps/public-docsite-v9/src/Concepts/Migration/FromV8/ComponentMapping.mdx
import { Meta } from '@storybook/addon-docs/blocks';
<Meta title="Concepts/Migration/from v8/Component Mapping" />Install Fluent UI v9: To begin migration, install the latest Fluent UI React v9 package.
npm install @fluentui/react-components
Update Imports: Update your component imports to use the v9 components. Use the component mapping table below to assist.
Refactor Code: Refactor your code to accommodate changes in API, props, and new functionalities provided by v9 components.
Here is the mapping of v8 components to their v9 component replacement or equivalent. This table provides a side-by-side comparison of React v8 components and their corresponding counterparts in React v9. Where a direct v9 equivalent doesn't exist, an alternative or note is provided.
| **React v8 Component** | **React v9 Component** | **Notes** |
|---|---|---|
| `ActionButton` | [`Button`](/docs/components-button-button--docs) | Use `Button` with `iconPosition="before"` for similar functionality. |
| `ActivityItem` | Not available | No direct equivalent in v9; custom implementation needed. |
| `Announced` | Not available | No direct equivalent in v9. |
| `Breadcrumb` | [`Breadcrumb`](/docs/components-breadcrumb--docs) | No major changes; available in v9. |
| `Button` | [`Button`](/docs/components-button-button--docs) | Unified button API; use `appearance` prop for variants like `PrimaryButton`. |
| `Callout` | [`Popover` ](/docs/components-popover--docs) | Replaced by `Popover`, with enhanced accessibility and customization. |
| `Calendar` | [`CalendarCompat`](/docs/compat-components-calendar--docs) | Use the compact variant in v9. |
| `CommandBar` | [`Toolbar`](/docs/components-toolbar--docs) | Similar functionality in v9. |
| `CommandBarButton` | [`Toolbar`](/docs/components-toolbar--docs) | Similar functionality in v9. |
| `CommandButton` | [`MenuButton`](/docs/components-button-docs--docs) | Similar functionality in v9. |
| `CompoundButton` | [`CompoundButton`](/docs/components-button-compoundbutton--docs) | Similar functionality in v9. |
| `Charts` | [`Migration Guide`](/docs/concepts-migration-from-v8-components-charts-migration--docs) | No direct equivalent in v9. |
| `Checkbox` | [`Checkbox`](/docs/components-checkbox--docs) | API remains mostly the same in v9. |
| `ChoiceGroup` | [`RadioGroup`](/docs/components-radiogroup--docs) | Renamed to `RadioGroup` with similar functionality. |
| `Coachmark` | [`TeachingPopover`](/docs/components-teachingpopover--docs) | Use `TeachingPopover` in v9 for the same functionality. |
| `ColorPicker` | [`ColorPicker`](/docs/components-colorpicker--docs) | No major changes in v9. |
| `ComboBox` | [`Combobox`](/docs/components-combobox--docs) | Renamed to `Combobox` with API improvements. |
| `CommandBar` | [`Toolbar`](/docs/components-toolbar--docs) | CommandBar replaced by `Toolbar` for managing actions. |
| `ContextualMenu` | [`Menu`](/docs/components-menu-menu--docs) with Button as the `MenuTrigger` | Use `Menu` in v9 with `MenuTrigger`. |
| `DefaultButton (anchor)` | [`Button`](/docs/components-button-button--docs) | Use `Button` in v9. |
| `DefaultButton (menu)` | [`MenuButton`](/docs/components-button-menubutton--docs) | Use `Button` in v9. |
| `DatePicker` | [`DatePickerCompat`](/docs/compat-components-datepicker--docs) | API remains similar with enhanced theming options. |
| `DetailsList` | [`DataGrid`](/docs/components-datagrid--docs) | Experimental `DataGrid` in v9 could be a substitute. |
| `Dialog` | [`Dialog`](/docs/components-dialog--docs) | Refined API, using `open` and `onOpenChange` props. |
| `DocumentCard` | [`Card`](/docs/components-card-card--docs) | Use `Card` in v9. |
| `Dropdown` | [`Dropdown`](/docs/components-dropdown--docs) | API and performance enhancements. |
| `Fabric` | `FluentProvider` | Use `FluentProvider` for managing themes and global context. |
| `Facepile` | [`AvatarGroup`](/docs/components-avatargroup--docs) | Replaced by `AvatarGroup` in v9. |
| `FocusTrapZone` | [`Tabster`](https://tabster.io/) | Use `Tabster`. |
| `FocusZone` | [`Tabster`](https://tabster.io/) | Use `Tabster`. |
| `GroupedList` | [`Tree`](/docs/components-tree--docs) | Use `Tree` in v9. |
| `HoverCard` | Not available | No direct equivalent; could use `Popover` with custom behavior. |
| `Icon` | [`@fluentui/react-icons package`](/docs/icons-overview--docs) | v9 provides more customization options. |
| `IconButton` | [`Button`](/docs/components-button-button--docs) | v9 provides more customization options. |
| `Image` | [`Image`](/docs/components-image--docs) | No major changes in v9. |
| `Keytips` | [`Keytips`](/docs/contrib_packages-react-keytips--docs) | No major changes in v9. |
| `Label` | [`Label`](/docs/components-label--docs) | Similar functionality in v9. |
| `Layer` | [`Portal`](/docs/components-portal--docs) | Use `Portal` for similar layering behavior. |
| `Link` | [`Link`](/docs/components-link--docs) | Available in v9, with better accessibility handling. |
| `List` | [`List`](/docs/components-list--docs) | Enhanced performance in v9. |
| `MarqueeSelection` | Not available | No direct equivalent in v9. |
| `MessageBar` | [`MessageBar`](/docs/components-messagebar--docs) | Available in v9, with better accessibility handling. |
| `Modal` | [`Dialog`](/docs/components-dialog--docs) | Dialog in v9 serves the modal role with updated API. |
| `Nav` | [`Nav`](/docs/components-nav--docs) | No major changes; available in v9 with improvements. |
| `OverflowSet` | [`Dialog`](/docs/components-overflow--docs) | No direct equivalent; consider `Dialog` for overflow menus. |
| `Overlay` | [`Portal`](/docs/components-portal--docs) | Replaced with `Dialog` in v9. |
| `Panel` | [`Drawer`](/docs/components-drawer--docs) | Replaced by `Drawer` for side panel navigation. |
| `Popup` | [`Dialog`](/docs/components-dialog--default) | Replaced by `Dialog` |
| `PeoplePicker` | [`TagPicker`](/docs/components-tagpicker--docs) | Replaced by `TagPicker` for improved functionality. |
| `Persona` | [`Persona`](/docs/components-persona--docs) | No major changes; available in v9 with improvements. |
| `Pickers` | Not available | No direct equivalent in v9. |
| `Pivot`, `PivotItem` | [`TabList`, `Tab`](/docs/components-tablist--docs) | Replaced by `TabList` in v9. |
| `ProgressIndicator` | [`ProgressBar`](/docs/components-progressbar--docs) | Renamed to `ProgressBar` in v9; similar functionality. |
| `Rating` | [`Rating`](/docs/components-rating--docs) | Available in v9 with slight API refinements. |
| `ResizeGroup` | Not available | No direct equivalent in v9. |
| `ScrollablePane` | Not available | No direct equivalent in v9. |
| `SearchBox` | [`SearchBox`](/docs/components-searchbox--docs) | Available in v9 with updated API and better accessibility. |
| `Separator` | [`Divider`](/docs/components-divider--docs) | Replaced by `Divider` in v9. |
| `Shimmer` | [`Skeleton`](/docs/components-skeleton--docs) | Updated to `Skeleton` in v9 for loading states. |
| `Slider` | [`Slider`](/docs/components-slider--docs) | API enhancements for better customization. |
| `SplitButton` | [`Menu with SplitButton as the Menu Trigger`](/docs/components-button-splitbutton--docs) | Various updates done in v9. |
| `SpinButton` | [`SpinButton`](/docs/components-spinbutton--docs) | Available in v9 with improved API. |
| `Spinner` | [`Spinner`](/docs/components-spinner--docs) | Available in v9 with better control over animations. |
| `Stack` | [`Migration Guide`](/docs/concepts-migration-from-v8-components-flex-stack--docs), [`StackShim`](/docs/migration-shims-v8-stackshim--playground) | Various changes in v9. |
| `SwatchColorPicker` | [`SwatchPicker`](/docs/components-swatchpicker--docs) | Replaced by `SwatchPicker` in v9 for color selection. |
| `TagPicker` | [`TagPicker`](/docs/components-tagpicker--docs) | No major changes; retained as `TagPicker`. |
| `TeachingBubble` | [`TeachingPopover`](/docs/components-teachingpopover--docs) | Replaced by `TeachingPopover` in v9. |
| `Text` | [`Text`](/docs/components-text--docs) | Similar functionality in v9. |
| `TextField` | [`Input`](/docs/components-input--docs) | Replaced by `Input` in v9 for text input functionality. |
| `ThemeProvider` | [`FluentProvider`](/docs/components-fluentprovider--docs) | Replaced by `FluentProvider` in v9; similar behavior. |
| `TimePicker` | [`TimePickerCompat`](/docs/compat-components-timepicker--docs) | Replaced by `TimePickerCompat` in v9; similar behavior. |
| `ToggleButton` | [`ToggleButton`](/docs/components-button-togglebutton--docs) | No major changes in v9. |
| `Toggle` | [`Switch`](/docs/components-switch--docs) | Renamed to `Switch` in v9; similar behavior. |
| `Tooltip` | [`Tooltip`](/docs/components-tooltip--docs) | No major changes in v9. |
React v9 introduces several new components that were not present in v8:
Persona for rendering user images.Facepile.Panel for side-drawer navigation.Callout with improved accessibility.Pivot for tabbed navigation.ProgressIndicator, with similar functionality but refined API.TextField for simpler text input handling.Shimmer.Toggle for binary options.SwatchColorPicker with added functionality.TeachingBubble and Coachmark in v8.Some components in React v8 are not present in v9 or been replaced. Hereโs a list of deprecated components:
CoachmarkActivityItemHovercardMarqueeSelectionResizeGroupScrollablePaneDetailsListPickersPopupFor more information on Fluent UI v9, consult these resources: