``` 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. The marker is derived per selector, so a compound rule like `.parent-owned.dimmed` yields a single marker node that carries both classes: ```svelte {#snippet __svelte_scoped_props_marker()} {/snippet} ``` The snippet is never called, so that node 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. Combinator selectors are mirrored the same way — `.a .b` becomes a nested pair of marker nodes — so compound and combinator scoped rules survive pruning. The nodes are `` rather than typed tags, so the marker is dynamically typed: Svelte's pruner matches it against any element-qualified selector, and it carries no void or content-model constraints. 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. # ESLint > Configure the Svelte Scoped Props ESLint processor for svelte/valid-compile. **Source:** [https://scoped.svelte.page/docs/eslint](https://scoped.svelte.page/docs/eslint) --- The Svelte preprocessor fixes `scoped:class` during builds, but ESLint sees a different path. `eslint-plugin-svelte` runs `svelte/valid-compile` against the source it receives from ESLint, so raw `scoped:class` can fail before your Svelte build preprocessor ever gets a turn. Without the lint processor, a scoped prop can produce errors like: ```txt Attributes should not contain ':' characters to prevent ambiguity with Svelte directives Unused CSS selector ".parent-owned" ``` Use the package's ESLint processor to run the same scoped-props transform before Svelte lint rules compile the component. ## Flat config Add the scoped props config after `eslint-plugin-svelte`'s flat config. ```js title="eslint.config.js" import svelte from 'eslint-plugin-svelte' import scopedProps from '@humanspeak/svelte-scoped-props/eslint' export default [ ...svelte.configs['flat/recommended'], ...scopedProps.configs.recommended ] ``` ESLint only supports one active processor per file. Placing this config after the Svelte config lets the Svelte parser and rules remain active while the scoped props processor supplies transformed markup for `.svelte` files. ## Custom options If your Svelte preprocessor uses custom hash options, pass the same options to the ESLint processor. ```js title="eslint.config.js" import svelte from 'eslint-plugin-svelte' import { createProcessor } from '@humanspeak/svelte-scoped-props/eslint' export default [ ...svelte.configs['flat/recommended'], { files: ['**/*.svelte'], processor: createProcessor({ cssHash: ({ css, filename, hash }) => `my-${hash(filename ?? css)}` }) } ] ``` The processor accepts the same option shape as `scopedProps()`: `cssHash`, `marker`, `normalizeFilename`, and `runtimeModule`. ## What gets transformed Static scoped props are rewritten into normal props before linting. ```svelte ``` ```svelte ``` Dynamic `ClassValue` expressions use the same runtime helper call as the build preprocessor. ```svelte ``` Prop aliases work the same way. ```svelte ``` Parent-side object spreads still cannot express scoped intent. Scope before the prop is collected into an object, then forward the transformed prop normally. ## Message locations The processor remaps lint messages back to the source you authored. Diagnostics from other ESLint rules should point at `scoped:class` or the original expression, not at the generated `class={__svelte_scoped_props_class(...)}` output. Autofixes are kept when their ranges map cleanly to authored source. Fixes that would edit generated helper code or marker snippets are dropped. ## CSS selector checks For `svelte/valid-compile`, the processor also adds the same marker snippet used by the build preprocessor. That marker lets Svelte's CSS analysis see the local class name, so the selector is not reported as unused just because the class is handed to a child component prop. The marker does not render. # 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. If CI runs `svelte/valid-compile`, add the [ESLint processor](/docs/eslint) so lint sees the same transform as your Svelte build. 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 selectors alive during CSS analysis. The marker is synthesized from the component's own selectors: for each scoped selector that has a combinator it emits a chain of `` nodes that mirrors the selector's structure (nested elements for descendant and child combinators, adjacent siblings for `+` and `~`, pseudo-classes stripped), plus a flat fallback `` that carries every scoped class at once. Because the marker nodes are dynamically typed, Svelte's pruner matches them against any element-qualified selector and they carry no element content-model or void constraints, so single-compound selectors are defended by the fallback alone. 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. ## Selector support The scanner is intentionally small and is not a full CSS parser. For scoped classes it synthesizes marker structure — so these selector forms survive Svelte's unused-CSS pruning and keep the correct scope hash: - Compound classes on one element, such as `.page-rows.paged`. - Descendant, child, and sibling combinators, such as `.a .b`, `.a > .b`, and `span.a + button.b`. - Any element-qualified selector, including void and custom elements, such as `button.foo`, `input.bar`, or `my-widget.baz` — the marker element is dynamically typed, so it matches any type and has no void or content-model constraints. These forms are not matched — only the flat fallback element defends them, so their structural shape can still be pruned: - Selectors containing attribute selectors, such as `.a[data-open]`. - A `:global(...)` compound sitting inside a chain. - Functional or positional pseudo-classes such as `:has()`, `:nth-child()`, and `:not()` — pseudos are stripped, not matched. ## Style block is exempt from unused-CSS pruning A component that uses `scoped:` effectively opts its `