Svelte Scoped ​

Place generated CSS for each Svelte component's utility styles directly into the Svelte component's <style> block instead of in a global CSS file.

This component:

<div class="mb-1" />

<div class="mb-1" />

is transformed into:

<div class="uno-ei382o" />

<style>
  :global(.uno-ei382o) {
    margin-bottom: 0.25rem;
  }
</style>

<div class="uno-ei382o" />

<style>
  :global(.uno-ei382o) {
    margin-bottom: 0.25rem;
  }
</style>

When to use ​

How it works ​

A regular UnoCSS/Tailwind setup places utility styles in a global CSS file with proper ordering. In contrast, Svelte Scoped distributes your styles across many arbitrarily ordered Svelte component CSS files. However, it must keep the utility styles global to allow them to be context aware as needed for things like right-to-left and other use cases listed below. This presents a challenge that is solved by using Svelte's :global() wrapper to opt out of the default Svelte CSS hashing method and instead use a hash based on filename + class name(s) to compile unique class names that can be made global without style conflicts.

Usage ​

Because Svelte Scoped rewrites your utility class names, you are limited in where you can write them:

Svelte Scoped is designed to be a drop-in replacement for a project that uses utility styles. As such, expressions found within class attributes are also supported (e.g. <div class="mb-1 {foo ? 'mr-1' : 'mr-2'}" />) but we recommend you use the class directive syntax moving forward. Note also that if you've used class names in other ways like placing them in a <script> block or using attributify mode then you'll need to take additional steps before using Svelte Scoped. You can utilize the safelist option and also check the presets section below for more tips.

Context aware ​

Even though styles are distributed across your app's Svelte components, they are still global classes and will work in relationship to elements found outside of their specific components. Here are some examples:

Parent dependent ​

Classes that depend on attributes found in a parent component:

<div class="dark:mb-2 rtl:right-0"></div>

<div class="dark:mb-2 rtl:right-0"></div>

turn into:

<div class="uno-3hashz"></div>

<style>
  :global(.dark .uno-3hashz) {
    margin-bottom: 0.5rem;
  }
  :global([dir="rtl"] .uno-3hashz) {
    right: 0rem;
  }
</style>

<div class="uno-3hashz"></div>

<style>
  :global(.dark .uno-3hashz) {
    margin-bottom: 0.5rem;
  }
  :global([dir="rtl"] .uno-3hashz) {
    right: 0rem;
  }
</style>

Children influencing ​

You can add space between 3 children elements of which some are in separate components:

<div class="space-x-1">
  <div>Status: online</div>
  <Button>FAQ</Button>
  <Button>Login</Button>
</div>

<div class="space-x-1">
  <div>Status: online</div>
  <Button>FAQ</Button>
  <Button>Login</Button>
</div>

turns into:

<div class="uno-7haszz">
  <div>Status: online</div>
  <Button>FAQ</Button>
  <Button>Login</Button>
</div>

<style>
  :global(.uno-7haszz > :not([hidden]) ~ :not([hidden])) {
    --un-space-x-reverse: 0;
    margin-left: calc(0.25rem * calc(1 - var(--un-space-x-reverse)));
    margin-right: calc(0.25rem * var(--un-space-x-reverse));
  }
</style>

<div class="uno-7haszz">
  <div>Status: online</div>
  <Button>FAQ</Button>
  <Button>Login</Button>
</div>

<style>
  :global(.uno-7haszz > :not([hidden]) ~ :not([hidden])) {
    --un-space-x-reverse: 0;
    margin-left: calc(0.25rem * calc(1 - var(--un-space-x-reverse)));
    margin-right: calc(0.25rem * var(--un-space-x-reverse));
  }
</style>

Passing classes to child components ​

You can add a class prop to a component to allow passing custom classes wherever that component is consumed.

<Button class="px-2 py-1">Login</Button>

<Button class="px-2 py-1">Login</Button>

turns into:

<Button class="uno-4hshza">Login</Button>

<style>
  :global(.uno-4hshza) {
    padding-left:0.5rem;
    padding-right:0.5rem;
    padding-top:0.25rem;
    padding-bottom:0.25rem;
  }
</style>

<Button class="uno-4hshza">Login</Button>

<style>
  :global(.uno-4hshza) {
    padding-left:0.5rem;
    padding-right:0.5rem;
    padding-top:0.25rem;
    padding-bottom:0.25rem;
  }
</style>

An easy way to implement the class in a receiving component would be to place them on to an element using {$$props.class} as in div class="{$$props.class} foo bar" />.

