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 something goes wrong.

git checkout -b migration

Make sure you’ve accounted for the following:

• Ensure each Skeleton package (core and framework) are updated to the latest v3.x release.
• Update all critical dependencies to their latest version (optional but recommended)
• Your app has been tested and is in a functional state.

Migrate to v4 RC

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

Remove Source Import

The @source import in your global stylesheet (ex: app.css) is no longer required. Please remove this, but keep all other Skeleton-related imports.

@source '../node_modules/@skeletonlabs/skeleton-svelte/dist';

Migrating Components

Per the Skeleton v4 RC, we do not yet have an automated migration CLI. For now, you will need to manually migrate each component in your project to the new format. Please consult the code snippets found on each respective component’s documentation page for reference. Below an example of that process using 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 to 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!

Component Guidelines

If you would like a deeper understanding of how components operate in Skeleton v4, we recommend browsing the Contribution Guidelines. Use this to update your custom components to the latest standards for Skeleton.