# Migrate from v2
Learn how to migrate from Skeleton v2 to the latest version.

## Introduction

Version 3 represents a major overhaul to Skeleton. This includes a ground up rewrite of quite literally every feature in the library. We have provided a migration CLI to help automate this process. However, some portions of this migration will still required manual intervention. This is not a trivial migration from prior versions, so please use caution when updating and ensure you follow this guide very carefully.

## Prerequisites

While Skeleton v3 introduces support for multiple frameworks, we’ve historically only supported SvelteKit. As such, this guide is only intended for users migrating from Skeleton v2 and SvelteKit. If you you are coming from another meta-framework, this will be outside the scope of this guide. However, this may still provide a valuable insight to the primary objectives for migration.

### Create a Migration Branch

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

```shell
git checkout -b migration
```

### Prepare Your Skeleton App

Please make sure you have accounted for the following:

- Your app is running the latest release of Skeleton v2.x
- All critical dependencies have been updated (optional but recommended)
- Your app is in a functional state before you proceed

---

## Migrate Core Technologies

Skeleton is built on top of the following technologies. These must be migrated individually before proceeding with the Skeleton-specific migration. Note that Svelte and Tailwind provide dedicated CLIs to automate this process.

### Svelte v5

Migrate to the latest release of Svelte v5.

<figure class="linker bg-noise">
	<a class="btn preset-filled" href="https://svelte.dev/docs/svelte/v5-migration-guide" target="_blank">
		Svelte v5 Migration &rarr;
	</a>
</figure>

### SvelteKit v2

Migrate to the latest release of SvelteKit v2.

<figure class="linker bg-noise">
	<a class="btn preset-filled" href="https://svelte.dev/docs/kit/migrating-to-sveltekit-2" target="_blank">
		SvelteKit v2 Migration &rarr;
	</a>
</figure>

### Tailwind v4

Before migration to tailwind v4 using their upgrade guide some manual steps are required:

1. Remove the `skeleton` plugin from your `tailwind.config` file.
2. Rename your `app.postcss` or `app.pcss` to `app.css`.
3. Remove the `purgecss` (`vite-plugin-tailwind-purgecss`) vite plugin from your `vite.config` (if installed).

Migrate to the latest release of Tailwind v4.

> TIP: Having trouble running Tailwind's automated migration script due to `@apply`? Remove the classes temporarily, then follow [these steps](/docs/get-started/migrate-from-v2#replacing-apply) to adapt to native CSS custom properties and Tailwind's new utilities.

<figure class="linker bg-noise">
	<a class="btn preset-filled" href="https://tailwindcss.com/docs/upgrade-guide" target="_blank">
		Tailwind v4 Migration &rarr;
	</a>
</figure>

---

## Migrate to the Tailwind Vite Plugin

Use the following steps to migrate to from PostCSS to the Vite plugin:

1. Delete `postcss.config.mjs`
2. Run `npm uninstall postcss @tailwindcss/postcss`
3. Run `npm install @tailwindcss/vite`
4. Open your `vite.config` in the root of your project
5. Import the following at the top of the file: `import tailwindcss from '@tailwindcss/vite'`
6. Finally, add the Vite plugin ABOVE your specific framework plugin:

```ts
plugins: [
	tailwindcss(),
	sveltekit(), // or svelte()
];
```

---

## Automated Migration

We’ve provided a dedicated migration script as part of the Skeleton CLI to help automate much of this process.

> TIP: Please ensure you've committed all pending changes before proceeding.

```console
npx skeleton migrate skeleton-3
```

What WILL be migrated...

- Update all required `package.json` dependencies
- Implement all required Skeleton imports in your global stylesheet `app.css`
- Modify `data-theme` in `app.html` if you’re using a Skeleton preset theme.
- Temporarily disable custom theme imports to allow for theme migration.
- Migrate all modified Skeleton utility classes (ex: `variant-*` to `preset-*`)
- Update all Skeleton imports throughout your entire project
- Renames all relevant Skeleton components
- Some Component imports will also be pruned as they are no longer supported. We’ll cover these features in detail below.

What will NOT be migrated...