Apply directives ​

You can use apply directives inside your <style> blocks with either --at-apply or @apply or a custom value set using the applyVariables option.

Svelte Scoped even properly handles context dependent classes like dark:text-white that the regular @unocss/transformer-directives package can't handle properly because it wasn't built specifically for Svelte style blocks. For example, with Svelte Scoped this component:

<div />

<style>
  div {
    --at-apply: rtl:ml-2;
  }
</style>

<div />

<style>
  div {
    --at-apply: rtl:ml-2;
  }
</style>

will be transformed into:

<div />

<style>
  :global([dir=\\"rtl\\"]) div {
    margin-right: 0.5rem;
  }
</style>

<div />

<style>
  :global([dir=\\"rtl\\"]) div {
    margin-right: 0.5rem;
  }
</style>

In order for rtl:ml-2 to work properly, the [dir="rtl"] selector is wrapped with :global() to keep the Svelte compiler from stripping it out automatically as the component has no element with that attribute. However, div can't be included in the :global() wrapper because that style would then affect every div in your app.

Vite Plugin ​

In Svelte or SvelteKit apps, inject generated styles directly into your Svelte components, while placing the minimum necessary styles in a global stylesheet. Check out the SvelteKit example in Stackblitz:

Install ​

pnpm add -D unocss @unocss/svelte-scoped

pnpm add -D unocss @unocss/svelte-scoped

yarn add -D unocss @unocss/svelte-scoped

yarn add -D unocss @unocss/svelte-scoped

npm install -D unocss @unocss/svelte-scoped

npm install -D unocss @unocss/svelte-scoped

Add plugin ​

Add @unocss/svelte-scoped/vite to your Vite config:

// vite.config.ts
import { defineConfig } from 'vite'
import { sveltekit } from '@sveltejs/kit/vite'
import UnoCSS from '@unocss/svelte-scoped/vite'

export default defineConfig({
  plugins: [
    UnoCSS({
      // injectReset: '@unocss/reset/normalize.css', // see type definition for all included reset options or how to pass in your own
      // ...other Svelte Scoped options
    }),
    sveltekit(),
  ],
})

// vite.config.ts
import { defineConfig } from 'vite'
import { sveltekit } from '@sveltejs/kit/vite'
import UnoCSS from '@unocss/svelte-scoped/vite'

export default defineConfig({
  plugins: [
    UnoCSS({
      // injectReset: '@unocss/reset/normalize.css', // see type definition for all included reset options or how to pass in your own
      // ...other Svelte Scoped options
    }),
    sveltekit(),
  ],
})

Add config file ​

Setup your uno.config.ts file as described below.

Global styles ​

While almost all styles are placed into individual components, there are still a few that must be placed into a global stylesheet: preflights, safelist, and an optional reset (if you use the injectReset option).

Add the %unocss-svelte-scoped.global% placeholder into your <head> tag. In Svelte this is index.html. In SvelteKit this will be in app.html before %sveltekit.head%:

<head>
  <!-- ... -->
  <title>SvelteKit using UnoCSS Svelte Scoped</title>
  %unocss-svelte-scoped.global%
  %sveltekit.head%
</head>

<head>
  <!-- ... -->
  <title>SvelteKit using UnoCSS Svelte Scoped</title>
  %unocss-svelte-scoped.global%
  %sveltekit.head%
</head>

If using SvelteKit, you also must add the following to the transformPageChunk hook in your server.hooks.js file:

/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
  const response = await resolve(event, {
    transformPageChunk: ({ html }) => html.replace('%unocss-svelte-scoped.global%', 'unocss_svelte_scoped_global_styles'),
  })
  return response
}

/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
  const response = await resolve(event, {
    transformPageChunk: ({ html }) => html.replace('%unocss-svelte-scoped.global%', 'unocss_svelte_scoped_global_styles'),
  })
  return response
}

In a regular Svelte project, Vite's transformIndexHtml hook will do this automatically.

Svelte Preprocessor ​

Use utility styles to build a component library that is not dependent on including a companion CSS file by using a preprocessor to place generated styles directly into built components. Check out the SvelteKit Library example in Stackblitz:

Install ​

pnpm add -D unocss @unocss/svelte-scoped

pnpm add -D unocss @unocss/svelte-scoped

yarn add -D unocss @unocss/svelte-scoped

yarn add -D unocss @unocss/svelte-scoped

npm install -D unocss @unocss/svelte-scoped

