@vanilla-extract/dynamic
Advanced tools
Zero-runtime Stylesheets-in-TypeScript.
Write your styles in TypeScript (or JavaScript) with locally scoped class names and CSS Variables, then generate static CSS files at build time.
Basically, it’s “CSS Modules-in-TypeScript” but with scoped CSS Variables + heaps more.
🔥 All styles generated at build time — just like Sass, Less, etc.
✨ Minimal abstraction over standard CSS.
🦄 Works with any front-end framework — or even without one.
🌳 Locally scoped class names — just like CSS Modules.
🚀 Locally scoped CSS Variables, @keyframes and @font-face rules.
🎨 High-level theme system with support for simultaneous themes. No globals!
🛠 Utils for generating variable-based calc expressions.
💪 Type-safe styles via CSSType.
🏃♂️ Optional runtime version for development and testing.
🙈 Optional API for dynamic runtime theming.
🖥 Try it out for yourself in CodeSandbox.
Write your styles in .css.ts files.
// styles.css.ts
import { createTheme, style } from '@vanilla-extract/css';
export const [themeClass, vars] = createTheme({
color: {
brand: 'blue'
},
font: {
body: 'arial'
}
});
export const exampleStyle = style({
backgroundColor: vars.color.brand,
fontFamily: vars.font.body,
color: 'white',
padding: 10
});
💡 These
.css.tsfiles will be evaluated at build time. None of the code in these files will be included in your final bundle. Think of it as using TypeScript as your preprocessor instead of Sass, Less, etc.
Then consume them in your markup.
// app.ts
import { themeClass, exampleStyle } from './styles.css.ts';
document.write(`
<section class="${themeClass}">
<h1 class="${exampleStyle}">Hello world!</h1>
</section>
`);
Want to work at a higher level while maximising style re-use? Check out 🍨 Sprinkles, our official zero-runtime atomic CSS framework, built on top of vanilla-extract.
There are currently a few integrations to choose from.
npm install @vanilla-extract/css @vanilla-extract/babel-plugin @vanilla-extract/webpack-plugin
{
"plugins": ["@vanilla-extract/babel-plugin"]
}
const { VanillaExtractPlugin } = require('@vanilla-extract/webpack-plugin');
module.exports = {
plugins: [new VanillaExtractPlugin()],
};
const { VanillaExtractPlugin } = require('@vanilla-extract/webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
module.exports = {
plugins: [
new VanillaExtractPlugin(),
new MiniCssExtractPlugin()
],
module: {
rules: [
{
test: /\.vanilla\.css$/i, // Targets only CSS files generated by vanilla-extract
use: [
MiniCssExtractPlugin.loader,
{
loader: require.resolve('css-loader'),
options: {
url: false // Required as image imports should be handled via JS/TS import statements
}
}
]
}
]
}
};
npm install @vanilla-extract/css @vanilla-extract/esbuild-plugin
const { vanillaExtractPlugin } = require('@vanilla-extract/esbuild-plugin');
require('esbuild').build({
entryPoints: ['app.ts'],
bundle: true,
plugins: [vanillaExtractPlugin()],
outfile: 'out.js',
}).catch(() => process.exit(1))
Please note: There are currently no automatic readable class names during development. However, you can still manually provide a debug ID as the last argument to functions that generate scoped styles, e.g.
export const className = style({ ... }, 'className');
As esbuild currently doesn't have a way to process the CSS generated by vanilla-extract, you can optionally use the processCss option.
For example, to run autoprefixer over the generated CSS.
const {
vanillaExtractPlugin
} = require('@vanilla-extract/esbuild-plugin');
const postcss = require('postcss');
const autoprefixer = require('autoprefixer');
async function processCss(css) {
const result = await postcss([autoprefixer]).process(
css,
{
from: undefined /* suppress source map warning */
}
);
return result.css;
}
require('esbuild')
.build({
entryPoints: ['app.ts'],
bundle: true,
plugins: [
vanillaExtractPlugin({
processCss
})
],
outfile: 'out.js'
})
.catch(() => process.exit(1));
Warning: Currently the Vite plugin doesn't rebuild files when dependent files change, e.g. updating
theme.css.tsshould rebuildstyles.css.tswhich importstheme.css.ts. This is a limitation in the Vite Plugin API that will hopefully be resolved soon. You can track the Vite issue here: https://github.com/vitejs/vite/issues/3216
npm install @vanilla-extract/css @vanilla-extract/vite-plugin
import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin';
// vite.config.js
export default {
plugins: [vanillaExtractPlugin()]
}
Please note: There are currently no automatic readable class names during development. However, you can still manually provide a debug ID as the last argument to functions that generate scoped styles, e.g.
export const className = style({ ... }, 'className');
npm install @vanilla-extract/css @vanilla-extract/snowpack-plugin
// snowpack.config.json
{
"plugins": ["@vanilla-extract/snowpack-plugin"]
}
Please note: There are currently no automatic readable class names during development. However, you can still manually provide a debug ID as the last argument to functions that generate scoped styles, e.g.
export const className = style({ ... }, 'className');
To add to your Gatsby site, use the gatsby-plugin-vanilla-extract plugin.
$ npm install @vanilla-extract/babel-plugin
{
"plugins": ["@vanilla-extract/babel-plugin"]
}
In testing environments (like jsdom) vanilla-extract will create and insert styles. While this is often desirable, it can be a major slowdown in your tests. If your tests don’t require styles to be available, the disableRuntimeStyles import will disable all style creation.
// setupTests.ts
import '@vanilla-extract/css/disableRuntimeStyles';
🍬 If you're a treat user, check out our migration guide.
Creates styles attached to a locally scoped class name.
import { style } from '@vanilla-extract/css';
export const className = style({
display: 'flex'
});
CSS Variables, simple pseudos, selectors and media/feature queries are all supported.
import { style } from '@vanilla-extract/css';
import { vars } from './vars.css.ts';
export const className = style({
display: 'flex',
vars: {
[vars.localVar]: 'green',
'--global-variable': 'purple'
},
':hover': {
color: 'red'
},
selectors: {
'&:nth-child(2n)': {
background: '#fafafa'
}
},
'@media': {
'screen and (min-width: 768px)': {
padding: 10
}
},
'@supports': {
'(display: grid)': {
display: 'grid'
}
}
});
Selectors can also contain references to other scoped class names.
import { style } from '@vanilla-extract/css';
export const parentClass = style({});
export const childClass = style({
selectors: {
[`${parentClass}:focus &`]: {
background: '#fafafa'
}
},
});
💡 To improve maintainability, each
styleblock can only target a single element. To enforce this, all selectors must target the&character which is a reference to the current element. For example,'&:hover:not(:active)'is considered valid, while'& > a'and[`& ${childClass}`]are not.If you want to target another scoped class then it should be defined within the
styleblock of that class instead. For example,[`& ${childClass}`]is invalid since it targets${childClass}, so it should instead be defined in thestyleblock forchildClass.If you want to globally target child nodes within the current element (e.g.
'& > a'), you should useglobalStyleinstead.
Creates a collection of named style variants.
import { styleVariants } from '@vanilla-extract/css';
export const variant = styleVariants({
primary: { background: 'blue' },
secondary: { background: 'aqua' },
});
💡 This is useful for mapping component props to styles, e.g.
<button className={styles.variant[props.variant]}>
You can also transform the values by providing a map function as the second argument.
import { styleVariants } from '@vanilla-extract/css';
const spaceScale = {
small: 4,
medium: 8,
large: 16
};
export const padding = styleVariants(spaceScale, (space) => ({
padding: space
}));
Creates styles attached to a global selector.
import { globalStyle } from '@vanilla-extract/css';
globalStyle('html, body', {
margin: 0
});
Global selectors can also contain references to other scoped class names.
import { globalStyle } from '@vanilla-extract/css';
export const parentClass = style({});
globalStyle(`${parentClass} > a`, {
color: 'pink'
});
Combines multiple styles into a single class string, while also deduplicating and removing unnecessary spaces.
import { style, composeStyles } from '@vanilla-extract/css';
const button = style({
padding: 12,
borderRadius: 8
});
export const primaryButton = composeStyles(
button,
style({ background: 'coral' })
);
export const secondaryButton = composeStyles(
button,
style({ background: 'peachpuff' })
);
💡 Styles can also be provided in shallow and deeply nested arrays, similar to classnames.
When style compositions are used in selectors, they are assigned an additional class so they can be uniquely identified. When selectors are processed internally, the composed classes are removed, only leaving behind the unique identifier classes. This allows you to treat them as if they were a single class within vanilla-extract selectors.
import {
style,
globalStyle,
composeStyles
} from '@vanilla-extract/css';
const background = style({ background: 'mintcream' });
const padding = style({ padding: 12 });
export const container = composeStyles(background, padding);
globalStyle(`${container} *`, {
boxSizing: 'border-box'
});
Creates a locally scoped theme class and a theme contract which can be consumed within your styles.
// theme.css.ts
import { createTheme } from '@vanilla-extract/css';
export const [themeClass, vars] = createTheme({
color: {
brand: 'blue'
},
font: {
body: 'arial'
}
});
You can create theme variants by passing a theme contract as the first argument to createTheme.
// themes.css.ts
import { createTheme } from '@vanilla-extract/css';
export const [themeA, vars] = createTheme({
color: {
brand: 'blue'
},
font: {
body: 'arial'
}
});
export const themeB = createTheme(vars, {
color: {
brand: 'pink'
},
font: {
body: 'comic sans ms'
}
});
💡 All theme variants must provide a value for every variable or it’s a type error.
Creates a theme attached to a global selector, but with locally scoped variable names.
// theme.css.ts
import { createGlobalTheme } from '@vanilla-extract/css';
export const vars = createGlobalTheme(':root', {
color: {
brand: 'blue'
},
font: {
body: 'arial'
}
});
💡 All theme variants must provide a value for every variable or it’s a type error.
Creates a contract for themes to implement.
Ensure this function is called within a .css.ts context, otherwise variable names will be mismatched between themes.
💡 This is useful if you want to split your themes into different bundles. In this case, your themes would be defined in separate files, but we'll keep this example simple.
// themes.css.ts
import {
createThemeContract,
createTheme
} from '@vanilla-extract/css';
export const vars = createThemeContract({
color: {
brand: null
},
font: {
body: null
}
});
export const themeA = createTheme(vars, {
color: {
brand: 'blue'
},
font: {
body: 'arial'
}
});
export const themeB = createTheme(vars, {
color: {
brand: 'pink'
},
font: {
body: 'comic sans ms'
}
});
Assigns a collection of CSS Variables anywhere within a style block.
💡 This is useful for creating responsive themes since it can be used within
@mediablocks.
import { createThemeContract, style, assignVars } from '@vanilla-extract/css';
export const vars = createThemeContract({
space: {
small: null,
medium: null,
large: null
}
});
export const responsiveSpaceTheme = style({
vars: assignVars(vars.space, {
small: '4px',
medium: '8px',
large: '16px'
}),
'@media': {
'screen and (min-width: 1024px)': {
vars: assignVars(vars.space, {
small: '8px',
medium: '16px',
large: '32px'
})
}
}
});
💡 All variables passed into this function must be assigned or it’s a type error.
Creates a single CSS Variable.
import { createVar, style } from '@vanilla-extract/css';
export const colorVar = createVar();
export const exampleStyle = style({
color: colorVar
});
Scoped variables can be set via the vars property on style objects.
import { createVar, style } from '@vanilla-extract/css';
import { colorVar } from './vars.css.ts';
export const parentStyle = style({
vars: {
[colorVar]: 'blue'
}
});
Provides fallback values when consuming variables.
import { createVar, fallbackVar, style } from '@vanilla-extract/css';
export const colorVar = createVar();
export const exampleStyle = style({
color: fallbackVar(colorVar, 'blue');
});
Multiple fallbacks are also supported.
import { createVar, fallbackVar, style } from '@vanilla-extract/css';
export const primaryColorVar = createVar();
export const secondaryColorVar = createVar();
export const exampleStyle = style({
color: fallbackVar(primaryColorVar, secondaryColorVar, 'blue');
});
Creates a custom font attached to a locally scoped font name.
import { fontFace, style } from '@vanilla-extract/css';
const myFont = fontFace({
src: 'local("Comic Sans MS")'
});
export const text = style({
fontFamily: myFont
});
Creates a globally scoped custom font.
import {
globalFontFace,
style
} from '@vanilla-extract/css';
globalFontFace('MyGlobalFont', {
src: 'local("Comic Sans MS")'
});
export const text = style({
fontFamily: 'MyGlobalFont'
});
Creates a locally scoped set of keyframes.
import { keyframes, style } from '@vanilla-extract/css';
const rotate = keyframes({
'0%': { rotate: '0deg' },
'100%': { rotate: '360deg' },
});
export const animated = style({
animation: `3s infinite ${rotate}`,
});
Creates a globally scoped set of keyframes.
import { globalKeyframes, style } from '@vanilla-extract/css';
globalKeyframes('rotate', {
'0%': { rotate: '0deg' },
'100%': { rotate: '360deg' },
});
export const animated = style({
animation: `3s infinite rotate`,
});
We also provide a lightweight standalone package to support dynamic runtime theming.
npm install @vanilla-extract/dynamic
Assigns CSS Variables as inline styles.
// app.tsx
import { assignInlineVars } from '@vanilla-extract/dynamic';
import { vars } from './vars.css.ts';
const MyComponent = () => (
<section
style={assignInlineVars({
[vars.colors.brand]: 'pink',
[vars.colors.accent]: 'green'
})}
>
...
</section>
);
You can also assign collections of variables by passing a theme contract as the first argument. All variables must be assigned or it’s a type error.
// app.tsx
import { assignInlineVars } from '@vanilla-extract/dynamic';
import { vars } from './vars.css.ts';
const MyComponent = () => (
<section
style={assignInlineVars(vars.colors, {
brand: 'pink',
accent: 'green'
})}
>
...
</section>
);
Even though this function returns an object of inline styles, its toString method returns a valid style attribute value so that it can be used in string templates.
// app.ts
import { assignInlineVars } from '@vanilla-extract/dynamic';
import { vars } from './vars.css.ts';
document.write(`
<section style="${assignInlineVars({
[vars.colors.brand]: 'pink',
[vars.colors.accent]: 'green'
})}">
...
</section>
`);
Sets CSS Variables on a DOM element.
// app.ts
import { setElementVars } from '@vanilla-extract/dynamic';
import { vars } from './styles.css.ts';
const el = document.getElementById('myElement');
setElementVars(el, {
[vars.colors.brand]: 'pink',
[vars.colors.accent]: 'green'
});
You can also set collections of variables by passing a theme contract as the second argument. All variables must be set or it’s a type error.
// app.ts
import { setElementVars } from '@vanilla-extract/dynamic';
import { vars } from './styles.css.ts';
const el = document.getElementById('myElement');
setElementVars(el, vars.colors, {
brand: 'pink',
accent: 'green'
});
We also provide a standalone package of optional utility functions to make it easier to work with CSS in TypeScript.
💡 This package can be used with any CSS-in-JS library.
npm install @vanilla-extract/css-utils
Streamlines the creation of CSS calc expressions.
import { calc } from '@vanilla-extract/css-utils';
const styles = {
height: calc.multiply('var(--grid-unit)', 2)
};
The following functions are available.
calc.addcalc.subtractcalc.multiplycalc.dividecalc.negateThe calc export is also a function, providing a chainable API for complex calc expressions.
import { calc } from '@vanilla-extract/css-utils';
const styles = {
marginTop: calc('var(--space-large)')
.divide(2)
.negate()
.toString()
};
MIT.
FAQs
Zero-runtime Stylesheets-in-TypeScript
The npm package @vanilla-extract/dynamic receives a total of 160,439 weekly downloads. As such, @vanilla-extract/dynamic popularity was classified as popular.
We found that @vanilla-extract/dynamic demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.