@engie-group/fluid-design-system-react/docs/migration-guides/migration-v2-to-v6.md

Fluid Design System React

# Fluid React Library v2.16.9 → v6.0.0 Migration Guide

This migration guide helps you upgrade your project from Fluid React 2.16.9 version to v6.0.0. It covers breaking changes, new features, and actionable steps for a smooth transition. Follow each migration step and test your UI after each phase.

---

## 1. **Framework & Dependency Update**

### 1.1. **React Version**

- **What changed:** Fluid v6.0.0 requires React 19.
- **Action:** Upgrade your project to React 19. Older React versions are not supported. You may need to apply React update steps first.

---

## 2. **General Property Changes**

- **Many `size` props are now called `scale`** for consistency.
- **Many proprietary props (such as `isDisabled`, `isChecked`, `ariaLabel`, etc.) are now replaced by native HTML attributes.**
- **Action:** Update all component props and usages as described below.

```tsx
// Before
<NJAvatar size="md" />
<NJRadio isDisabled isChecked ariaLabel="..."/>
// After
<NJAvatar scale="md" />
<NJRadio disabled checked aria-label="..." />
```

---

## 3. **Component-by-Component Migration Steps**

### 3.1. **Form Elements (FormItem, Checkbox, Radio, RadioGroup, Slider, Toggle)**

- **What changed:**  
  - Various proprietary props (`isClearable`, `isDisabled`, etc.) replaced by standardized HTML attributes for improved React support and accessibility.
- **Action:**  
  - Use standard HTML props (e.g., `disabled`, `checked`, `aria-label`, `aria-labelledby`, `required`, etc.).
  - Replace `isClearable` with `clearable` (FormItem, Autocomplete).
  - For Checkbox, Radio, RadioGroup, Slider, TabPanel, Toggle: update/remove deprecated props and use native equivalents.

```tsx
// Before
<NJRadio isDisabled isChecked ariaLabel="Label" isRequired />
<NJRadioGroup isDisabled hasError />
<NJFormItem isClearable />
// After
<NJRadio disabled checked aria-label="Label" required />
<NJRadioGroup disabled aria-invalid />
<NJFormItem clearable />
```

---

### 3.2. **Segmented Control**

- **What changed:**  
  - Controlled/uncontrolled modes use `value`/`initialValue` and `onChange`.
  - `size` prop ⇒ `scale`.
  - `label` prop replaced by `aria-label`.
  - Buttons now use children instead of `label` prop.
  - Button props like `isDisabled`, `iconClass`, `onClick` are replaced by native or new conventions: use `disabled`, pass icons via `icon` prop, normal `onClick`.

- **Action:**  
  - Refactor each `NJSegmentedControl` and its buttons.

```tsx
// Before
<NJSegmentedControl value={value} size="md" label="Choose">
  <NJSegmentedControlButton value="opt" label="Opt" />
</NJSegmentedControl>

// After
<NJSegmentedControl initialValue={value} scale="md" aria-label="Choose">
  <NJSegmentedControlButton value="opt">Opt</NJSegmentedControlButton>
</NJSegmentedControl>
```

- For icons overrides, use `icon` prop:

```tsx
// Before
<NJSegmentedControlButton iconName="bolt" iconClass="custom" label="Option" />
// After
<NJSegmentedControlButton icon={<NJIcon name="bolt" className="custom"/>}>Option</NJSegmentedControlButton>
```

- Use `asChild` to customize rendering:

```tsx
<NJSegmentedControlButton value="opt" asChild>
  <a href="#opt">Opt</a>
</NJSegmentedControlButton>
```

---

### 3.3. **Tag**

- **What changed:**  
  - Tag root is now a `span` (was `div`) for better semantics in inline contexts.
  - `size` ⇒ `scale`.
  - Tag is no longer directly clickable; use `actionAsChild` for custom link/button.
- **Action:**  
  - Refactor usages (ensure accessibility for interactive tags).

