``` Use normal Svelte `class` behavior for native elements. # ClassValue > Dynamic scoped props support Svelte-style ClassValue inputs. **Source:** [https://scoped.svelte.page/docs/class-value](https://scoped.svelte.page/docs/class-value) --- Dynamic scoped props accept Svelte-style `ClassValue` inputs: strings, arrays, object maps, and falsy entries. ```ts import type { ClassValue } from 'svelte/elements' ``` ```svelte ``` The preprocessor turns the expression into a runtime helper call. ```svelte ``` The helper normalizes the value, removes disabled object-map keys, joins arrays, and appends the parent scope hash. ## Typing child props When a child prop is class-like, type it as `ClassValue`. ```svelte

Child content

``` That `Props` shape is a child component contract. The preprocessor does not inspect the child's TypeScript types. # Design Notes > Why Svelte Scoped Props exists as an ecosystem proof before proposing compiler support. **Source:** [https://scoped.svelte.page/docs/design-notes](https://scoped.svelte.page/docs/design-notes) --- Svelte Scoped Props is a proof vehicle. The goal is to test the shape, tradeoffs, and failure modes of `scoped:` in userland before asking the Svelte team to consider anything like it in core. ## TLDR We still believe the child component should own its styling contract. A child should decide which props are class-like, where those props land, and whether a prop named `class` even means CSS. But Svelte works from the parent component's markup and scoped CSS analysis. At the point where we can cheaply rewrite a parent call site, we do not have a reliable child type graph or child prop contract. So the alpha takes the smallest explicit path: ```svelte ``` The parent declares, at the usage site, "this value is one of my scoped CSS classes." The child still decides what to do with the resulting normal prop. There are now two companion artifacts for reviewing the idea: a [live proof page](https://poc-scoped-svelte-page.humanspeak.workers.dev) that shows the cases running, including SSR, and a [Svelte fork PR](https://github.com/humanspeak/svelte/pull/1) that sketches what native compiler support could look like. ## Why Test This Outside Core? An installable package gives us a real place to prove the idea. - We can test literal values, dynamic `ClassValue`s, aliases, spread forwarding, SSR, and CSS pruning against an actual app. - We can find bad edges before proposing language or compiler surface. - We can show screenshots, examples, and failing cases instead of asking maintainers to reason from an abstract issue. - We can learn whether people actually want this syntax before adding weight to Svelte itself. Native compiler support would be cleaner than this package. It would already know the scope hash, could avoid the marker snippet, and could place runtime helpers without a published-package workaround. This package exists to make the case concrete. ## How We Got Here ### Plain component `class` cannot be magical This is the maintainer mantra around this subject, and this package is designed to respect it. In Svelte, `class` on a component is just a prop. A component can use `class` as CSS, as data, or not at all. As a Svelte repo member put it in the `class` attribute discussion, the compiler does not know how a component uses a prop named `class`; it could mean something completely different. Automatically treating every component `class` as a scoped CSS handoff would break that contract. It would also smuggle new language behavior behind a prop name that already belongs to component authors. That is why plain `class` stays plain: ```svelte ``` The caller must opt in: ```svelte ``` #### References - [Svelte issue #9044 comment](https://github.com/sveltejs/svelte/issues/9044#issuecomment-1653301326) - Svelte repo member explanation that `class` on a component is just a component property, so compiler magic based on the prop name would be risky. - [Svelte issue #6972](https://github.com/sveltejs/svelte/issues/6972) - ` ``` The preprocessor can rewrite the prop: ```svelte ``` but the selector still is not attached to a local element in the parent component's markup. Outside core, the package has to preserve the parent selector by adding an uncalled snippet marker: ```svelte {#snippet __svelte_scoped_props_marker()}

{/snippet} ``` The snippet is never called, so that `

` never renders. It only gives Svelte's CSS analysis a local class usage to see, which keeps the selector alive and lets Svelte add the correct scope hash. That marker is an implementation scar. Native support would already know that `scoped:class` is intentionally exporting a parent-scoped class through a component prop, so it could preserve the selector directly without the fake snippet. ## What This Alpha Is Trying To Prove - `scoped:` is explicit enough to avoid automatic component `class` magic. - The child remains the owner of where class-like props are applied. - Prop aliases are necessary for real wrapper components. - Dynamic `ClassValue` support matters. - SSR needs the scoped class in the rendered HTML, not after hydration. - Spread forwarding is viable once the parent has already scoped the value. - The language boundary is clear: this works in Svelte markup, not arbitrary objects. ## Current Bet The current bet is that explicit usage-site syntax is the best testable compromise: small enough to ship as an ecosystem package, clear enough to discuss with the team, and honest about the places where native compiler support would do a better job. # Get started with Svelte Scoped Props > Use explicit scoped: props to pass parent-scoped Svelte classes through component props. **Source:** [https://scoped.svelte.page/docs](https://scoped.svelte.page/docs) --- **Svelte Scoped Props** adds an explicit `scoped:` directive for component props. It is for the narrow case where the parent owns a scoped CSS selector, but the element that needs the class lives inside a child component. ```svelte ``` Before Svelte compiles the component, the preprocessor rewrites the directive into a normal prop value with the parent component's CSS hash attached. ```svelte ``` The child still controls what happens next. If it applies `class` to an internal element, that internal element receives the parent-scoped class. If it treats `class` as data, Svelte Scoped Props does not force it to become CSS. ## Install ```bash pnpm add -D @humanspeak/svelte-scoped-props ``` ## Configure Svelte Add the preprocessor after your style preprocessors so it sees the same CSS Svelte will hash. ```ts title="svelte.config.ts" import { vitePreprocess } from '@sveltejs/vite-plugin-svelte' import { scopedProps } from '@humanspeak/svelte-scoped-props' export default { preprocess: [ vitePreprocess(), scopedProps({ runtimeModule: '@humanspeak/svelte-scoped-props/runtime' }) ] } ``` The `runtimeModule` option points dynamic `ClassValue` props at the published scoped package runtime. Literal props do not import the runtime helper. ## First scoped prop ```svelte title="Parent.svelte" ``` ```svelte title="ChildCard.svelte"

Child content

``` The class is authored in `Parent.svelte`, but the child can decide where it lands. The generated prop contains the parent scope hash, so the parent style can match the child's internal element. ## Dynamic values Dynamic scoped props accept the same `ClassValue` shapes used by Svelte class attributes: strings, arrays, and object maps. ```svelte ``` The preprocessor routes dynamic values through a tiny runtime helper that normalizes the value and appends the scope hash. ## Prop aliases The prop name comes after `scoped:`. ```svelte ``` That rewrites to an `internalClass` prop. The child can expose whatever class-like prop names make sense for its API. ## Spread forwarding `scoped:` intent must be expressed before a spread object exists. ```svelte ``` After the preprocessor rewrites the prop, a middle component can forward it like any other prop. ```svelte ``` A raw object spread cannot contain `scoped:` syntax, so scope first and spread later. ## What this is not - It is not a Svelte core feature. - It does not make every component `class` prop special. - It does not inspect child component TypeScript types. - It does not cross language boundaries where Svelte markup is no longer available. For the full package surface, see the [API Reference](/docs/api-reference). For the current caveats, see [Limits](/docs/limits). # Limits > Current alpha constraints and design boundaries for Svelte Scoped Props. **Source:** [https://scoped.svelte.page/docs/limits](https://scoped.svelte.page/docs/limits) --- Svelte Scoped Props is an experiment. These boundaries are intentional for the alpha. ## Not a Svelte core feature The package is a preprocessor that runs before Svelte parses the component. Native compiler support would have access to Svelte's already-computed CSS scope hash and would not need to mirror private hash behavior. ## Private hash mirror Svelte does not currently export its default `cssHash` helper as a public API. This package mirrors that implementation. If Svelte changes the private default hash, projects should update this package or pass their own `cssHash`. ```ts scopedProps({ cssHash: ({ css, filename, hash }) => `svelte-${hash(filename ?? css)}` }) ``` ## No child type graph The preprocessor does not inspect the imported child component or its TypeScript prop types. `scoped:class` is an explicit usage-site decision by the parent. That keeps the transform small, but it also means `scoped:` cannot automatically know which child props are `ClassValue` props. ## Component tags only Only uppercase and dotted component tags are supported. ```svelte ``` Native elements are rejected because normal Svelte `class` behavior already works there. ## Scope before spread Object spreads cannot express Svelte directive syntax. Use `scoped:` before props are collected into an object, then forward the transformed prop normally. ## Marker snippet By default, the transform adds an uncalled snippet marker so Svelte keeps the parent CSS selector alive during CSS analysis. The marker does not render, but it can leave a small unused function in compiled output. ```ts scopedProps({ marker: false }) ``` Only disable the marker when you are running transform-level tests and are not asking Svelte to compile scoped CSS. ## CSS scanning The alpha scanner is intentionally small. It handles normal class selectors, but it is not a full CSS parser. Escaped or highly unusual selector forms may need more work. # Prop aliases > Use scoped: with class-like prop aliases such as internalClass. **Source:** [https://scoped.svelte.page/docs/prop-aliases](https://scoped.svelte.page/docs/prop-aliases) --- `scoped:` is not limited to `class`. The prop name after `scoped:` is preserved. ```svelte ``` That becomes: ```svelte ``` Aliases are useful when a component exposes more than one class-like entry point. ```svelte title="FancyCard.svelte"

``` The parent chooses which child prop receives the scoped class. The child still chooses where that prop is applied. # Spread forwarding > Scope a prop before spreading it through intermediate components. **Source:** [https://scoped.svelte.page/docs/spread-forwarding](https://scoped.svelte.page/docs/spread-forwarding) --- `scoped:` is syntax, not object data. That means scoped intent must be expressed in markup before a spread object exists. ```svelte title="Parent.svelte" ``` After the preprocessor runs, the middle component receives a normal `class` prop with the parent hash attached. ```svelte title="MiddleChild.svelte" ``` ```svelte title="FinalChild.svelte"

Forwarded child

``` ## What does not work There is no object-spread equivalent of `scoped:class`. ```svelte ``` Scope before spread. Once transformed, the prop can be forwarded normally. # SSR > Scoped props are rewritten before Svelte compiles server and client output. **Source:** [https://scoped.svelte.page/docs/ssr](https://scoped.svelte.page/docs/ssr) --- Svelte Scoped Props runs before Svelte compiles the component. That means literal scoped props are present in the server-rendered HTML. ```svelte ``` is compiled as if the parent wrote: ```svelte ``` There is no client effect that waits for hydration to add the parent scope hash. The server and client compile from the same transformed source. ## Dynamic values Dynamic values use the runtime helper on both server and client. ```svelte ``` The helper is pure string normalization. It does not read the DOM, start observers, or wait for the browser. ## Test route The package includes a visual SvelteKit test page at `/tests/scoped-props` and an SSR check route at `/tests/scoped-props/ssr-check`. Those routes are intentionally test fixtures, not marketing docs. # Syntax > How to use scoped: props on Svelte component tags. **Source:** [https://scoped.svelte.page/docs/syntax](https://scoped.svelte.page/docs/syntax) --- Use `scoped:` on a component tag when the parent intentionally passes one of its scoped CSS classes through a child prop. ```svelte ``` The directive target is the prop name after `scoped:`. ```svelte ``` becomes: ```svelte ``` ## Component tags only Use `scoped:` on components, not native elements. ```svelte ``` Native elements already live in the current component, so normal `class` behavior is the right tool. ```svelte

``` ## Explicit values only The directive must include a value. ```svelte ``` ## No duplicate target prop Do not combine `scoped:class` and `class` on the same component. ```svelte ``` The transform rejects this because it would be unclear which value should win.