Skip to content

docs(v6): write v5 to v6 migration guide #5059

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mikolajadamowicz wants to merge 3 commits into
base: main
Choose a base branch
from
+626 −112
Open

docs(v6): write v5 to v6 migration guide #5059

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a08a379
docs: write full v5→v6 migration guide
mikolajadamowicz Aug 21, 2026
4f59c3e
docs: icon migration compatibility update
mikolajadamowicz Aug 24, 2026
f98c81b
docs: clarify vector icons auto-detection in v6 icon guides
mikolajadamowicz Aug 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions docs/6.x/docs/guides/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,15 @@ Minimum requirements:

Follow the [React Native Reanimated installation guide](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/).

If you use Expo, you don't need to install vector icons - those are the part of the expo package. However, if you have a `babel.config.js` or `.babelrc` file, make sure that it includes `babel-preset-expo`.
You also need to install [@react-native-vector-icons/material-design-icons](https://github.com/oblador/react-native-vector-icons/tree/master/packages/material-design-icons). It is the only icon package Paper detects, `@expo/vector-icons` is no longer picked up automatically:

```bash
npx expo install @react-native-vector-icons/material-design-icons
```

If you prefer to keep using `@expo/vector-icons`, pass a custom icon renderer to `PaperProvider` as described in the [Icons guide](./icons#4-use-custom-icons).

If you have a `babel.config.js` or `.babelrc` file, make sure that it includes `babel-preset-expo`.

</TabItem>
<TabItem value="community-cli" label="Community CLI">
Expand All @@ -49,7 +57,7 @@ Minimum requirements:

Follow the [React Native Reanimated installation guide](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/).

If you're on a vanilla React Native project, you also need to install [@react-native-vector-icons/material-design-icons](https://github.com/oblador/react-native-vector-icons/tree/master/packages/material-design-icons).
You also need to install [@react-native-vector-icons/material-design-icons](https://github.com/oblador/react-native-vector-icons/tree/master/packages/material-design-icons). It is the only icon package Paper detects, the old single package `react-native-vector-icons` is no longer picked up.

Specifically, the `MaterialDesignIcons` icon pack needs to be included in the project because some components use those icons internally, such as `AppBar.BackAction` on Android.

Expand Down
31 changes: 5 additions & 26 deletions docs/6.x/docs/guides/icons.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,13 @@
title: Icons
---

import TabItem from '@docs/components/TabItem';
import Tabs from '@docs/components/Tabs';
import IconsList from '@docs/components/IconsList.tsx';

# Icons

## Configuring icons

Many of the components render icon names using [`@react-native-vector-icons/material-design-icons`](https://github.com/oblador/react-native-vector-icons/tree/master/packages/material-design-icons). In Expo projects this usually works without extra setup. In vanilla React Native projects, install the package and complete any required platform setup as described in the [getting started guide](./getting-started).
Many of the components render icon names using [`@react-native-vector-icons/material-design-icons`](https://github.com/oblador/react-native-vector-icons/tree/master/packages/material-design-icons). It is the only icon package Paper detects, in Expo projects too, so install it and complete any required platform setup as described in the [getting started guide](./getting-started). Without it, icon names render as broken (the □ placeholder character). If you use another icon package, such as `@expo/vector-icons`, pass a [custom icon renderer](#4-use-custom-icons) instead. If you're upgrading from v5, the [migration guide](./migration#icons-only-react-native-vector-iconsmaterial-design-icons-is-auto-detected) explains this change in detail.

:::note
If you opted out of vector icons support using [babel-plugin-optional-require](https://github.com/satya164/babel-plugin-optional-require), you won't be able to use icon names for the icon prop. Some components may not look correct without vector icons and might need extra configuration.
Expand All @@ -30,29 +28,10 @@ Example:
<Button icon="camera">Press me</Button>
```

:::note
Choose the correct tab below based on your `react-native-vector-icons` version:

- Use **latest** tab if you're using the latest version of `@react-native-vector-icons/material-design-icons`
- Use **10.x** tab if you're still using the old single package `react-native-vector-icons`, version `10.x`

If you are using `@expo/vector-icons`, please check their [searchable list of icons](https://icons.expo.fyi/).
:::

<Tabs>
<TabItem value="material-design-icons" label="latest">
<details>
<summary>See the list of supported icons</summary>
<IconsList latest />
</details>
</TabItem>
<TabItem value="material-community-icons" label="10.x">
<details>
<summary>See the list of supported icons</summary>
<IconsList />
</details>
</TabItem>
</Tabs>
<details>
<summary>See the list of supported icons</summary>
<IconsList latest />
</details>

### 2. An image source

Expand Down
Loading