Migrate from v2 - Skeleton

Skeleton
  1. get started
  2. ›
  3. migrate v3

Migrate from v2

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

WARNING: Skeleton v3 is currently in a pre-release status. It is not yet intended for production use. This may include bugs, incomplete documentation, and breaking changes leading up to the full release. Depending on the scale and scope of of your project, we may even encourage of your application to take full advantage of all changes.

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.

Terminal window
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.

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.

Terminal window
npx @skeletonlabs/skeleton-cli 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 the these automated changes.

Early Adopters: In extremely rare instances the CLI may modify values outside the scope of Skeleton. If this occurs, please report this as a bug in the #skeleton-cli-beta channel on Discord!

Additional Migration

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

Migrate Themes

For Preset Themes

  1. Browse the available preset themes. Tap each preview to copy the name to your clipboard.
  2. You may register or or more theme in your global stylesheet in /src/app.css:
@import '@skeletonlabs/skeleton/themes/{theme-name}';
  1. Update the active theme by setting the data-theme attribute on the <body> tag in /src/app.html

For Custom Themes

  1. Use the Import feature 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.
  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) <AppShell> component in favor of user-defined custom layouts. We’ve provided a 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 like runes, snippets, event handlers, etc.
  • Changes to support Zag.js, which serves as a foundation 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 and cross-framework standardization.

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

<!-- Skeleton v2 -->


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


<RangeSlider name="amount" bind: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]} />

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

Namev2v3Notes
<AppRail>LinkLinkRenamed <Navigation> - greatly expanded features
<FileButton>LinkLinkRenamed <FileUpload> - merges <FileDropzone> features
<FileDropzone>LinkLinkRenamed <FileUpload> - merges <FileButton> features
<InputChip>LinkLinkRenamed <TagsInput>
<Paginator>LinkLinkRenamed <Pagination>
<ProgressBar>LinkLinkRenamed <Progress>
<ProgressRadial>LinkLinkRenamed <ProgressRing>
<RadioGroup>LinkLinkRenamed <Segment> (aka Segmented Control)
<RangeSlider>LinkLinkRenamed <Slider>
<SlideToggle>LinkLinkRenamed <Switch>
<TabGroup>LinkLinkRenamed <Tabs>
<TreeView>Link—Coming soon - Track progress

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 post for the full roster of changes.

  • The tailwing.config has been removed in favor of CSS-base configuration in your global stylesheet.
  • Make sure you’re using the newest strategies for supporting Dark Mode.
  • You are still required to implement the Tailwind Forms Plugin to use Skeleton form elements.
  • The Skeleton data-theme attribute has moved from <body> to <html>
  • Themes colos are not stored in the oklch format, but optionally support any format.

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

Namev2AlternativeNotes
ClipboardLinkLinkProvided via Cookbook guide
SVG FilterLinkLinkProvided via Cookbook guide
Focus TrapLinkLinkProvided via Integration guide

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

Components

Namev2AlternativeNotes
<AppShell>LinkLinkReplaced with custom layouts
<Autocomplete>LinkLinkProvided via Integration guide
<ConicGradient>LinkLinkNow built into Tailwind
<Lightswitch>LinkLinkRemoved in favor of custom components
<ListBox>Link—Removed
<Stepper>LinkLinkProvided via Cookbook guide
<Table>LinkLinkRemoved in favor of a Tailwind component

Utilities

Namev2AlternativeNotes
Code BlocksLinkLinkProvided via Integration guide
DrawersLinkLinkProvided via Integration guide
ModalsLinkLinkProvided via Integration guide
PopoversLinkLinkProvided via Integration guide
ToastsLinkLinkProvided via Integration guide
Table of ContentsLinkLinkProvided via Cookbook guide
Persisted StoreLink—Incompatable with Svelte 5

Popovers and Modals

Members of the both the Skeleton team and the Svelte community are actively building Floating UI Svelte. 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, 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) in the future. We ask that you please be patience 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.

Terminal window
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 or Discord support channels.