A lightweight yet powerful solution to support multiple color schemes in your Svelte/SvelteKit application.
๐ค lightweight (<1kb)
๐ช powerful
๐ easy to use
๐ fast and efficient
๐ช nested schemes
โฑ๏ธ supports SSR (Server-Side Rendering)
๐ฆบ best TypeScript support (works with JavaScript projects too)
โ no external dependencies
Click here to see some live examples
-
โจ๏ธ Install
sthemer
as a dependency.npm install sthemer
-
๐ง Add the style mixin globally.
svelte.config.js
import preprocess from 'svelte-preprocess' /** @type {import('@sveltejs/kit').Config} */ const config = { preprocess: preprocess({ scss: { prependData: `@import 'sthemer/mixins';`, }, }), } export default config
This example uses
scss
as css preprocessor. Other formats are also supported. See the supported CSS preprocessors section for more details. -
๐ Wrap your code with the
Sthemer.svelte
component and define your preferred strategy.App.svelte or __layout.svelte
<script> import Sthemer from 'sthemer/Sthemer.svelte' </script> <Sthemer strategy="auto"> <!-- your application goes here --> </Sthemer>
-
๐จ Define styles for your components.
Button.svelte
<button on:click> <slot /> </button> <style lang="scss"> button { // styles that apply to both schemes font-size: 1.3rem; padding: 10px 20px; border-radius: 8px; // these styles will apply when the component gets rendered on a 'dark' wrapper @include on-dark { background-color: white; color: black; } // these styles will apply when the component gets rendered on a 'light' wrapper @include on-light { background-color: black; color: white; } } </style>
-
๐ Thats it. Play around and explore the docs to see some more examples.
-
โญ Star this project on GitHub.
Thanks! This helps the project to grow.
To wrap your application or parts of it. It will set up everything in order for you to just define the styles of your components.
<script>
import Sthemer from 'sthemer/Sthemer.svelte'
</script>
<Sthemer strategy="auto" let:scheme>
I am rendered on a <strong>{scheme}</strong>
wrapper.
</Sthemer>
strategy
(optional): the strategy to use.
The component reacts to changes to thestrategy
prop and changes the color scheme accordingly.
let:scheme
: the current used scheme.
To get the current used scheme, use thelet:scheme
slot prop.
To programmatically access the current used scheme and strategy, you can call getSthemerContext()
. The returned object contains two items:
- strategy: a
writable-store
containing the strategy to use. - scheme: a
readable-store
containing the used color scheme.
<script>
import { getSthemerContext } from 'sthemer/context'
const { strategy, scheme } = getSthemerContext()
const toggleStrategy = () => {
$strategy = $strategy === 'dark' ? 'light' : 'dark'
}
</script>
<button on:click={toggleStrategy}>Toggle strategy</button>
Used scheme: {$scheme}
sthemer
works with the most used CSS preprocessors to provide you with a good user experience. It is recommended to use one of the following options.
-
Add the mixin globally.
svelte.config.js
import preprocess from 'svelte-preprocess' /** @type {import('@sveltejs/kit').Config} */ const config = { preprocess: preprocess({ scss: { prependData: `@import 'sthemer/mixins';`, }, }), } export default config
-
Define styles for your components.
Component.svelte
<button on:click> <slot /> </button> <style lang="scss"> button { // these styles will apply when the component gets rendered on a 'dark' wrapper @include on-dark { background-color: white; color: black; } // these styles will apply when the component gets rendered on a 'light' wrapper @include on-light { background-color: black; color: white; } } </style>
-
Add the mixin globally.
svelte.config.js
import preprocess from 'svelte-preprocess' /** @type {import('@sveltejs/kit').Config} */ const config = { preprocess: preprocess({ less: { prependData: `@import 'sthemer/mixins';`, }, }), } export default config
-
Define styles for your components.
Component.svelte
<button on:click> <slot /> </button> <style lang="less"> button { // these styles will apply when the component gets rendered on a 'dark' wrapper .on-dark({ background-color: white; color: black; }); // these styles will apply when the component gets rendered on a 'light' wrapper .on-light({ background-color: black; color: white; }); } </style>
-
Add the mixin globally.
svelte.config.js
import preprocess from 'svelte-preprocess' /** @type {import('@sveltejs/kit').Config} */ const config = { preprocess: preprocess({ sass: { prependData: `@import 'sthemer/mixins'`, }, }), } export default config
-
Define styles for your components.
Component.svelte
<button on:click> <slot /> </button> <style lang="sass"> button // these styles will apply when the component gets rendered on a 'dark' wrapper @include on-dark background-color: white color: black // these styles will apply when the component gets rendered on a 'light' wrapper @include on-light background-color: black color: white </style>
-
Define styles for your components.
Component.svelte
<button on:click> <slot /> </button> <style> // these styles will apply when the component gets rendered on a 'dark' wrapper :global(.sthemer-dark) button { background-color: white; color: black; } // these styles will apply when the component gets rendered on a 'light' wrapper :global(.sthemer-dark) button { background-color: black; color: white; } </style>
sthemer
supports the built-in color schemes 'dark' and 'light'.
- light: The user expects a light background and dark text.
- dark: The user expects a dark background and light text.
-
default value
Auto-detects the user's preferred color scheme.
The prefers-color-scheme media query is used to determine the user's preferred color scheme.
Read here to know how to add SSR support.
-
Use the light color scheme.
-
Use the dark color scheme.
-
Use the inverted color scheme.
If used on a light color scheme, it will be dark and vice versa. Can be useful when using nested schemes. When used at the root, it uses the inverted color scheme from the 'auto'-strategy.
Read here to know how to add SSR support.
By default sthemer
doesn't output code that can be used with nested color schemes. But you can manually specify how many levels of nesting you want support.
-
-
globally
svelte.config.js
// set the '$sthemerLevels' variable to the value you want prependData: '@import 'sthemer/mixins'; $sthemerLevels: 3',
-
for a specific selector
Component.svelte
button { // add the amount of levels as a parameter @include on-dark(3) { background-color: white; } }
-
-
-
globally
svelte.config.js
// set the '@sthemerLevels' variable to the value you want prependData: `@import 'sthemer/mixins'; @sthemerLevels: 3;`,
-
for a specific selector
Component.svelte
button { .on-dark({ background-color: white; }, 3); // add the amount of levels as a second parameter }
-
-
-
globally
svelte.config.js
// set the '$sthemerLevels' variable to the value you want prependData: ` @import 'sthemer/mixins' $sthemerLevels: 3 `,
-
for a specific selector
Component.svelte
button // add the amount of levels as a parameter @include on-dark(3) background-color: white
-
-
If you want to support multiple levels of nesting with plain CSS, you need to manually add them if you are not using a preprocessor like
sass
,scss
orless
.// these styles will apply when the component gets rendered on a 'dark' wrapper // (supports 3 levels of nesting) :global(.sthemer-dark) button, :global(.sthemer-light) :global(.sthemer-dark) button, :global(.sthemer-dark) :global(.sthemer-light) :global(.sthemer-dark) button { background-color: white; color: black; } // these styles will apply when the component gets rendered on a 'light' wrapper // (supports 3 levels of nesting) :global(.sthemer-light) button, :global(.sthemer-dark) :global(.sthemer-light) button, :global(.sthemer-light) :global(.sthemer-dark) :global(.sthemer-light) button { background-color: black; color: white; }
sthemer
also works with your SvelteKit projects that perform server-side rendering.
Note: this currently is only supported in Chrome >= 93. The feature was not added yet for Firefox and Safari.
If you want to use the inverted
strategy at the root level or the auto
strategy, you need to make a small adjustments to your SvelteKit project.
By default the server doesn't know what color scheme the user is using. To get that information the server has to respond with some custom HTTP headers. The browser then performs the request again with the information about the preferred color scheme.
sthemer
already provides this functionality and you just have to connect it to your SvelteKit project:
-
if you don't have a hooks.server.js file yet, create one with the following content:
export { handle } from 'sthemer/hooks'
-
or if you already have a hooks.server.js file, add following lines to the top of the
handle
function:+import { setupSthemer } from 'sthemer/hooks' /** @type {import('@sveltejs/kit').Handle} */ export async function handle({ event, resolve }) { + const sthemerResponse = setupSthemer(event) + if (sthemerResponse) return sthemerResponse // your custom logic goes here return await resolve(event) }
Become a sponsor โค๏ธ if you want to support my open source contributions.
Thanks for sponsoring my open source work!
Probably not, but sthemer
offers everything you could potentially need and can handle edge-cases like SSR
and nesting for you.
You can also just take a look at the source code and take the parts you are interested in without using the full library.
Instead of writing your components like this:
:root {
--c-dark-primary: #212121;
--c-dark-secondary: #303030;
--c-dark-tertiary: #424242;
--c-light-primary: #fafafa;
--c-light-secondary: #f5f5f5;
--c-light-tertiary: #e0e0e0;
}
button {
color: var(--c);
background-color: var(--c-bg);
border-color: var(--c-border);
&:hover {
background-color: var(--c-bg--hover);
}
&.on-dark {
--c: var(--c-dark-primary);
--c-bg: var(--c-light-secondary);
--c-border: var(--c-light-tertiary);
&:hover {
--c-bg--hover: var(--c-light-primary);
}
}
&.on-light {
--c: var(--c-light-primary);
--c-bg: var(--c-dark-secondary);
--c-border: var(--c-dark-tertiary);
&:hover {
--c-bg--hover: var(--c-dark-primary);
}
}
}
you could also use the following approach:
.dark-mode {
--c-primary: #212121;
--c-secondary: #303030;
--c-tertiary: #424242;
--c-primary-inverted: #fafafa;
--c-secondary-inverted: #f5f5f5;
--c-tertiary-inverted: #e0e0e0;
}
.light-mode {
--c-primary: #fafafa;
--c-secondary: #f5f5f5;
--c-tertiary: #e0e0e0;
--c-primary-inverted: #212121;
--c-secondary-inverted: #303030;
--c-tertiary-inverted: #424242;
}
button {
color: var(--c-primary);
background-color: var(--c-secondary-inverted);
border-color: var(--c-tertiary-inverted);
&:hover {
background-color: var(--c-primary-inverted);
}
}
But you probably shouldn't do that. There are a few reasons why you should use the approach that sthemer
provides:
-
It makes it easier to reason about how the component changes its appearance based on the color scheme.
At first glance this may sound not so important. And it requires you to also write more code. But in the long run you will benefit from it. Not having to jump around different files to make a color adjustment will make your code more readable and easier to maintain. -
You probably need to vary from the variables you define at the root in some edge cases which will become hard to implement when you base your theming on pre-existing variables.
The border color on the dark button looks a bit odd. Maybe we should try to use--c-primary-inverted
, but we want to keep--c-tertiary-inverted
for the light button. How would you do that? You would probably need to define a new variable called--c-button-border
and a few weeks later you will have 20+ variables defined at the root level, that are decoupled from their components and only get used a single time for a specific component.
Nesting is a feature that probably won't get used by most projects. Nesting produces more code, so it is disabled per default (see also next question). If you want to use it, you can enable it easily.
The more levels of nesting you are using, the longer the required CSS selector is and so the file size of the resulting CSS will be larger. But It will not account that much to the amount of data an user has to download. Modern browsers and tools have good support for gzip compression. Because those selectors will look quite similar, gzip compression will perform great and reduce the size.
You probably will never need it. You can wrap the root of your application with the Sthemer
and define your styles there. This approach also makes it possible to use nested schemes in a consistent way.