RFC: Component API Changes

[endigo9740]

Hey everyone, Chris here from Skeleton. Today we're launching a new community-focused RFC (request for comment) regarding some proposed component API changes. Please read each proposal below very carefully and raise questions or leave you feedback in the comments section below this post.

The Goal

We know many of you are still acclimating to the changes introduce as part of Skeleton v3.0 release. Many of which were spurred by support for Svelte 5 APIs (such as runes and snippets), the introduction of React, and of course implementing Zag.js primitives as the foundation for each Skeleton component.

We also know migration is painful, but as we continue to move forward we've identified a handful of opportunity to improve the interface for Skeleton's first-party components. Including a new and novel strategy for implementing styles via new options provided by Tailwind v4. We'll cover each of these in detail below, explaining the change, and covering the benefits to you as the end user.

We ask that you come in with an open mind as we believe these changes to be critical for the continued health of the project. However, we're excited about what these changes may entail. As they help address pain points that have been present since the inception of Skeleton.

Proposal A: Component Composition

One of the biggest challenges facing Skeleton is need to feed more granular data to explicit portions of each component. Be that functional properties (state), style properties (classes), or common attributes (such as required, data-*, style, etc). To address this we're proposing that we break components into smaller, more modular, and much more composable parts.

This takes inspiration from other popular component libraries, such as Bits UI, Shadcn, and more. In fact, after reviewing many of the most popular component libraries on the market, this appears to be the de-facto solution.

Here's a quick example using the Accordion component. You can compare this to the production implementation.

<Accordion>
  <Accordion.Item value="item-1">
    <Accordion.Heading>
      <Accordion.Trigger>Item 1</Accordion.Trigger>
      <Accordion.Content>Content for Item 1</Accordion.Content>
    </Accordion.Heading>
  </Accordion.Item>
  <Accordion.Item value="item-2">
    <Accordion.Heading>
      <Accordion.Trigger>Item 2</Accordion.Trigger>
      <Accordion.Content>Content for Item 2</Accordion.Content>
    </Accordion.Heading>
  </Accordion.Item>
  <Accordion.Item value="item-3">
    <Accordion.Heading>
      <Accordion.Trigger>Item 3</Accordion.Trigger>
      <Accordion.Content>Content for Item 3</Accordion.Content>
    </Accordion.Heading>
  </Accordion.Item>
</Accordion>

• This will enable fine grain control over the placement and access to props
• This will allow us to also support and spread arbitrary attributes at each level
• The smaller scale means we can return to using the standard class attribute
• We can also implement the Child Snippet pattern, detailed by Bits UI

Proposal B: Condensing Style Props

If you're not already familiar, we recommend reading the current component fundamentals to learn how Skeleton components provide utility classes to each component template. This requires a huge number of manually defined props to ensure classes are inserted to the proper class list per template element.

With the proposed change, any and all styles would now be provided by a singular class attribute. All classes automatically take precedence and are assigned to these more bite-sized components. Here's a quick run down by Skeleton team member @Hugos68 on how this works. Comparing it to familiar alternatives such as Tailwind Merge.

• Comparison of base variants vs Tailwind Merge

Here's an example of what this change would look like in practice. Simply put you just use class for any and all utility classes!

<Accordion class="bg-green border-2 border-red-500">...</Accordion>

<Accordion.Item class="bg-blue p-4">...</Accordion>

The benefits of this are numerous:

• A radically simpler interface for supplying custom classes - just use class
• A much simpler concept to learn and retain for new users
• Infinite ways to customize using all Tailwind, Skeleton, or custom utility classes
• No need to differentiate between base, individual property, or arbitrary classes
• Nearly zero maintenance on Skeleton's end. We just pass your overrides to the class list.
• More future-proof, automatically supporting all standard or custom utility classes going forward
• Tailwind auto-suggestions should just work for most common editors (ex: VS Code)

This new strategy is only now possible via the use of Tailwind v4, and comes courtesy of Haz from Ariakit. This was originally a concept proposed by Tailwind creator Adam Wathan, and nearly baked into Tailwind v4. It was excluded only because it's so simple to implement in user-land.