- Component props will not be updated. Unfortunately there’s too many permutations.
- Most v2 Utility features will not be migrated (ex: popovers, code blocks, etc)

Make sure to consult your local Git Diff to compare what has been modified before progressing forward or committing these automated changes.

---

## Additional Migration

With automated migration complete, please follow the remaining manual migration steps.

### Migrate Themes

#### For Preset Themes

Your preset theme should be automatically migrated by the CLI, you're all set!

#### For Custom Themes

1. Use the [Import feature](https://themes.skeleton.dev/themes/import) provided by the new Theme Generator.
2. Drag and Drop your v2 theme into the file upload field.
3. Your theme will be automatically converted to the newest format.
4. Update and modify any theme settings in the live preview.
5. Make sure to set a valid theme name in the right-hand panel.
6. Tap the “Code” tab to preview your generated theme code.
7. Copy the theme code, then following our [custom theme instructions](/docs/design/themes#custom-themes).
8. Similar to preset themes, you will need to both register and set an active theme.

### Replace AppShell with Custom Layouts

Skeleton has sunset the ([troublesome](https://github.com/skeletonlabs/skeleton/issues/2383)) `<AppShell>` component in favor of user-defined custom layouts. We've provided a [Layouts](/docs/guides/layouts) guide for replicating common page structures using only semantic HTML and Tailwind - no Skeleton specific features needed!

### Migrating Components

Components have undergone the biggest update in Skeleton v3. Given the sheer number of changes, we recommend you compare each component to it's equivalent v3 documentation. We’ve highlighted a few of the key changes below:

- Changes to adopt the new [Svelte 5 APIs](https://svelte.dev/docs/svelte/v5-migration-guide) like runes, snippets, event handlers, etc.
- Changes to support [Zag.js](https://zagjs.com/), which serves as a foundation of our cross-framework components.
- Changes to the import path: `@skeletonlabs/skeleton-svelte`.
- Changes to the component name and/or structure (including sub-components)
- Changes based on newly introduces features and properties.
- Changes to adopt the new [style prop conventions](/docs/get-started/fundamentals#style-props) and cross-framework standardization.

Here's an example of changes for a single component from v2 to the new equivalent:

```svelte
<!-- Skeleton v2 -->

<script lang="ts">
	import { RangeSlider } from '@skeletonlabs/skeleton';

	let value = 15;
</script>

<RangeSlider name="amount" bind:value ticked />
```

```svelte
<!-- Skeleton v3 -->

<script lang="ts">
	import { Slider } from '@skeletonlabs/skeleton-svelte';

	let value = $state([15]);
</script>

<Slider name="amount" {value} onValueChange={(e) => (value = e.value)} markers={[25, 50, 75]} />
```

We’ve denoted the most notable changes to each component in the table below:

| Name               | v2                                                          | v3                                            | Notes                                                                                                        |
| ------------------ | ----------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `<AppRail>`        | [Link](https://v2.skeleton.dev/components/app-rail)         | [Link](/docs/components/navigation/svelte)    | Renamed `<Navigation>` - greatly expanded features                                                           |
| `<FileButton>`     | [Link](https://v2.skeleton.dev/components/file-buttons)     | [Link](/docs/components/file-upload/svelte)   | Renamed `<FileUpload>` - merges `<FileDropzone>` features                                                    |
| `<FileDropzone>`   | [Link](https://v2.skeleton.dev/components/file-buttons)     | [Link](/docs/components/file-upload/svelte)   | Renamed `<FileUpload>` - merges `<FileButton>` features                                                      |
| `<InputChip>`      | [Link](https://v2.skeleton.dev/components/input-chips)      | [Link](/docs/components/tags-input/svelte)    | Renamed `<TagsInput>`                                                                                        |
| `<Paginator>`      | [Link](https://v2.skeleton.dev/components/paginators)       | [Link](/docs/components/pagination/svelte)    | Renamed `<Pagination>`                                                                                       |
| `<ProgressBar>`    | [Link](https://v2.skeleton.dev/components/progress-bars)    | [Link](/docs/components/progress/svelte)      | Renamed `<Progress>`                                                                                         |
| `<ProgressRadial>` | [Link](https://v2.skeleton.dev/components/progress-radials) | [Link](/docs/components/progress-ring/svelte) | Renamed `<ProgressRing>`                                                                                     |
| `<RadioGroup>`     | [Link](https://v2.skeleton.dev/components/radio-groups)     | [Link](/docs/components/segment/svelte)       | Renamed `<Segment>` (aka Segmented Control)                                                                  |
| `<RangeSlider>`    | [Link](https://v2.skeleton.dev/components/range-sliders)    | [Link](/docs/components/slider/svelte)        | Renamed `<Slider>`                                                                                           |
| `<SlideToggle>`    | [Link](https://v2.skeleton.dev/components/slide-toggles)    | [Link](/docs/components/switch/svelte)        | Renamed `<Switch>`                                                                                           |
| `<TabGroup>`       | [Link](https://v2.skeleton.dev/components/tabs)             | [Link](/docs/components/tabs/svelte)          | Renamed `<Tabs>`                                                                                             |
| `<TreeView>`       | [Link](https://v2.skeleton.dev/components/tree-views)       | --                                            | Coming soon - [Track progress](https://github.com/skeletonlabs/skeleton/issues/2358#issuecomment-2313215789) |

### Tailwind v4 Changes

Taliwind v4 represents a major update for Tailwind. We've detailed the most notable features as they may relate to your Skeleton project. Please consult the [Tailwind v4 announcement](https://tailwindcss.com/blog/tailwindcss-v4) post for the full roster of changes.

- The `tailwing.config` has been removed in favor of [CSS-base configuration](https://tailwindcss.com/blog/tailwindcss-v4#css-first-configuration) in your global stylesheet.
- Make sure you’re using the newest strategies for supporting [Dark Mode](/docs/guides/mode).
- You are still required to implement the [Tailwind Forms Plugin](/docs/tailwind/forms#prerequisites) to use Skeleton form elements.
- The Skeleton `data-theme` attribute has moved from `<body>` to `<html>`
- Themes colors are now stored in the [oklch format](https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl), but optionally support any format.

### Replacing @apply

We strongly encourage you take this opportunity to move away from any usage of `@apply`. Tailwind has long since advocated against heavy use of this, and Tailwind v4 introduces new directives and functions that make this much easier to avoid. Here's a trivial example:

```css
/* Before */

.foo {
	@apply bg-surface-50-950 text-surface-950 dark:text-surface-50 p-4;
}
```

```css
/* After */

.foo {
	background-color: var(--color-surface-50-950);
	color: var(--color-surface-950);
	padding: --spacing(4);
	@variant dark {
		color: var(--color-surface-50);
	}
}
```

- Usage of `@apply` may be found in your global stylesheet or component `<style>` blocks.
- Refer to the Skeleton [Core API](/docs/get-started/core-api) documentation for a full list of Skeleton's CSS custom properties.
- Refer to the Tailwind's [functions and directives](https://tailwindcss.com/docs/functions-and-directives) for information on how to utilize these new features.

### Replace Unsupported Features

Skeleton v3 represents a point of reflection on what features should remain as part of the core experience. As such, we've identified a number of features that fall outside of this scope. Don't fret though, we've gone out of our way to detail each feature and provide the best alternative available.

#### Svelte Actions

| Name       | v2                                                 | Alternative                               | Notes                          |
| ---------- | -------------------------------------------------- | ----------------------------------------- | ------------------------------ |
| Clipboard  | [Link](https://v2.skeleton.dev/actions/clipboard)  | [Link](/docs/guides/cookbook/clipboard)   | Provided via Cookbook guide    |
| SVG Filter | [Link](https://v2.skeleton.dev/actions/filters)    | [Link](/docs/guides/cookbook/svg-filters) | Provided via Cookbook guide    |
| Focus Trap | [Link](https://v2.skeleton.dev/actions/focus-trap) | [Link](/docs/integrations/popover/svelte) | Provided via Integration guide |

> TIP: We also recommend [Runed](https://runed.dev/docs) for a similar approach to small composable features for Svelte 5.

#### Components

| Name              | v2                                                              | Alternative                                                                    | Notes                                    |
| ----------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------- |
| `<AppShell>`      | [Link](https://v2.skeleton.dev/components/app-shell)            | [Link](/docs/guides/layouts)                                                   | Replaced with custom layouts             |
| `<Autocomplete>`  | [Link](https://v2.skeleton.dev/components/autocomplete)         | [Link](/docs/integrations/popover/svelte#combobox)                             | Provided via Integration guide           |
| `<ConicGradient>` | [Link](https://v2.skeleton.dev/components/conic-gradients)      | [Link](https://tailwindcss.com/docs/background-image#adding-a-radial-gradient) | Now built into Tailwind                  |
| `<Lightswitch>`   | [Link](https://v2.skeleton.dev/docs/dark-mode#custom-component) | [Link](/docs/guides/mode#lightswitch)                                          | Removed in favor of custom components    |
| `<ListBox>`       | [Link](https://v2.skeleton.dev/components/listboxes)            | --                                                                             | Removed                                  |
| `<Stepper>`       | [Link](https://v2.skeleton.dev/components/steppers)             | [Link](/docs/guides/cookbook/stepper)                                          | Provided via Cookbook guide              |
| `<Table>`         | [Link](https://v2.skeleton.dev/components/tables)               | [Link](/docs/tailwind/tables)                                                  | Removed in favor of a Tailwind component |

#### Utilities

| Name              | v2                                                             | Alternative                                       | Notes                          |
| ----------------- | -------------------------------------------------------------- | ------------------------------------------------- | ------------------------------ |
| Code Blocks       | [Link](https://v2.skeleton.dev/utilities/codeblocks)           | [Link](/docs/integrations/code-block/svelte)      | Provided via Integration guide |
| Drawers           | [Link](https://v2.skeleton.dev/utilities/drawers)              | [Link](/docs/integrations/popover/svelte#modal)   | Provided via Integration guide |
| Modals            | [Link](https://v2.skeleton.dev/utilities/modals)               | [Link](/docs/integrations/popover/svelte#modal)   | Provided via Integration guide |
| Popovers          | [Link](https://v2.skeleton.dev/utilities/popovers)             | [Link](/docs/integrations/popover/svelte#popover) | Provided via Integration guide |
| Toasts            | [Link](https://v2.skeleton.dev/utilities/toasts)               | [Link](/docs/integrations/toasts/svelte)          | Provided via Integration guide |
| Table of Contents | [Link](https://v2.skeleton.dev/utilities/table-of-contents)    | [Link](/docs/guides/cookbook/table-of-contents)   | Provided via Cookbook guide    |
| Persisted Store   | [Link](https://v2.skeleton.dev/utilities/local-storage-stores) | --                                                | Incompatible with Svelte 5     |

#### Popovers and Modals

Members of the both the Skeleton team and the Svelte community are actively building [Floating UI Svelte](https://floating-ui-svelte.vercel.app/). The long term goal is to use this as a best-in-class solution for: popovers, tooltips, modals, drawers, and more. Until then, we are providing a [select set of components](/docs/integrations/popover/svelte), powered by Zag.js, to help bridge the gap. These components will be supported for the full duration of Skeleton v3.x. However, they will be replaced with a dedicated guide ([similar to React](/docs/integrations/popover/react)) in the future. We ask that you please be patient during this transitory phase.

### Migration Complete

If you’ve completed all steps above in full, your application should once again be in a function state. Run your application's local dev server to confirm, and remember to merge all changes into your primary branch.

```shell
npm run dev
```

---

## Troubleshooting

If you’re receiving errors, they may indicate components or features that require additional manual migration on your part. Use each error to identify the location of the feature and make any required changes. Consult each component’s documentation for the most current usage examples and API reference. In many cases this may just involve adding/removing/renaming a prop.

## Reporting Issues

If you get stuck or need to report an issue with either Skeleton v3 or this migration guide, please reach out via either the Skeleton [GitHub](https://github.com/skeletonlabs/skeleton/) or [Discord](https://discord.gg/EXqV7W8MtY) support channels.