Migration Guide

Introducing version 5 of the spirit-web-react package.

Please follow these steps to safely upgrade to Spirit Design System v5 components.

ℹ️ Don't forget to check the migration guide of the spirit-web package for general changes in available feature flags, CSS, and other changes that might affect your project.

Overview

• Component Changes
  • Collapse: hideOnCollapse Prop Renamed to isDisposable
  • Flex: Direction Prop Values Changed
  • Avatar: Component Name Stabilized
  • Slider: Component Name Stabilized
  • EmptyState: Component Name Stabilized
  • Toggle: Component Name Stabilized
  • Truncate: Component Name Stabilized and lines Prop Changed

Component Changes

Collapse: hideOnCollapse Prop Renamed to isDisposable

The hideOnCollapse prop in UncontrolledCollapse component was renamed to isDisposable.

Migration Guide

🪄 Use codemods to automatically update your codebase:

                                                
                                                npx @alma-oss/spirit-codemods -p <path> -t v5/web-react/collapse-isDisposable-prop

👉 See Codemods documentation for more details.

🔧 Manual Migration Steps

Manually replace the prop in your project.

• <UncontrolledCollapse hideOnCollapse … /> → <UncontrolledCollapse isDisposable … />

Flex: Direction Prop Values Changed

The direction prop values in Flex component were changed from row/column to horizontal/vertical.

Migration Guide

🪄 Use codemods to automatically update your codebase:

                                                
                                                npx @alma-oss/spirit-codemods -p <path> -t v5/web-react/flex-direction-values

👉 See Codemods documentation for more details.

🔧 Manual Migration Steps

Manually replace the prop values in your project.

• <Flex direction="row" … /> → <Flex direction="horizontal" … />
• <Flex direction="column" … /> → <Flex direction="vertical" … />
• <Flex direction={{ mobile: "column", tablet: "row" }} … /> → <Flex direction={{ mobile: 'vertical', tablet: 'horizontal' }} … />

Avatar: Component Name Stabilized

The UNSTABLE_Avatar component was stabilized and renamed to Avatar.

Migration Guide

🪄 Use codemods to automatically update your codebase:

                                                
                                                npx @alma-oss/spirit-codemods -p <path> -t v5/web-react/unstable-avatar-component-name

👉 See Codemods documentation for more details.

🔧 Manual Migration Steps

Manually replace the component name in your project.

• UNSTABLE_Avatar → Avatar

Slider: Component Name Stabilized

The UNSTABLE_Slider component was stabilized and renamed to Slider.

Migration Guide

🪄 Use codemods to automatically update your codebase:

                                                
                                                npx @alma-oss/spirit-codemods -p <path> -t v5/web-react/unstable-slider-component-name

👉 See Codemods documentation for more details.

🔧 Manual Migration Steps

Manually replace the component name in your project.

• UNSTABLE_Slider → Slider
• UNSTABLE_UncontrolledSlider → UncontrolledSlider

EmptyState: Component Name Stabilized

The UNSTABLE_EmptyState and UNSTABLE_EmptyStateSection components were stabilized and renamed to EmptyState and EmptyStateSection.

Migration Guide

🪄 Use codemods to automatically update your codebase:

                                                
                                                npx @alma-oss/spirit-codemods -p <path> -t v5/web-react/unstable-emptystate-component-name

👉 See Codemods documentation for more details.

🔧 Manual Migration Steps

Manually replace the component names in your project.

• UNSTABLE_EmptyState → EmptyState
• UNSTABLE_EmptyStateSection → EmptyStateSection

Toggle: Component Name Stabilized

The UNSTABLE_Toggle component was stabilized and renamed to Toggle.

Migration Guide

🪄 Use codemods to automatically update your codebase:

                                                
                                                npx @alma-oss/spirit-codemods -p <path> -t v5/web-react/unstable-toggle-component-name

👉 See Codemods documentation for more details.

🔧 Manual Migration Steps

Manually replace the component name in your project.

• UNSTABLE_Toggle → Toggle

Truncate: Component Name Stabilized and lines Prop Changed

The UNSTABLE_Truncate component was stabilized and renamed to Truncate. Additionally, the lines prop was replaced with mode="lines" and limit={lines}.

Migration Guide

🪄 Use codemods to automatically update your codebase:

                                                
                                                npx @alma-oss/spirit-codemods -p <path> -t v5/web-react/unstable-truncate-component-name-and-lines-prop

👉 See Codemods documentation for more details.

🔧 Manual Migration Steps

Manually replace the component name and prop in your project.

• UNSTABLE_Truncate → Truncate
• <Truncate lines={3} … /> → <Truncate mode="lines" limit={3} … />

---

Please refer back to these instructions or reach out to our team if you encounter any issues during migration.