Next, add styled-jsx/babel to plugins in your babel configuration:
{ "plugins": ["styled-jsx/babel"]}
Now add <style jsx> to your code and fill it with CSS:
export default () => ( <div> <p>only this paragraph will get the style :)</p> {/* you can include <Component />s here that include other <p>s that don't get unexpected styles! */} <style jsx>{` p { color: red; } `}</style> </div>)
Configuration options
The following are optional settings for the babel plugin.
optimizeForSpeed
Blazing fast and optimized CSS rules injection system based on the CSSOM APIs.
When in production* this mode is automatically enabled.
Beware that when using this option source maps cannot be generated and styles cannot be edited via the devtools.
* process.env.NODE_ENV === 'production'
sourceMaps
Generates source maps (default: false)
styleModule
Module that the transpiled files should import (default: styled-jsx/style)
Very fast, minimal and efficient transpilation (see below)
High-performance runtime-CSS-injection when not server-rendering
Future-proof: Equivalent to server-renderable "Shadow CSS"
Source maps support
Dynamic styles and themes support
CSS Preprocessing via Plugins
Using in Next.js
Next.js automatically configures styled-jsx with babel or swc, you don't have to configure it manually.
How It Works
The example above transpiles to the following:
import _JSXStyle from 'styled-jsx/style'export default () => ( <div className="jsx-123"> <p className="jsx-123">only this paragraph will get the style :)</p> <_JSXStyle id="123">{`p.jsx-123 {color: red;}`}</_JSXStyle> </div>)
Why It Works Like This
Unique classnames give us style encapsulation and _JSXStyle is heavily optimized for:
Injecting styles upon render
Only injecting a certain component's style once (even if the component is included multiple times)
Removing unused styles
Keeping track of styles for server-side rendering
Targeting The Root
Notice that the outer <div> from the example above also gets a jsx-123 classname. We do this so that
you can target the "root" element, in the same manner that
:host works with Shadow DOM.
If you want to target only the host, we suggest you use a class:
The advantage of using this over <style> is twofold: no need
to use dangerouslySetInnerHTML to avoid escaping issues with CSS
and take advantage of styled-jsx's de-duping system to avoid
the global styles being inserted multiple times.
One-off global selectors
Sometimes it's useful to skip selectors scoping. In order to get a one-off global selector we support :global(), inspired by css-modules.
This is very useful in order to, for example, generate a global class that
you can pass to 3rd-party components. For example, to style
react-select which supports passing a custom class via optionClassName:
import Select from 'react-select'export default () => ( <div> <Select optionClassName="react-select" /> <style jsx>{` /* "div" will be prefixed, but ".react-select" won't */ div :global(.react-select) { color: red; } `}</style> </div>)
Dynamic styles
To make a component's visual representation customizable from the outside world there are three options.
Via interpolated dynamic props
Any value that comes from the component's render method scope is treated as dynamic. This makes it possible to use props and state for example.
New styles' injection is optimized to perform well at runtime.
That said when your CSS is mostly static we recommend to split it up in static and dynamic styles and use two separate style tags so that, when changing, only the dynamic parts are recomputed/rendered.
Please keep in mind that constants defined outside of the component scope are treated as static styles.
Server-Side Rendering
styled-jsx v5 introduced StyledRegistry component and useStyleRegistry hook to let you scope styles rendering in each SSR render to keep concurrent-safe.
registry.styles() will return the array of react components for style tags.
registry.flush() can clean the existing styles in the registry, it's optional for SSR when you have a standalone registry for each SSR render.
Next.js 12 integrates with styled-jsx v5 and manages the registry for you.
There's also a new API createStyleRegistry that is introduced when you have to create a registry manually. In this way you can operate the registry yourself to extract the rendered styles (registry.styles()) or flush them out (registry.flush()).
By default <StyleRegistry /> will use the registry from root top StyleRegistry, which means there's only one registry in the react tree.
It's paramount that you use one of these two functions so that
the generated styles can be diffed when the client loads and
duplicate styles are avoided.
import nanoid from 'nanoid'const nonce = Buffer.from(nanoid()).toString('base64') //ex: N2M0MDhkN2EtMmRkYi00MTExLWFhM2YtNDhkNTc4NGJhMjA3
You must then pass a nonce to registry.styles({ nonce })and set a <meta property="csp-nonce" content={nonce} /> tag.
Your CSP policy must share the same nonce as well (the header nonce needs to match the html nonce and remain unpredictable).
Content-Security-Policy: default-src 'self'; style-src 'self' 'nonce-N2M0MDhkN2EtMmRkYi00MTExLWFhM2YtNDhkNTc4NGJhMjA3';
External CSS and styles outside of the component
In styled-jsx styles can be defined outside of the component's render method or in separate JavaScript modules using the styled-jsx/css library. styled-jsx/css exports three tags that can be used to tag your styles:
css, the default export, to define scoped styles.
css.global to define global styles.
css.resolve to define scoped styles that resolve to the scoped className and a styles element.
External styles
In an external file:
/* styles.js */import css from 'styled-jsx/css'// Scoped stylesexport const button = css` button { color: hotpink; }`// Global stylesexport const body = css.global`body { margin: 0; }`// Resolved stylesexport const link = css.resolve`a { color: green; }`// link.className -> scoped className to apply to `a` elements e.g. jsx-123// link.styles -> styles element to render inside of your component// Works also with default exportsexport default css` div { color: green; }`
N.B. All the tags except for resolve don't support dynamic styles.
resolve and global can also be imported individually:
import { resolve } from 'styled-jsx/css'import { global } from 'styled-jsx/css'
If you use Prettier we recommend you to use the default css export syntax since the tool doesn't support named imports.
Styles outside of components
The css tag from styled-jsx/css can be also used to define styles in your components files but outside of the component itself. This might help with keeping render methods smaller.
Like in externals styles css doesn't work with dynamic styles. If you have dynamic parts you might want to place them inline inside of your component using a regular <style jsx> element.
The resolve tag
The resolve tag from styled-jsx/css can be used when you need to scope some CSS - for example, if you need to style nested components from the parent, such as the Link component in the example below.
It works by returning the generated scoped className and related styles.
import React from 'react'import Link from 'some-library'import css from 'styled-jsx/css'const { className, styles } = css.resolve` a { color: green }`export default () => ( <div> {/* use the className */} <Link className={className}>About</Link> {/* render the styles for it */} {styles} </div>)
The resolve tag also supports dynamic styles, via template string interpolation:
If you can't (or would rather not) make changes to your .babelrc, the resolve tag can be used as a Babel macro, thanks to the babel-plugin-macros system.
To set this up, first of all, install styled-jsx and babel-plugin-macros:
npm i --save styled-jsxnpm i --save-dev babel-plugin-macros
Next, add babel-plugin-macros to your Babel configuration:
{ "plugins": ["babel-plugin-macros"]}
You can then use resolve by importing it from styled-jsx/macro.
import css from 'styled-jsx/macro'const { className, styles } = css.resolve` a { color: green }`export default () => ( <div> <Link className={className}>About</Link> {styles} </div>)
To consume the styles in your component you can import them from your CSS file and render them using a <style jsx> tag. Remember to add the global prop if you want your styles to be global.
To use this feature you need to register the loader in your webpack config file, before babel-loader which will then transpile the styles via styled-jsx/babel
The plugin accepts a type option to configure whether the styles should be scoped, global or resolve (see above). By default its values is set to scoped. type can also be a function which takes the fileName and the fileNameQuery that is being transpiled and must return a valid type.
Plugins are regular JavaScript modules that export a simple function with the following signature:
function plugin(css: string, options: Object): string
Basically they accept a CSS string in input, optionally modify it and finally return it.
Plugins make it possible to use popular preprocessors like SASS, Less, Stylus, PostCSS or apply custom transformations to the styles at compile time.
To register a plugin add an option plugins for styled-jsx/babel to your .babelrc. plugins must be an array of module names or full paths for local plugins.
This is a fairly new feature so make sure that you using a version of Next.js that supports passing options to styled-jsx.
Plugins are applied in definition order left to right before styles are scoped.
In order to resolve local plugins paths you can use NodeJS' require.resolve.
N.B. when applying the plugins styled-jsx replaces template literals expressions with placeholders because otherwise CSS parsers would get invalid CSS E.g.
/* `ExprNumber` is a number */%%styled-jsx-placeholder-ExprNumber%%
When publishing a plugin you may want to add the keywords: styled-jsx and styled-jsx-plugin.
We also encourage you to use the following naming convention for your plugins:
styled-jsx-plugin-<your-plugin-name>
Plugin options
Users can set plugin options by registering a plugin as an array that contains
the plugin path and an options object.
Each plugin receives a options object as second argument which contains
the babel and user options:
;(css, options) => { /* ... */}
The options object has the following shape:
{ // user options go here // eg. exampleOption: true // babel options babel: { sourceMaps: boolean, vendorPrefixes: boolean, isGlobal: boolean, filename: ?string, // defined only when the filename option is passed to Babel, such as when using Babel CLI or Webpack location: { // the original location of the CSS block in the JavaScript file start: { line: number, column: number, }, end: { line: number, column: number, } } }}
Example plugins
The following plugins are proof of concepts/sample:
If you're using a tool such as Enzyme, you might want to avoid compiling your styles in test renders. In general, styled-jsx artifacts like jsx-123 classnames and vendor prefixing are not direct concerns of your component, and they generate a lot of snapshot noise.
One option is to exclude the styled-jsx/babel plugin from the test environment using env in your Babel config (see Config Merging options).
But this can cause noise in your terminal output when rendering:
console.error node_modules/react-dom/cjs/react-dom.development.js:527 Warning: Received `true` for a non-boolean attribute `jsx`.
The styled-jsx/babel-test solves this problem. It simply strips jsx attributes from all <style> tags. Be sure to target each environment with the appropriate plugin:
Styling third parties / child components from the parent
When the component accepts a className (or ad-hoc) prop as a way to allow customizations then you can use the resolve tag from styled-jsx/css.
When the component doesn't accept any className or doesn't expose any API to customize the component, then your only option is to use :global() styles:
export default () => ( <div> <ExternalComponent /> <style jsx>{` /* "div" will be prefixed, but ".nested-element" won't */ div > :global(.nested-element) { color: red; } `}</style> </div>)
Please keep in mind that :global() styles will affect the entire subtree, so in many cases you may want to be careful and use the children (direct descendant) selector >.
Build a component library with styled-jsx
There's an article explaining how to bundle React components with Rollup and styled-jsx as an external dependency.
Syntax Highlighting
When working with template literals a common drawback is missing syntax highlighting. The following editors currently have support for highlighting CSS inside <style jsx> elements.
If you have a solution for an editor not on the listplease open a PRand let us now.
After installing the package add the code below to the appropriate settings entry. In a few moments you should be blessed with proper CSS syntax highlighting. (source)
The IDE let you inject any language in place with Inject language or reference in an Intention Actions (default alt+enter).
Simply perform the action in the string template and select CSS.
You get full CSS highlighting and autocompletion and it will last until you close the IDE.
Additionally you can use language injection comments to enable all the IDE language features indefinitely using the language comment style:
If you're using Emmet you can add the following snippet to ~/emmet/snippets-styledjsx.json This will allow you to expand style-jsx to a styled-jsx block.
Install vim-styled-jsx with your plugin manager of choice.
ESLint
If you're using eslint-plugin-import, the css import will generate errors, being that it's a "magic" import (not listed in package.json). To avoid these, simply add the following line to your eslint configuration:
If you're using TypeScript, then in order to allow <style jsx> tags to be properly understood by it, create a file named "styled-jsx.d.ts" anywhere within your project containing the following, or add this line to the top of any single existing .ts file within your project:
/// <reference types="styled-jsx" />
If you're using babel to transform styled-jsx code with TypeScript, you need to specify "jsx": "preserve" in your tsconfig.json to keep the original JSX and let babel parse and transform with styled-jsx babel plugin.
Credits
Pedram Emrouznejad (rijs) suggested attribute selectors over my initial class prefixing idea.
Sunil Pai (glamor) inspired the use of murmurhash2 (minimal and fast hashing) and an efficient style injection logic.
Sultan Tarimo built stylis.js, a super fast and tiny CSS parser and compiler.
Max Stoiber (styled-components) proved the value of retaining the familiarity of CSS syntax and pointed me to the very efficient stylis compiler (which we forked to very efficiently append attribute selectors to the user's css)
Yehuda Katz (ember) convinced me on Twitter to transpile CSS as an alternative to CSS-in-JS.
Evan You (vuejs) discussed his Vue.js CSS transformation with me.
Henry Zhu (babel) helpfully pointed me to some important areas of the babel plugin API.