|
| 1 | +import { Message } from 'semantic-ui-react' |
| 2 | + |
1 | 3 | export const meta = { |
2 | | - title: 'Migration Guide', |
| 4 | + title: 'Migration Guide to v3', |
3 | 5 | prevPage: { title: 'Prototypes', href: '/prototypes' }, |
4 | 6 | } |
5 | 7 |
|
6 | | -This is a reference for upgrading your application to v2 of Semantic UI React. While there's a lot covered here, you probably won't need to do everything for your app. |
| 8 | +This is a reference for upgrading your application to v3 of Semantic UI React. |
7 | 9 |
|
8 | | -## Upgrade of `react-popper` for `Popup` |
| 10 | +<Message |
| 11 | + info |
| 12 | + size='tiny' |
| 13 | + header='Looking to upgrade your app to v2?' |
| 14 | + content={ |
| 15 | + <> |
| 16 | + Migration guide to Semantic UI React is available <a href='/migration-guide-v-2'>here</a>. |
| 17 | + </> |
| 18 | + } |
| 19 | +/> |
9 | 20 |
|
10 | | -_Popper.js v1 is out of date, v2 was released in Dec 2019, time to upgrade 🚀_ |
| 21 | +## Native ref support |
11 | 22 |
|
12 | | -### `offset` can't be specified as string anymore |
| 23 | +<Message |
| 24 | + compact |
| 25 | + content='This change can be considered as improvement. You should not be affected if you did not used `ref` on Semantic UI React components.' |
| 26 | + header='Risk: low' |
| 27 | + size='mini' |
| 28 | + color='teal' |
| 29 | +/> |
13 | 30 |
|
14 | | -Previously it was possible to pass different units to the offset prop as units. This behavior was changed and `offset` accepts a tuple or a function. Examples in our docs were also updated. |
| 31 | +The main change in v3 is the support of [native refs to components](https://react.dev/reference/react/forwardRef) to avoid usage of [deprecated `ReactDOM.findDOMNode()`](https://react.dev/reference/react-dom/findDOMNode). It means that `ref` prop can be used to get a reference to the underlying DOM element instead of a React component instance. |
15 | 32 |
|
16 | | -```diff |
17 | | - <> |
18 | | -- <Popup offset="50px" /> |
19 | | -+ <Popup offset={[50, 0]} /> |
20 | | - <br /> |
21 | | -- <Popup offset="-100%p" /> |
22 | | -+ <Popup offset={({ popper }) => [-popper.width, 0]} /> |
23 | | - </> |
| 33 | +For example, you can use `ref` to get a reference to the underlying DOM element of `Button` component: |
| 34 | + |
| 35 | +```jsx |
| 36 | +import { Button } from 'semantic-ui-react' |
| 37 | + |
| 38 | +const App = () => { |
| 39 | + const buttonRef = React.useRef() |
| 40 | + |
| 41 | + React.useEffect(() => { |
| 42 | + console.log(buttonRef.current) |
| 43 | + }, []) |
| 44 | + |
| 45 | + return <Button ref={buttonRef} /> |
| 46 | +} |
24 | 47 | ``` |
25 | 48 |
|
26 | | -### `popperModifiers` should be defined as array now |
| 49 | +All components from Semantic UI React v3 support native ref forwarding. |
| 50 | + |
| 51 | +### Note on `Button`, `Input`, `TextArea` |
| 52 | + |
| 53 | +`Button`, `Input` and `TextArea` implemented some methods like `focus()` and `blur()` on their class instances. However, now you will get a reference to the underlying DOM element instead of a React component instance. You should be able to call these methods directly on the DOM element without any issues. |
| 54 | + |
| 55 | +## Removal of `Ref` component |
| 56 | + |
| 57 | +<Message |
| 58 | + compact |
| 59 | + content='You will be affected if you use `Ref` component.' |
| 60 | + header='Risk: high' |
| 61 | + size='mini' |
| 62 | + color='orange' |
| 63 | +/> |
27 | 64 |
|
28 | | -The `popperModifiers` prop should be defined as an array with changed format (see [Popper docs](https://popper.js.org/docs/v2/migration-guide/#10-update-modifiers)). |
| 65 | +Because of the native ref support, `Ref` component is no longer needed and was removed as it used deprecated APIs. |
29 | 66 |
|
30 | 67 | ```diff |
31 | | --<Popup popperModifiers={{ preventOverflow: { padding: 0 } }} /> |
32 | | -+<Popup popperModifiers={[{ name: 'preventOverflow', options: { padding: 0 } }]} /> |
| 68 | +function App() { |
| 69 | +- return ( |
| 70 | +- <Ref innerRef={buttonRef}> |
| 71 | +- <Button /> |
| 72 | +- </Ref> |
| 73 | +- ) |
| 74 | ++ return <Button ref={buttonRef} /> |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +As we exported `Ref` component and recommended its usage everywhere we moved out `Ref` component to a separate package (`@semantic-ui-react/component-ref`). This means that you can use it already with both v2 & v3 to make the upgrade smoother. |
| 79 | + |
| 80 | +```diff |
| 81 | +-import { Ref } from "semantic-ui-react"; |
| 82 | ++import Ref from "@semantic-ui-react/component-ref"; |
33 | 83 | ``` |
34 | 84 |
|
35 | | -### a wrapping element around `Popup` |
| 85 | +<Message compact size='tiny' warning> |
| 86 | + `@semantic-ui-react/component-ref` is considered as a deprecated package, we don't plan maintain |
| 87 | + it, so please consider migration anyway. It also will not receive fixes related to usage of |
| 88 | + deprecated APIs from React. |
| 89 | +</Message> |
36 | 90 |
|
37 | | -We started to use an additional wrapping element around `Popup` for positioning, see [Semantic-Org/Semantic-UI-React#3947](https://github.com/Semantic-Org/Semantic-UI-React/pull/3947) for more details. To pass props to this element `popper` shorthand can be used, see [an example](/modules/popup/#usage-position-fixed). |
| 91 | +More details on this change in [Semantic-Org/Semantic-UI-React#4286](https://github.com/Semantic-Org/Semantic-UI-React/pull/4286). |
38 | 92 |
|
39 | | -⚠️We also made a fix in [Semantic-Org/Semantic-UI-React#4094](https://github.com/Semantic-Org/Semantic-UI-React/pull/4094) to transfer `zIndex` value to avoid any breaks. |
| 93 | +## Removal of `Visibity` component |
40 | 94 |
|
41 | | -## `Responsive` component was removed |
| 95 | +<Message |
| 96 | + compact |
| 97 | + content='You will be affected if you use `Visibility` component.' |
| 98 | + header='Risk: high' |
| 99 | + size='mini' |
| 100 | + color='orange' |
| 101 | +/> |
42 | 102 |
|
43 | | -`Responsive` component was deprecated in 1.1.0. There are two main reasons for the removal: there is no connection between breakpoints and pure SSR (server side rendering) support. |
| 103 | +The main reason is performance that is far away from native APIs. We suggest to use [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) directly or via React wrappers, for example: [react-intersection-observer](https://www.npmjs.com/package/react-intersection-observer). |
44 | 104 |
|
45 | | -[@artsy/fresnel](https://github.com/artsy/fresnel) was proposed as a replacement as it properly handles SSR scenarios. |
| 105 | +As it's not a straightforward replacement that may cause issues with adoption we moved out `Visibility` component to a separate package (`@semantic-ui-react/component-visibility`). This means that you can use it already with v2 or upcoming v3: |
46 | 106 |
|
47 | 107 | ```diff |
48 | | -+import { createMedia } from "@artsy/fresnel"; |
49 | | -import React from "react"; |
50 | | --import { Responsive, Segment } from "semantic-ui-react"; |
51 | | -+import { Segment } from "semantic-ui-react"; |
52 | | - |
53 | | -+const AppMedia = createMedia({ |
54 | | -+ breakpoints: { |
55 | | -+ mobile: 320, |
56 | | -+ tablet: 768, |
57 | | -+ computer: 992, |
58 | | -+ largeScreen: 1200, |
59 | | -+ widescreen: 1920 |
60 | | -+ } |
61 | | -+}); |
62 | | -+const mediaStyles = AppMedia.createMediaStyle(); |
63 | | -+const { Media, MediaContextProvider } = AppMedia; |
64 | | - |
65 | | --const App = () => ( |
66 | | -- <Responsive as={Segment} {...Responsive.onlyMobile}> |
67 | | -- Mobile |
68 | | -- </Responsive> |
69 | | --) |
70 | | -+const App = () => ( |
71 | | -+ <> |
72 | | -+ <style>{mediaStyles}</style> |
73 | | -+ <MediaContextProvider> |
74 | | -+ <Segment as={Media} at="mobile"> |
75 | | -+ Mobile |
76 | | -+ </Segment> |
77 | | -+ </MediaContextProvider> |
78 | | -+ </> |
79 | | -+); |
| 108 | +-import { Visibility } from "semantic-ui-react"; |
| 109 | ++import Visibility from "@semantic-ui-react/component-visibility"; |
80 | 110 | ``` |
81 | 111 |
|
82 | | -The full migration guide is available in [Semantic-Org/Semantic-UI-React#4008](https://github.com/Semantic-Org/Semantic-UI-React/pull/4008), it contains more detailed explanation and examples for Next.js & Gatsby. |
| 112 | +<Message compact size='tiny' warning> |
| 113 | + `@semantic-ui-react/component-visibility` is considered as a deprecated package, we don't plan |
| 114 | + maintain it, so please consider migration anyway. It also will not receive fixes related to usage |
| 115 | + of deprecated APIs from React. |
| 116 | +</Message> |
| 117 | + |
| 118 | +More details on this change in [Semantic-Org/Semantic-UI-React#4257](https://github.com/Semantic-Org/Semantic-UI-React/pull/4257). |
83 | 119 |
|
84 | | -## `MountNode` component was removed |
| 120 | +### Removal of static properties on `Transition` component |
| 121 | + |
| 122 | +<Message |
| 123 | + compact |
| 124 | + content='These properties were never referenced in documentation or suggested to be used.' |
| 125 | + header='Risk: negligible' |
| 126 | + size='mini' |
| 127 | + color='green' |
| 128 | +/> |
| 129 | + |
| 130 | +Some static properties on `Transition` component were removed: |
| 131 | + |
| 132 | +```diff |
| 133 | +- static INITIAL = TRANSITION_STATUS_INITIAL |
| 134 | +- static ENTERED = TRANSITION_STATUS_ENTERED |
| 135 | +- static ENTERING = TRANSITION_STATUS_ENTERING |
| 136 | +- static EXITED = TRANSITION_STATUS_EXITED |
| 137 | +- static EXITING = TRANSITION_STATUS_EXITING |
| 138 | +- static UNMOUNTED = TRANSITION_STATUS_UNMOUNTED |
| 139 | +``` |
85 | 140 |
|
86 | | -`MountNode` component was deprecated in 1.1.0. The main reason for the removal is that the component should not be a part of the public API as it solves our specific issue with the `Modal` component. |
87 | | -Additional details are available in [Semantic-Org/Semantic-UI-React#4027](https://github.com/Semantic-Org/Semantic-UI-React/pull/4027). |
| 141 | +This properties should not be used in public APIs, but it's still a breaking change. |
0 commit comments