(Work in Progress) Skeleton v3 Beta Migration Guide

[endigo9740]

Warning

This guide is a work in progress. Look for the full announcement on Tuesday, November 5th.

---

This guide covers migrating from Skeleton v2 to the Skeleton v3 Beta. Please be aware that Skeleton v3 is a massive update and overhaul with a significant number of changes when compared to prior versions. We want to set clear expectations upfront that this will be an involved migration process. We recommend you read through the full guide before you begin the migration process.

We are providing this migration guide as early as possible to enable the community to test and provide feedback for both Skeleton v3 and the migration process itself. We expect this guide will grow and evolve as we gather feedback and get closer to the final release. If you experience issues, please report them in the comments section below or via the #skeleton-next channel on Discord.

• Announcement: (Work in Progress) Skeleton v3 Beta 🎉 #2919
• v3 Documentation: https://next.skeleton.dev/
• v3 Theme Generator: https://themes.skeleton.dev/

Beta Disclaimer

Caution

• 🔴 The v3 Beta is NOT YET INTENDED FOR PRODUCTION USE.
• 🔴 The v3 Beta will include bugs, have missing features, and incomplete documentation.
• 🔴 Depending on the scale and scope of your application, we may recommend a rewrite over a migration.

Framework Support

Skeleton has historically only supported Svelte/Kit, so the following guide is geared towards Svelte/Kit-based web applications. For all other frameworks, please refer to the growing Skeleton v3 Onboarding section.

Tips for Migrating

• Create a dedicated v3 branch in your project where you handle the migration process. This allows you to update slowly over time, easily roll back changes, or even drop the branch if you're not satisfied with the update.
• Use your editor's find/replace feature to update feature in bulk (rename classes, etc)
• Open the relevant v2 docs and v3 docs for the feature you're migrating for quick reference
• Remember the v3 documentation is the best source of truth for all changes.
• Pace yourself. Don't feel like you have to migrate everything in a single session!

Prerequisites

Before you begin, make sure you have migrated your Skeleton v2.x project to Svelte 5:

• Svelte 5 Migration Guide for Skeleton v2 #2887

Your project should meet the following criteria before proceeding:

• Your app is running the latest release of Skeleton v2.x
• Your app is running Svelte 5.x
• Your app is running SvelteKit 2.x
• Your app is running the latest dependencies (optional; but recommended)
• Your app has been tested and is fully functional

Migration Guide

Caution

Skeleton v3 features a major rewrite of nearly every feature in the library - adapting to the new Svelte 5 component APIs, new features, and of course new internal conventions. As such, you may find the migration process more open ended than prior migration guides. However, this should cover the most import steps required. If you get stuck, please reach out in the comments section below, or in the #skeleton-next channel on Discord.

Video Tutorial

Before you begin, consider watching our Video Tutorial. This showcases the complete migration process from start to finish for a real world application. Timestamps have been provided if you wish to skip to a particular topic.

1. Remove the v2.x Packages

npm uninstall @skeletonlabs/skeleton @skeletonlabs/tw-plugin

2. Follow the Onboarding Guide

Follow from Step 2 and forward on the onboarding guide. This will accomplish the following:

• Install the new skeleton (core) and skeleton-svelte (component) packages.
• Install the @types/node package to prevent Tailwind config type errors.
• Update your tailwind.config to use the latest settings.
• Temporarily implement a preset theme to ensure things are working.

3. Update Your Theme

For Preset Themes

Browse the 20+ available themes, then register one or more themes.

NOTE: some legacy Skeleton v2 themes have been renamed. Make sure you're using the new name.

For Custom Themes

If you wish to migrate a custom theme. Follow the steps below:

1. Use the Import feature for the new Theme Generator.
2. Drag and Drop your v2 theme into the file upload field.
3. Update and modify all theme settings as desired.
4. Make sure to set a valid theme name in the right-hand panel.
5. When ready, tap the Code tab to preview your generated theme code.
6. Copy the theme code, then following our custom theme instructions.

TIP: Don't forget to activate your theme using the data-theme attribute on your <body> tag!

4. Replace AppShell with Custom Layouts

Skeleton has dropped the (very troubled) <AppShell> component in favor of user-defined layouts. We've provided a Layouts guide for building common page structures using only HTML and Tailwind - no Skeleton specific features needed!

5. Update Utility Classes

Skeleton utility classes have been rewritten from the ground up and feature numerous changes. This includes:

Name	v2	v3	Notes
Design Tokens	Link	Link	Now considered utility classes; drop -token.
Color Pairings	Link	Link	Now considered utility classes; drop -token.
Variants	Link	Link	Renamed Presets; greatly expanded options.
Gradient Variants	Link	Link	Replaced with Tailwind utility classes.

Here's a quick comparison of utility class changes from v2 to v3:

