# Migrate from v3

Learn how to migrate from Skeleton v3 to the latest version.

<Alert type="warning">The Skeleton v4 Release Candidate is an early access preview and not yet intended for production use.</Alert>

Skeleton v4 introduces a top-to-bottom overhaul of the component APIs. The goal has been to stabilized the internal and external APIs of our component system and ensure we can continue to introduce new components and new component frameworks over time. It also aims to make Skeleton's components as simple and intuitive to use as possible for new users.

## Prerequisites

We recommend you handle all migration changes on a dedicated feature branch. This ensures you can easily drop and revert if anything goes wrong.

```console
git checkout -b migration
```

Make sure you've accounted for the following:

* Ensure both Skeleton packages (core and framework) are updated to the latest v3.x release.
* Update all critical dependencies in your app to their latest version (optional but recommended)
* Make sure your app has been tested and is in a functional state.

***

## Automated Migration

To begin, we will run a quick automated migration.

```console
npx skeleton migrate skeleton-4
```

This will handle the package and stylesheet updates in the next couple steps. If you opt for the CLI, feel free to skip down to the [Manual Migration](/docs/get-started/migrate-from-v3#manual-migration) steps below. Note the manual steps are required for all migrations.

### Update NPM Packages

For the Release Candidate, please update each Skeleton package to the early access `@next` version. Note that we will be updating these package frequently leading up to the full release.

**React**

```console
npm install @skeletonlabs/skeleton@latest @skeletonlabs/skeleton-react@latest
```

**Svelte**

```console
npm install @skeletonlabs/skeleton@latest @skeletonlabs/skeleton-svelte@latest
```

### Update Stylesheet Imports

The following migration steps apply to your global stylesheet (ex: `app.css`).

The `@source` rules for sourcing component styles have been replaced with simpler and more intuitive `@import` rules.

```diff
- @source '../node_modules/@skeletonlabs/skeleton-{framework}/dist';
+ @import '@skeletonlabs/skeleton-{framework}';
```

In Skeleton v3 the [Preset styles](/docs/design/presets) were split to an optional stylesheet to allow them to be opt-in. However, due to popular demand, these have now been combined back into the core package. If this optional import is present, please remove it:

```diff
- @import '@skeletonlabs/skeleton/optional/presets';
```

***

## Manual Migration

Assuming all above steps have been completed in full, you will now be required to handle the manual portion of the migration. The steps below are not optional and must be completed to finalize your migration to Skeleton v4.

### Migrating Components

Below is an example of that process specifically tailored for the Avatar component.

**Was (v3)**

```svelte
<Avatar src="https://i.pravatar.cc/150?img=48" name="Jane Doe" />
```

**Now (v4 RC)**

```svelte
<Avatar>
	<Avatar.Image src="https://i.pravatar.cc/150?img=48" alt="Jane Doe" />
	<Avatar.Fallback>SK</Avatar.Fallback>
</Avatar>
```

1. Consult the Avatar documentation for [React](/docs/components/avatar/react) or [Svelte](/docs/components/avatar/svelte).
2. Keep the import as is; no changes are required for this component.
3. The root component `<Avatar>` remains; remove the `src`, `alt`, and or `name` props.
4. Implement the new `<Avatar.Image>` child and pass the `src` path and `alt` text.
5. Initials are no longer generated via the `name`; instead specify a fallback with `<Avatar.Fallback>`

> TIP: To locate components, search your project by the v3 component name, such `<Avat...` for Avatar. We recommend commenting out each Skeleton component instance, then enabling them one-by-one as you migrate to the new format.

### Rename Components

As part of this update, select components have been renamed. We now aim to follow the [Zag.js](https://zagjs.com/) naming conventions.

\| Was (v3)            | Now (v4)                     | v4 Docs                                                                                                 |
\| ------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------- |
\| `<Modal>`           | `<Dialog>`                   | [React](/docs/components/dialog/react) / [Svelte](/docs/components/dialog/svelte)                       |
\| `<Navigation.Bar>`  | `<Navigation layout="bar">`  | [React](/docs/components/navigation/react) / [Svelte](/docs/components/navigation/svelte)               |
\| `<Navigation.Rail>` | `<Navigation layout="rail">` | [React](/docs/components/navigation/react) / [Svelte](/docs/components/navigation/svelte)               |
\| `<ProgressRing>`    | `<Progress>`                 | [React](/docs/components/progress-circular/react) / [Svelte](/docs/components/progress-circular/svelte) |
\| `<Ratings>`         | `<RatingGroup>`              | [React](/docs/components/rating-group/react) / [Svelte](/docs/components/rating-group/svelte)           |
\| `<Segment>`         | `<SegmentedControl>`         | [React](/docs/components/segmented-control/react) / [Svelte](/docs/components/segmented-control/svelte) |
\| `<Toaster>`         | `<Toast.Group>`              | [React](/docs/components/toast/react) / [Svelte](/docs/components/toast/svelte)                         |

***

## Support and Feedback

If you have any questions or issues about the migration process, please contact us on Discord (the `#contributors` channel) or via [GitHub](https://github.com/skeletonlabs/skeleton/discussions). We are here to help!