```tsx
// Before
<NJTag size="md" href="https://...">Clickable Tag</NJTag>
// After
<NJTag scale="md" actionAsChild>
  <a href="https://...">Clickable Tag</a>
</NJTag>
```

---

### 3.4. **Badge**

- **What changed:**  
  - Badge no longer sets icon size for custom icons; use CSS property (--nj-material-icon-size).
- **Action:**  
  - For custom badge icons, use style with the correct CSS property.

```css
// Example CSS
svg {
  width: var(--nj-material-icon-size);
  height: var(--nj-material-icon-size);
}
```

---

### 3.5. **Button**

- **What changed:**  
  - Link properties (`href`, etc.) removed; use `asChild` pattern for rendering as `<a>`.
- **Action:**  
  - Update your button code to match new usage.

```tsx
// Before
<NJButton href="#" label="Go" />
// After
<NJButton asChild>
  <a href="#">Go</a>
</NJButton>
```

---

### 3.6. **Spinner**

- **What changed:**  
  - `size="xxs"` becomes `scale="2xs"`.
  - Remove `isBlock`, `isLoading` props; conditionally render via React.
- **Action:**  
  - Update prop and conditional rendering.

```tsx
// Before
<NJSpinner size="xxs" isLoading={loading} />
// After
{loading && <NJSpinner scale="2xs" />}
```

---

### 3.7. **Heading/Display**

- **What changed:**  
  - Heading `lg` and `xl` font sizes reduced; `2xl` removed—use `NJDisplay scale="xl"` instead.
  - New `ai` variant added for gradient headings.
- **Action:**  
  - Update all affected headings and display usages.

```tsx
// Before
<NJHeading scale="2xl">Big Title</NJHeading>
<NJHeading scale="xl">Title</NJHeading>
// After
<NJDisplay scale="xl">Big Title</NJDisplay>
<NJDisplay scale="md">Title</NJDisplay>
```

---

### 3.8. **Inline Message**

- **What changed:**  
  - Cannot longer pass a title.
  - New `action` prop for passing action elements (like links, buttons); `actionPlacement` controls position.
- **Action:**  
  - Refactor to pass actions as children, remove title.

```tsx
// Before
<NJInlineMessage>
  <span data-child-name="njInlineMessageTitle">Error!</span>
  Content here.
</NJInlineMessage>
// After: No title
<NJInlineMessage actionPlacement="right" action={<NJLink href="#">Learn more</NJLink>}>
  Content here.
</NJInlineMessage>
```

---

## 4. **Other Major Changes**

- **Avatar:**  
  - Background for picture avatars removed.
  - Use new composition pattern and subcomponents as per documentation.

- **IconButton:**  
  - Fully supports `asChild` for wrapping custom elements.

- **Autocomplete / Select / MultiSelect / Popover / Modal / Menu:**  
  - Most legacy or deprecated components removed; use new "composition API" and follow updated documentation patterns.

- **Fonts:**  
  - Lato, Material Icons, Roboto Mono are now bundled—remove manual font imports.
  - You may still import them manually for certain bundlers (there is an issue with NextJS which need to be investigate, fonts are not imported).

- **Design tokens:**  
  - Switch to responsive tokens:  
    - `--nj-semantic-font-size-text-<scale>`, `--nj-semantic-font-size-heading-<scale>`, etc.

---

## 5. **Recommended Migration Steps**

1. Upgrade React to v19, update Fluid dependencies.
2. Refactor HTML/JSX code for all component and prop updates described above.
3. Remove all deprecated and legacy components and props.
4. Remove font imports and update CSS for new tokens.
5. Test your app thoroughly after each change.
6. Consult Fluid documentation for new advanced usages and edge cases.

---

## 6. **Testing & Troubleshooting**

- Test all page sections for correct rendering and interactions.
- Check lists, buttons, avatars, menus, spinner, heading, and messages.
- Review accessibility changes, and ensure you use native HTML attributes.
- See Fluid documentation for up-to-date examples.

---

**Done! Your app is now on Fluid React v6.0.0.**

If you encounter issues or need clarification, please reach out to us.