# Migration

This document lists migration guidance for new features and breaking changes.

## v3 to v4

`@splunk/react-icons@4.0.0` brings new outline and fill modes, improved accessibility, and more than 400 newly designed icons.
Check out the docs to explore these new features and the redesigned icon library page.

When migrating from `@splunk/react-icons@3.x` to `@splunk/react-icons@4.0.0` there are two options: continue to use the Enterprise icons or migrate to the new icons.


### Enterprise icons
To continue using the Enterprise icons the only thing that has changed is the icons’ import location which is now from an `enterprise` directory. 

The following code in 3.x: 

```
import External from ‘@splunk/react-icons/External’;
```

should be changed to:

```
import External from’@splunk/react-icons/enterprise/External’;
```

And that’s it! The API of these icons have remained unchanged, so although this is a major version upgrade, it is backwards compatible, and you can continue to use icons in the same way after updating the import path. 

In most cases, you may be able to safely find and replace ’@splunk/react-icons/’ with ‘@splunk/react-icons/enterprise/’

### Migrating to the new Icons
When adopting new icons, there are a few changes to the API that must be considered. 

#### Accessibility

In version 3.x icons had default labels and enabled the browser tooltip. This meant there were icons that were visually the same but shipped as a separate icon to have a different label: e.g. Close and Cancel. 

In version 4.x icons are now decorative by default; meaning they do not have labels or interactivity. Migrating will require deciding if the icon is functional or decorative so the correct accessibility attributes can be used. See below how to migrate a Button in both of these scenarios or check the docs for examples on how to use icons in an accessible way.

##### Migrating a decorative icon

If previously you had a react-ui Button with a decorative icon it may have looked like: 

```
import Button from '@splunk/react-ui/Button';
import Print from '@splunk/react-icons/Print';

const MyButton = () => {
return (<Button icon={<Print screenReaderText={null} />} label="Print" />);
}
```

In v4 there is no default accessible name added to the icon. The screenReaderText prop has been removed for this reason. Migrated code should look like this: 

```
import Button from '@splunk/react-ui/Button';
import Printer from '@splunk/react-icons/Printer';

const MyButton = () => {
    return (
        <Button icon={<Printer />} label="Print" />
    );
}
```

##### Migrating a functional icon

If the icon instead is functional and needs an accessible name it may have looked like: 

```
import Button from '@splunk/react-ui/Button';
import Print from '@splunk/react-icons/Print';

const MyButton = () => {
    return (
        <Button icon={<Print />} />
    );
}
```

This relied on the icon to provide the accessible name by default. Now that icons are decorative by default the migrated could should look like this: 

```
import Button from '@splunk/react-ui/Button';
import Printer from '@splunk/react-icons/Printer';

const MyButton = () => {
    return (
        <Button icon={<Printer />} aria-label="Print" />
    );
}
```

#### API 

The API of icons and the underlying SVG component has been significantly reduced in favor of passing through native SVG attributes. 

The following attributes have been removed from the API but are passed through as SVG attributes if needed: width, height, viewBox, and preserveAspectRatio. If you relied on these attributes previously note that the behavior may have changed as it is determined according to browser implementation.

##### `screenReaderText`
This prop has been removed in favor of native aria-* attributes or using `ScreenReaderContent` from `@splunk/react-ui` 

In v3 the prop may have been used like this: 
```
<External screenReaderText={'Open in new tab'} />
```

Which should be migrated to one of these options:
```
// using aria-label
<ArrowSquareTopRight aria-label="Open in new tab" aria-hidden="false" />
```

```
// or a sibling ScreenReaderContent component
<>
    <ArrowSquareTopRight />
    <ScreenReaderContent>(Opens new window)</ScreenReaderContent>
</>
```

##### `size`

This prop has been removed. Instead pass width and height or use styled-components to set the dimensions via CSS.

##### `hideDefaultTooltip`

This behavior has been removed. Browser tooltips are not added by default and the icons source no longer contains `<title>` elements with text. Using a Tooltip from react-ui is preferred to give a label on hover. In cases where the native tooltip is still desired, Icons accept children elements that are inserted as nodes within the svg element: 

```
import ArrowSquareTopRightIcon from '@splunk/react-icons/ArrowSquareTopRight;

<ArrowSquareTopRightIcon>
	<title>Open in window</title>
</ArrowSquareTopRightIcon>
```

#### Mapping
Here are the mappings for commonly used icons from v3 to the new icon set in v4: 

```
| react-icons v3 | react-icons v4            |
|----------------|---------------------------|
| Cancel         | Cross                     |
| Close          | Cross                     |
| Clear          | Cross                     |
| Plus           | Plus                      |
| Error          | ExclamationSquare, filled |
| InfoCircle     | InformationCircle         |
| ChevronRight   | ChevronRight              |
| Success        | CheckCircle               |
| Trash          | TrashCanCross             |
| Warning        | ExclamationTriangle       |
| ChevronDown    | ChevronDown               |
| Pencil         | Pencil                    |
| ChevronLeft    | ChevronLeft               |
| Refresh        | ArrowsCircularDouble      |
| MoreVertical   | DotsThreeVertical         |
| Remove         | Cross                     |
| Search         | Magnifier                 |
```