docs: add shared state example for bind:group & add labels

[mandrasch]

In the last couple of days I tried to learn the new Svelte v5 $state (notes). I did some small hobby projects with v4 before.

I mainly stumbled over the lack of examples for bind:group with shared state, since object wrapping is needed here when using export. My current guess is that other developers will face the same challenge in future when they just check the docs for bind:group for v5 and try to use it with shared state on their own (like I did). Took me multiple days and support on Discord/Bluesky to get it right.

PR changes to bind-group docs:

• include a small example of shared state to get developers up to speed
• add note that state can't be passed to multiple components with different values
  • related: bind:group does not work with nested components #2308
• add <label> to the whole example to be a11y-complicant

REPL for submitted code

As alternative, a link to a tutorial might help as well.

Keep up the awesome work with Svelte and much success in 2025! 🎉

PS: I know that there is also the section bind:property for components, but I just noticed it afterwards + it's very technical. Wouldn't have helped me. https://svelte.dev/tutorial/svelte/group-inputs also doesn't cover shared state.

Before submitting the PR, please make sure you do the following

• It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
• Prefix your PR title with feat:, fix:, chore:, or docs:.
• This message body should clearly illustrate what problems it solves.
• Ideally, include a test that fails without this PR but passes with it.
• If this PR changes code within packages/svelte/src, add a changeset (npx changeset).

Tests and linting

• Run the tests with pnpm test and lint the project with pnpm lint

Couldn't run pnpm lint on node v23.5.0 and with pnpm 9.15.3

Error: Cannot find module '/Users/XXX/webserver/svelte/node_modules/.pnpm/[email protected]_svelte@packages+svelte/node_modules/svelte/compiler/index.js'

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0ee5c83

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[dummdidumm]

Hey, thanks for the PR. I don't think we can land this in its current form though.

• while you're right about a11y, in this case it would hinder the readability of what we actually want to show; the binding
• shared state and having to export it via an object has nothing to do with bind:group in particular, this is a more general rule. We should probably have something about this within https://svelte.dev/docs/svelte/$state
• the note about not being able to use it on components in certain conditions is certainly a good idea, though we need to make it more clear what exactly does not work

[mandrasch]

Hi, thanks very much for direct reply! :)

Just as personal note: I just checked the v4 docs https://v4.svelte.dev/docs/element-directives#bind-group - and my humble personal opinion is, that the Svelte v5 docs for this might need a general re-think? $state is directly introduced as technical concept in the v5 docs for bind-group - while there were no stores mentioned in v4 docs. Therefore at least a link to a new state section about "shared state for bind:group" (like you mentioned) or a tutorial link is needed imho. People will most likely first check bind:group docs, not $state - at least that's how I approached it? I guess this is also related a bit to the fact that some devs discuss if Svelte has lost (a bit) of it's simplicity in v5 unfortunately? 😔 My feeling is that more detailed examples (not abstract ones) in the docs could ease the pain to switch and restore simplicity?

For this PR:

Should I try to move the shared state example to https://svelte.dev/docs/svelte/$state, remove the labels and link it in bind:group?

[mandrasch]

This could be a good reference for what I had in mind, since shared state is the second example here:

• https://vuejs.org/guide/scaling-up/state-management

Currently the docs take developers to SvelteKits State Managament (gotchas) instead of Sveltes $state system.

The state management guide for SvelteKit could also be improved, reference to Nuxt:

• https://nuxt.com/docs/getting-started/state-management

I think the main problem I have with the current docs is that a lot of things are 'hidden' in the tutorials section. And my current assumption would be that developers check the docs first and do tutorials later (if not elsewhere). Especially when they're experienced with Svelte v4.

But if this PR is not a good place for discussion, please feel free to close and I move it to discussions. Don't want to block your PR queue here. Thanks very much for providing this awesome community framework! 🧡