Migrate from v3

Skeleton v4 introduces a top-to-bottom overhaul of the component APIs. The goal has been to stabilized the internal and external APIs of our component system and ensure we can continue to introduce new components and new component frameworks over time. It also aims to make Skeleton’s components as simple and intuitive to use as possible for new users.

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

Automated Migration

To begin, we will run a quick automated migration.

npx skeleton migrate skeleton-4

This will handle the package and stylesheet updates in the next couple steps. If you opt for the CLI, feel free to skip down to the Manual Migration steps below. Note the manual steps 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 install @skeletonlabs/skeleton@latest @skeletonlabs/skeleton-react@latest

Svelte

npm install @skeletonlabs/skeleton@latest @skeletonlabs/skeleton-svelte@latest

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 allow them to be opt-in. However, due to popular demand, these have now been combined back into the core package. If this optional import is present, please remove it:

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

Manual Migration

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

Migrating Components

Below is an example of that process specifically tailored for the Avatar component.

Was (v3)

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

Now (v4 RC)

<Avatar>
  <Avatar.Image src="https://i.pravatar.cc/150?img=48" alt="Jane Doe" />
  <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, alt, and or name props.
4. Implement the new <Avatar.Image> child and pass the src path and alt text.
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. We recommend commenting out each Skeleton component instance, then enabling them one-by-one as you migrate to the new format.

Rename Components

As part of this update, select components have been renamed. We now aim to follow the Zag.js naming conventions.

Support and Feedback

If you have any questions or issues about the migration process, please contact us on Discord (the #contributors channel) or via GitHub. We are here to help!