npm install -D unocss @unocss/svelte-scoped

Add preprocessor ​

Add @unocss/svelte-scoped/preprocess to your Svelte config:

// svelte.config.js
import adapter from '@sveltejs/adapter-auto'
import { vitePreprocess } from '@sveltejs/kit/vite'
import UnoCSS from '@unocss/svelte-scoped/preprocess'

const config = {
  preprocess: [
    vitePreprocess(),
    UnoCSS({
      // ... preprocessor options
    }),
  ],
  // other Svelte config
}

// svelte.config.js
import adapter from '@sveltejs/adapter-auto'
import { vitePreprocess } from '@sveltejs/kit/vite'
import UnoCSS from '@unocss/svelte-scoped/preprocess'

const config = {
  preprocess: [
    vitePreprocess(),
    UnoCSS({
      // ... preprocessor options
    }),
  ],
  // other Svelte config
}

Don't combine class names in development ​

When using Svelte Scoped in a normal app, the Vite plugin will automatically detect dev vs build. In development, classes will be kept distinct and hashed in place for ease of toggling on/off in your browser's developer tools. class="mb-1 mr-1" will turn into something like class="_mb-1_9hwi32 _mr-1_84jfy4. In production, these will be compiled into a single class name using your desired prefix, uno- by default, and a hash based on the filename + class names, e.g. class="uno-84dke3.

If you want this same behavior when using the preprocessor, you must manually set the the combine option based on environemnt. One way to do this is to install cross-env and update your dev script to this:

"dev": "cross-env NODE_ENV=development vite dev",

"dev": "cross-env NODE_ENV=development vite dev",

Then adjust your svelte.config.js:

+const prod = process.env.NODE_ENV !== 'development'
const config = {
  preprocess: [
    vitePreprocess(),
    UnoCSS({
+      combine: prod,
    }),
  ],
}

+const prod = process.env.NODE_ENV !== 'development'
const config = {
  preprocess: [
    vitePreprocess(),
    UnoCSS({
+      combine: prod,
    }),
  ],
}

Add config file ​

Setup your uno.config.ts file as described below.

Preflights ​

When using the preprocessor you have the option to include preflights in your component by adding uno:preflights as a style attribute.

<style uno:preflights></style>

<style uno:preflights></style>

Adding preflights into individual components is unnecessary if your classes do not depend on preflights or your built components are being consumed only in apps that already include preflights.

Safelist ​

When using the preprocessor you have the option to include safelist classes in your component by adding uno:safelist as a style attribute.

<style uno:safelist global></style>

<style uno:safelist global></style>

To avoid having the Svelte compiler then strip them out because they're not found in the component, you'll also need to add the global modifier which will require https://github.com/sveltejs/svelte-preprocess. It's probably easier to just use --at-apply instead:

<div class:computed-foo={condition} />

<style>
  :global(.computed-foo) {
    --at-apply: mb-1 mr-2;
  }
</style>

<div class:computed-foo={condition} />

<style>
  :global(.computed-foo) {
    --at-apply: mb-1 mr-2;
  }
</style>

Configuration ​

Place your UnoCSS settings in an uno.config.ts file:

// uno.config.ts
import { defineConfig } from 'unocss'

export default defineConfig({
  // ...UnoCSS options
})

// uno.config.ts
import { defineConfig } from 'unocss'

export default defineConfig({
  // ...UnoCSS options
})

See Config File and Config reference for more details.

Presets support ​

Do to the nature of having a few necessary styles in a global stylesheet and everything else contained in each component where needed, presets need to be handled on a case-by-case basis:

For other presets, if they don't rely on traditional class="..." usage you will need to first preprocess those class names into the class="..." attribute. If they add extremely complex styles like typography's .prose class then you may need to place the complex class names into your safelist.

Scoped utility classes unleashes creativity ​

Some advice on when you might want to use scoped styles: A global css file that includes everything is great for smaller apps, but there will come a point in a large project's life when every time you start to write a class like .md:max-w-[50vw] that you know is only going to be used once you start to cringe as you feel the size of your global style sheet getting larger and larger. This inhibits creativity. Sure, you could use --at-apply: md:max-w-[50vw] in the style block but that gets tedious and styles in context are so useful. Furthermore, if you would like to include a great variety of icons in your project, you will begin to feel the weight of adding them to the global stylesheet. When each component bears the weight of its own styles and icons you can continue to expand your project without having to analyze the cost benefit of each new addition.

License ​

• MIT License © 2022-PRESENT Jacob Bowdoin