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.

• 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:

• Reach out to us on Github: submit an issue and we will help you out.

• Join our public community Slack and ask a question on the #forma36 channel. We are there to help you out!