v2	v3
rouned-token	rounded
bg-surface-50-900-token	bg-surface-50-950
variant-filled-primary	preset-filled-primary-500
variant-gradient-primary-secondary	from-primary-500 to-secondary-500

6. Update Tailwind Elements

The vast majority of Element classes (ex: buttons, cards, etc) retain the same names from Skeleton v2. We have, however, moved a number of these features to Cookbook guides, built using simple Skeleton and Tailwind primitives.

Name	v2	v3	Notes
Alerts	Link	Link	Provided as a Cookbook guide.
Breadcrumbs	Link	Link	Provided as a Cookbook guide.
Lists	Link	Link	Replaced with Tailwind utility classes.
Logo Clouds	Link	Link	Provided as a Cookbook guide.

7. Update Tailwind Blocks

All Tailwind Blocks will now reside in the new Cookbook section:

Name	v2	v3	Notes
Chat	Link	(coming soon)	Provided as a Cookbook guide.
Gradient Headings	Link	(coming soon)	Provided as a Cookbook guide.
Image Layouts	Link	Link	Provided as a Cookbook guide.
Scroll Containers	Link	(coming soon)	Provided as a Cookbook guide.

8. Update Svelte Components

Components have undergone the biggest update in Skeleton v3. Given the sheer number of breaking changes, we recommend you compare each component to it's equivalent v3 documentation. Here's some of the key changes you may encounter:

• Changes to adopt the new Svelte 5 APIs like runes, snippets, event handlers, etc.
• Changes to support Zag.js, which serves as a foundation for standardizing cross-framework.
• Changes to the import path: @skeletonlabs/skeleton-svelte.
• Changes to the component name and/or structure (including sub-components)
• Changes due to new component features and properties.
• Changes to adopt the new style prop conventions and standardizing how utility classes are implemented.

Here's a quick comparison of these changes for a single component from v2 to v3:

<!-- Skeleton v2 -->

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

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

<!-- Skeleton v3 -->

<script lang="ts">
    import { Slider } from '@skeletonlabs/skeleton-svelte';
    let value = $state([15]);
</script>

<Slider name="amount" bind:value markers={[25, 50, 75]} />

You can review the most notable changes to components in the list below:

Name	v2	v3	Notes
<AppRail>	Link	Link	Renamed <Navigation>; greatly expanded features.
<FileButton>	Link	Link	Renamed <FileUpload>; merges <FileDropzone> features.
<FileDropzone>	Link	Link	Renamed <FileUpload>; merges <FileButton> features.
<InputChip>	Link	Link	Renamed <TagsInput>.
<Paginator>	Link	Link	Renamed <Pagination>.
<ProgressBar>	Link	Link	Renamed <Progress>.
<ProgressRadial>	Link	Link	Renamed <ProgressRing>.
<RadioGroup>	Link	Link	Renamed <Segment> (aka Segment Control).
<RangeSlider>	Link	Link	Renamed <Slider>.
<SlideToggle>	Link	Link	Renamed <Switch>.
<TreeView>	Link	(coming soon)	Awaiting an upcoming Zag-based component.

9. Replace Non-Supported Features

Earlier this year we began to reflect on what features should remain as part of the core experience in Skeleton. As such, we've identified a number of features that fall outside that scope. Don't fret though, we've gone out of our way to provide alternatives to supplement and replace these within your project. Not only do we expect these alternatives to work better long term for you, but you can expect Skeleton's total number of components to continue to grow rapidly post-release thanks to Zag.

Svelte Actions

Name	v2	v3	Notes
Clipboard	Link	(coming soon)	Provided as a Cookbook guide.
SVG Filter	Link	(coming soon)	Provided as a Cookbook guide.
Focus Trap	Link	Link	Provided via integration guide.

TIP: We also recommend Runed for a similar approach to small composable features for Svelte 5.

Components

Name	v2	v3	Notes
<AppShell>	Link	Link	Dropped in favor of custom layouts.
<Autocomplete>	Link	Link	Provided via integration guide.
<ConicGradient>	Link	(coming soon)	Provided via integration guide.
<Lightswitch>	Link	Link	Dropped in favor of framework-specific guidance.
<ListBox>	Link	--	Removed.
<Stepper>	Link	--	Removed.
<Table>	Link	Link	Dropped in favor of Tailwind Element styles.

Utilities

Name	v2	v3	Notes
Code Blocks	Link	Link	Provided via integration guide.
Drawers	Link	Link	Provided via integration guide.
Modals	Link	Link	Provided via integration guide.
Popovers	Link	Link	Provided via integration guide.
Toasts	Link	Link	Provided via integration guide.
Table of Contents	Link	(coming soon)	Provided as a Cookbook guide.
Persisted Store	Link	--	Removed.

Support

Please report all issues via Discord or the comments section below.