Proposal C: Bring Your Own Markup

Finally, let's talk through one more concept that would allow more control over component markup.

See the example below.

<Accordion>
    <Accordion.Item value="item-1">
        <Accordion.Heading>
            <Accordion.Trigger>
                {#snippet element({ attributes })}
                    <button {...attributes}>My Own Button</button>
                {/snippet}
            </Accordion.Trigger>
            <Accordion.Content>Content for Item 1</Accordion.Content>
        </Accordion.Heading>
    </Accordion.Item>
    <!-- ... -->
</Accordion>

• This is useful when you want to control the markup for trigger
• Skeleton provides the attributes and you simply apply them as desired with your own markup
• This is shown using Svelte 5 Snippets, but similar concepts are available for other frameworks
• Skeleton would set a convention, always providing the same "snippet" name to make this easy to learn

You are then free to essentially customize markup at any level!

What DOES NOT Change

While we're suggesting a number of exciting changes, it's worth nothing what will not change:

1. We will continue to use Zag.js, which means the primitives are the same
2. The feature set will remain identical, receiving new updates when Zag updates
3. Framework support remains the same due to the use of Zag (React and Svelte only for now)
4. The visual design will remain 1:1, with only minor cosmetic changes
5. The number of components will not grow dramatically - though this will expedite things over time.

Try it Live (Coming Soon)

We have an active pull request where we're currently implementing all proposed changes. Use this as reference to see how these changes would be implemented in practice for real world components:

• feat: experimental component API #3491

Note that over the next week or two, we will launch these changes into the production version of Skeleton. This will include a new Accordion and Avatar component for Svelte and React, which stand apart from the current production versions. Both versions will exist in parallel on the latest stable release of the v3 skeleton-svelte and skeleton-react packages. This will give you a chance to try out both versions.

Note that we do not recommend using these experimental features for production use. All proposed features are subject to change between now and release - which we expect to be the core focus for Skeleton v4.

How to Submit Feedback

After reviewing all proposals above, please take a moment to provide your questions and feedback in the comments section below. @Hugos68 and I will be monitoring this closely and respond to everyone as soon as possible. We ask that you keep things professional. Off topic or non-constructive comments may be removed. Remember we're all trying to do the same thing - push Skeleton forward and provide a top-tier component library. So let's do this together!

[itzTheMeow]

Honestly I really like this change and I don't see any immediate issues with it.

[endigo9740]

That's how the team and I feel as well, but we wanted to put this out to ensure the community agrees. A sanity check is always welcome. Especially since we just put everyone through a sizable component API change with v3. But our hope is folks agree the pros far outweigh the cost (more migration). But honestly this feels like something we could land on and keep for a long time.

[knd775]

I agree. There are a couple skeleton components we maintain internal versions of because we needed to tweak a single part and were unable to with the current API. This would eliminate our need to do that.

[endigo9740]

@knd775 can you provide a specific example. I might can make a suggestion to help in the interim.

[oatmealproblem]

Overall I like this.

Being able to just pass all classes into class is great. It feels much better, and makes Skeleton easier to learn / less intimidating. And having just worked on a Skeleton-3-style component, that sounds much nicer for making/maintaining components too!

Being able to pass attributes into any part of a component is also nice. I was thinking of requesting a method of passing data- attributes for Skeleton v3, and that's just handled automatically here. (Aside, I noticed Skeleton includes data-testids on some elements already; it would be nice if it didn't as that can be confusing; off topic for here, so I'll write up an issue for that.)

It does feel like there's some cost tradeoff in verbosity and ease of use. It seems like the user would need to learn the anatomy of each component for even a simple use-case. Today, if you're just using the default styles, you don't really need to learn the anatomy.

Migration obv is a tradeoff. I'll stick with skeleton for sure, but I wonder if update fatigue will push people away... Not sure what timeline you're thinking for v4. However (without having tried) this feels like it wouldn't be hard to automatically migrate, and that would mitigate this concern a lot.

Partly playing devil's advocate: at this point, should Skeleton components just wrap/style Ark UI components?

[endigo9740]

I noticed Skeleton includes data-testids on some elements already; it would be nice if it didn't as that can be confusing;

We test our components internally so we need test-ids. But I am going to push for prefixes to these going forward to help reduce the redundancy with user-generated components. Something like avatar -> skeleton:avatar.

It does feel like there's some cost tradeoff in verbosity and ease of use. It seems like the user would need to learn the anatomy of each component for even a simple use-case. Today, if you're just using the default styles, you don't really need to learn the anatomy.

I agree on this point, and I've always pushed to keep Skeleton simple and easy to use. We get a lot of positive feedback around that today. But we also get a lot of feedback about folks wanting to go further too. Wanting more flexibility and control. The good news here is we'll always document and folks will always have a direct reference for how to use each component. And while we're adding complexity with the composed model, we're reducing it with the style prop change. So I'm hoping that's a fair trade off.

Migration obv is a tradeoff. I'll stick with skeleton for sure, but I wonder if update fatigue will push people away... Not sure what timeline you're thinking for v4.

This is part of why we're going to do the trial run with the duplicate Accordion/Avatar components upfront. They are great examples of both the complex and simpler end of our available components. And should give folks a direct hands on experience with what it takes to migrate at a small scale. ETA for the full release won't be rushed, to give folks a bit of breathing room. But there's no perfect option here.

Partly playing devil's advocate: at this point, should Skeleton components just wrap/style Ark UI components?

We use Zag.js, which are the same primitives used for Ark. Ark is by the same folks that build Zag, as well Chakra UI.

https://ark-ui.com/react/docs/overview/introduction#solution

I think we're pretty comfortable with Zag at this point as it strips away an abstraction and just let us get right at the primitives themselves.

[oatmealproblem]

while we're adding complexity with the composed model, we're reducing it with the style prop change. So I'm hoping that's a fair trade off

yep, agreed!

re automatic migration, I'd be willing to help implement that. I'm one of those weirdos who likes working with ASTs

I've seen some mention of a potential plans for a skeleton vscode extension. It'd be cool if that could offer linting or hints about component anatomy, eg you forgot the Accordion.Heading in your Accordion.Item (since there's no good way to enforce child component types, right?). Just a nice-to-have, I wouldn't say that's at all necessary for an initial release. Prior to a bespoke editor extension, it would be nice if each component included an outline of its anatomy in its JSDoc description, so vscode shows that on hover

We use Zag.js, which are the same primitives used for Ark

Yeah, I guess my point was, you're already using the same primitives. With the move to piecemeal components, Skeleton would then be structurally much closer to Ark UI. There's quite a bit of duplicated work between the projects, especially as Skeleton adds more frameworks. Perhaps it's worth just using Ark (and collaborating with them on the Svelte implementations). Though I understand that collaboration itself can also be a quite a bit of work.

strips away an abstraction

also fair

Like I said, I'm partly playing devil's advocate with this point. But seems worth thinking through (which perhaps you've already done)

[endigo9740]

re automatic migration, I'd be willing to help implement that. I'm one of those weirdos who likes working with ASTs

@Hugos68 build and maintains the current CLI and migration process. But I'm sure he would be down for some help when we get to that point.

I've seen some mention of a potential plans for a skeleton vscode extension.

We've discussed it, but I think some of the benefit is lessoned with the singular class. That'll allow for Tailwind suggestions out of the box, which will be nice. But we have another open ticket if you would like to spitball ideas. The main issue is they're kind of a pain to maintain. They require a special license that has to be renewed like quarterly or something. It's a huge hassle tbh.

Perhaps it's worth just using Ark (and collaborating with them on the Svelte implementations).

I've spoke with Chris (the one that heads Ark) and he suggested something similar. I'm going to raise this with Hugo and see what he thinks. You may be onto something.

[oatmealproblem]

It's a huge hassle tbh

Ah, I haven't made an extension before. An eslint plugin could be another option for anatomy validation, and would avoid extension hassle. But as I'm thinking about it, making the AST analysis smart enough to be useful could be a lot of work (if you try to account for things like people using snippets or wrapping components)

Tbh, I think 80% of the benefit that I'm talking about would be achieved by including the anatomy outline in the JSDoc.

[mmailaender]

I noticed that Ark UI — has added first-party support for Svelte as of June 23rd. 🙂

[jhechtf]

I'm not huge on Proposal A -- I've never been huge on that kind of setup, and as I mainly use the Svelte version I much prefer using the snippets. That said, if Prop A is what's needed for Prop C, then I'll go with it. I always enjoy components that are very strong guard rails, but also allow you to break out and do something very custom if/when necessary.

For Prop B, I'm fine with that. I think it's a better way to do it. Again in my likeability-of-escape-hatch-iness what I've done for some custom components of my own is allowed people to define their own classes, whether they conflict with mine or not, and put an override or custom prop to signify to the component to include none of the base classes I apply normally. That might be something worth considering, and simply having it in the docs with a call out for it I think would be nice in the instance where a more customized use case comes up.

[Hugos68]

Yep, the verbosity is required for the customizability. But we hope with the help of good examples and documentation around the anatomy this will provide a good base while having the ability to nearly infinitely customize our components to the use cases your application might have. Our current components are more towards the "black box" components (as I like to call them) where they do a lot of things for you, but all wrapped behind an abstraction. This has pro's and con's.

[oatmealproblem]

Is there a way in the proposed API to opt-out of the skb:* styles? I'm thinking of scenarios where you want to heavily customize the look and feel of a component, and it's easier to start from a blank slate.

For example, in the Skeleton v3, you can pass in "" for the various CSS class props to opt-out of styles. In the proposed API, if you pass in class="", you still get all the skb:* classes. To opt out you would need to either:

• Pass in a corresponding tailwind class, eg border-none to opt out of skb:border, etc, which could be tedious (admittedly, only a little more tedious that v3)
• Configure tailwind to not use include classes from @skeletonlabs/skeleton-svelte. That's a good solution if you want to opt out for all components, but not if you want to opt out for a specific instance of a component.

Perhaps there could be a noBaseStyles prop?

I haven't carefully reviewed the related PR, so perhaps this is already addressed.

[endigo9740]

@oatmealproblem we considered something like this for v3 originally, a true headless option. But honestly the extra rings we would have to jump through just wasn't worth the effort. We would end up compiling two version of each package basically. We just lean into the fact our components are pre-styled. If you want headless then there's no shortage of options. You can choose from Zag, Bits UI, Melt UI, etc. Skeleton is also open source so you can just clone the component locally and style to your heart's content.

Also note that we have switched from base: to skb: (skeleton base) as the prefix to avoid unintended collision if users opt for a similar strategy locally. That or use another library that does something similar in the future.

[oatmealproblem]

That's fair. And with everything prefixed, skeleton v4 proposal could be used fully unstyled with by configuring tailwind to ignore @skeletonlabs/skeleton-<FRAMEWORK> as I mentioned. A prop option would only be useful for opting out of styles on a component-by-component basis, which is getting to a pretty niche scenario.

have switched from base: to skb:

Good change! I'll edit my original comment so as to not confuse future readers

[mmailaender]

Really appreciate the direction of these proposals! 🙌

The shift toward smaller, composable components, unified styling via class, and BYOM with Snippets is a massive leap in developer ergonomics. It’s clear that Skeleton is becoming not only more powerful but also more intuitive and maintainable — especially for teams that want full control over their UI.

---

Proposal D? Source-based Components with Update Mechanism

One idea I’d like to add to the conversation is inspired by jsrepo.dev — a Shadcn-style registry that distributes source code instead of compiled packages, but with an integrated update mechanism.

This approach combines the flexibility of shipped source (devs can freely modify and own it) with the benefit of version tracking and updates — something that’s historically been difficult to achieve in source registries.

Since Skeleton leans toward developer control and transparency, I could imagine this being a natural fit. For example, the new composable structure (Proposal A) and class-based styling (Proposal B) would work beautifully in a setup where devs pull in the actual component source, tweak it as needed, and still receive non-breaking updates over time.

It’s definitely a different angle than what’s been proposed so far, but maybe worth considering as a Proposal D — especially for teams that want to opt-in to Skeleton’s design system, while fully owning their implementation.

Thanks again for all the thoughtful work here — excited to see where this goes