Migrate from v3

Skeleton v4 introduces a top-to-bottom overhaul of the component APIs. The goal has been to stabalized the internal and external APIs of our component system and ensure we can continue to introduce new components and new component frameworks over time.

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.

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)
• Your app has been tested and is in a functional state.

Automated Migration

To begin, we will run a quick automated migration.

npx skeleton@next migrate skeleton-4

This will handle the following package and stylesheet updates. Once complete, skip to the Manual Migration steps below, which 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

npm remove @skeletonlabs/skeleton @skeletonlabs/skeleton-react
npm i -D @skeletonlabs/skeleton@next @skeletonlabs/skeleton-react@next

Svelte

npm remove @skeletonlabs/skeleton @skeletonlabs/skeleton-svelte
npm i -D @skeletonlabs/skeleton@next @skeletonlabs/skeleton-svelte@next

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.

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

In Skeleton v3 the Preset styles were split to an optional stylesheet to keep them opt-in. However, due to popular demand, these have now been rolled back into the core package. If this import is present, please remove it:

@import '@skeletonlabs/skeleton/optional/presets';

Manual Migration

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

Migrating Components

To begin migrating components, please consult the code snippets found on each respective component’s documentation page for reference. Below an example of that process specifically for the Avatar component.

Was (v3)

<Avatar src="https://i.pravatar.cc/150?img=48" name="skeleton" />

Now (v4 RC)

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

1. Consult the Avatar documentation for React or Svelte.
2. Keep the import as is; no changes are required for this component.
3. The root component <Avatar> remains; remove the src or name props.
4. Implement the new <Avatar.Image> child and pass the src path.
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.

Rename Components

As part of this update, select components have been renamed. Most now follow Zag.js naming conventions.

Support and Feedback

For the duration of this early access preview, we ask that you please test the new component structure, styling, and markup features in your real-world projects. We encourage you to share your experience and report issues on either Discord (the #contributors channel) or via GitHub. Your feedback will be invaluable to guide any last minutes changes and determine when the final release is ready. We appreciate your input!