How to migrate your Forma 36 v3 to v4
This step by step guide details how to migrate your Forma 36 components from v3 to v4.
Version 4 of Forma 36 contains multiple fixes requested by the community, such as accessibility improvements, better developer experience, and performance improvements.
Starting with version 4, Forma 36 is split into separate packages, enabling you to download only the specific package for the component you need. š
To get the latest updates, you must migrate your project to version 4 of Forma 36. This guide offers you tools and guidance to do it easily by:
Upgrading Forma 36 from version 3 to version 4
Dealing with breaking changes
āļø Step 1: Package upgrade
In version 4, our components are separated into packages that you can use separately. We introduced emotion to our components, so you no longer have to add separate css files to your project. It will work out of the box.Ā Learn how to upgrade your existing Forma 36 components from version 3 to version 4
āļø Step 2: Breaking changes in components
All the requests and fixes that have been waiting for the next version of the library have been fixed in version 4. The API is now more consistent as some components received major improvements, and all of them were migrated to ourĀ new code style guide.
To migrate your project easily, we provided a codemod for most of the components. For the ones that do not have a codemod, we created detailed documentation on how to do it.
Accordion: Accordion became a compound component. For more information, seeĀ the detailed documentation.
Asset: No changes were made. For more information, seeĀ the detailed documentation.
Autocomplete: API improvements, some properties were removed and manual migration is required. For more information, seeĀ the detailed documentation.
ButtonĀ API improvements: Some properties of the Button component were migrated or changed. For more information, seeĀ the detailed documentation.
Card, AssetCard, and EntryCardĀ : Some properties of the Card, AssetCard, and EntryCard components were migrated or changed. For more information, seeĀ the detailed documentation.
CopyButtonĀ API improvements: Some properties of the CopyButton component were migrated or changed. For more information, seeĀ the detailed documentation.
DateTime: You only need to update theĀ
formatĀ prop value. For more information, seeĀ the detailed documentation.Dropdown: The Dropdown component was removed in version 4. Instead, you can use three new components: Menu, Autocomplete, or Popover for each case. For more information, seeĀ the detailed documentation.
EditorToolbar: The EditorToolbar component was removed in version 4. For more information, seeĀ the detailed documentation.
EmptyState: The EmptyState component was removed in version 4. For more information, seeĀ the detailed documentation.
EntityListĀ API improvements: Some properties of the EntityList component were migrated or changed. For more information, seeĀ the detailed documentation.
Flex: Some properties of the Flex component were migrated or changed. For more information, seeĀ the detailed documentation.
Form Components: We changed how most of the Form components work:Ā Checkbox, CheckboxField, TextInput, TextField, Textarea, Select, SelectField, RadioButton, RadioButtonField, Switch. For more information, seeĀ the detailed documentation.
Grid: Some properties of the Grid component were migrated or changed. For more information, seeĀ the detailed documentation.
HelpText: Some properties of the HelpText component were migrated or changed. For more information, seeĀ the detailed documentation.
Icon: Now you can use any icon from our library directly as a component, or wrap an external icon in our Icon component to use consistent sizing and styling. For more information, seeĀ the detailed documentation.
IconButton: Now you can pass any icon as an element to the IconButton component. For more information, seeĀ the detailed documentation.
Illustration: The Illustration component was removed in version 4. For more information, seeĀ the detailed documentation
InViewport: The InViewport component was removed in version 4. For more information, seeĀ the detailed documentation.
List: Some properties of the List component were migrated or changed. For more information, seeĀ the detailed documentation.
Modal: We changed the way you import the Modal component. For more information, seeĀ the detailed documentation.
Note: Some properties of the Note component were migrated or changed. For more information, seeĀ the detailed documentation.
Notification: Some properties of the Notification component were migrated or changed. For more information, seeĀ the detailed documentation.
Pill: No changes were made. For more information, seeĀ the detailed documentation.
ProductIcon: ProductIcon is a set of Contentful specific icons. We removed this component from the public repository. Submit anĀ issue in GithubĀ if you need to use this component in your project.
RelativeDateTime: There are no changes, just import the new component. For more information, seeĀ the detailed documentation.
Skeleton: Some properties of the Skeleton component were renamed. For more information, seeĀ the detailed documentation.
Spinner: Some properties of the Spinner component were renamed. For more information, seeĀ the detailed documentation.
TabFocusTrap: The TabFocusTrap component was removed in version 4. For more information, seeĀ the detailed documentation.
Table: Table becomes a compound component in version 4. For more information, seeĀ the detailed documentation.
Tabs: The Tabs component API has been improved. For more information, seeĀ the detailed documentation.
TagĀ becomes Badge: We migrated the Tag component to Badge. For more information, seeĀ the detailed documentation.
TextLink: The TextLink component API has been improved. For more information, seeĀ the detailed documentation.
ToggleButton: Some properties of the ToggleButton component were migrated or changed. For more information, seeĀ the detailed documentation.
Tooltip: Two props got renamed:Ā
containerElementĀ toĀas; andĀplaceĀ toĀplacement. For more information, seeĀ the detailed documentation.Typography: The Typography component was removed, and some properties of theĀ Paragraph, Heading, SectionHeading, Subheading,Ā andĀ DisplayTextĀ components were renamed. For more information, seeĀ the detailed documentation.
Workbench: The only change in version 4 is from where you import the Workbench component. For more information, seeĀ the detailed documentation.
š¤ Step 3: Have a great time using Forma 36
You have successfully upgraded to version 4, so congratulations and welcome to the new version of Forma 36! ššš For any questions or issues, you can: