styled-jsx
Advanced tools
The styled-jsx npm package is a CSS-in-JS library that allows you to write encapsulated and scoped CSS to style your components in a React application. It is specifically designed to work with React and Next.js and provides a way to include styles directly within JavaScript or TypeScript files.
Scoped Styles
This feature allows you to write CSS that is scoped to a component. The styles will not leak to other parts of the application.
<style jsx>{`p { color: red; }`}</style>Global Styles
With styled-jsx, you can also define global styles that apply to the entire application, not just scoped to a single component.
<style jsx global>{`body { background: black; }`}</style>Dynamic Styles
styled-jsx supports dynamic styles, allowing you to use JavaScript variables and expressions to determine the styles at runtime.
`<style jsx>{
`p { color: ${color}; }`
}</style>`Preprocessing
You can use preprocessors with styled-jsx to include external stylesheets or use features like nesting or variables.
<style jsx>{`
@import 'styles/shared.css';
p { color: red; }
`}</style>styled-components is another CSS-in-JS library that allows you to use template literals to write actual CSS code in your JavaScript files. It also handles scoping and supports dynamic styling. It differs from styled-jsx in its API and the way styles are applied to components.
Emotion is a performant and flexible CSS-in-JS library. It allows you to style applications quickly with string or object styles. It has a similar API to styled-components and includes features like composition, theming, and server-side rendering.
Linaria is a zero-runtime CSS-in-JS library that extracts CSS to separate files during the build process, rather than including styles in the JavaScript bundle. This can result in better performance compared to styled-jsx, which includes styles in the JS bundle.
Full, scoped and component-friendly CSS support for JSX (rendered on the server or the client).
Code and docs are for v2 which we highly recommend you to try. Looking for styled-jsx v1? Switch to the v1 branch.
For an overview about the features and tradeoffs of styled-jsx you may want to take a look at this presentation.
Firstly, install the package:
npm install --save styled-jsx
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>
)
The following are optional settings for the babel plugin.
optimizeForSpeedBlazing fast and optimized CSS rules injection system based on the CSSOM APIs.
{
"plugins": [
["styled-jsx/babel", { "optimizeForSpeed": true }]
]
}
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'
sourceMapsGenerates source maps (default: false)
vendorPrefixesTurn on/off automatic vendor prefixing (default: true)
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 styleId='123' css={`p.jsx-123 {color: red;}`} />
</div>
)
Unique classnames give us style encapsulation and _JSXStyle is heavily optimized for:
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:
export default () => (
<div className="root">
<style jsx>{`
.root {
color: green;
}
`}</style>
</div>
)
Styles can be defined in separate JavaScript modules by tagging with css any template literal that contain CSS.
css must be imported from styled-jsx/css:
/* styles.js */
import css from 'styled-jsx/css'
export const button = css`button { color: hotpink; }`
export default css`div { color: green; }`
imported as regular strings:
import styles, { button } from './styles'
export default () => (
<div>
<button>styled-jsx</button>
<style jsx>{styles}</style>
<style jsx>{button}</style>
</div>
)
Styles are automatically scoped but you can also be consumed as globals.
N.B. Dynamic styles cannot be used in external styles.
We also support CommonJS exports but you can only export one string per module:
module.exports = css`div { color: green; }`
// the following won't work
// module.exports = { styles: css`div { color: green; }` }
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.
import css from 'styled-jsx/css'
export default () => (
<div>
<button>styled-jsx</button>
<style jsx>{button}</style>
</div>
)
const button = css`button { color: hotpink; }`
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.
To skip scoping entirely, you can make the global-ness of your styles explicit by adding global.
export default () => (
<div>
<style jsx global>{`
body {
background: red
}
`}</style>
</div>
)
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.
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>
)
To make a component's visual representation customizable from the outside world there are three options.
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.
const Button = (props) => (
<button>
{ props.children }
<style jsx>{`
button {
padding: ${ 'large' in props ? '50' : '20' }px;
background: ${props.theme.background};
color: #999;
display: inline-block;
font-size: 1em;
}
`}</style>
</button>
)
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.
const Button = (props) => (
<button>
{ props.children }
<style jsx>{`
button {
color: #999;
display: inline-block;
font-size: 2em;
}
`}</style>
<style jsx>{`
button {
padding: ${ 'large' in props ? '50' : '20' }px;
background: ${props.theme.background};
}
`}</style>
</button>
)
className togglingThe second option is to pass properties that toggle class names.
const Button = (props) => (
<button className={ 'large' in props && 'large' }>
{ props.children }
<style jsx>{`
button {
padding: 20px;
background: #eee;
color: #999
}
.large {
padding: 50px
}
`}</style>
</button>
)
Then you would use this component as either <Button>Hi</Button> or <Button large>Big</Button>.
style*best for animations
Imagine that you wanted to make the padding in the button above completely customizable. You can override the CSS you configure via inline-styles:
const Button = ({ padding, children }) => (
<button style={{ padding }}>
{ children }
<style jsx>{`
button {
padding: 20px;
background: #eee;
color: #999
}
`}</style>
</button>
)
In this example, the padding defaults to the one set in <style> (20), but the user can pass a custom one via <Button padding={30}>.
It is possible to use constants like so:
import { colors, spacing } from '../theme'
import { invertColor } from '../theme/utils'
const Button = ({ children }) => (
<button>
{ children }
<style jsx>{`
button {
padding: ${ spacing.medium };
background: ${ colors.primary };
color: ${ invertColor(colors.primary) };
}
`}</style>
</button>
)
Please keep in mind that constants defined outside of the component scope are treated as static styles.
styled-jsx/serverThe main export flushes your styles to an array of React.Element:
import React from 'react'
import ReactDOM from 'react-dom/server'
import flush from 'styled-jsx/server'
import App from './app'
export default (req, res) => {
const app = ReactDOM.renderToString(<App />)
const styles = flush()
const html = ReactDOM.renderToStaticMarkup(<html>
<head>{ styles }</head>
<body>
<div id="root" dangerouslySetInnerHTML={{__html: app}} />
</body>
</html>)
res.end('<!doctype html>' + html)
}
We also expose flushToHTML to return generated HTML:
import React from 'react'
import ReactDOM from 'react-dom/server'
import { flushToHTML } from 'styled-jsx/server'
import App from './app'
export default (req, res) => {
const app = ReactDOM.renderToString(<App />)
const styles = flushToHTML()
const html = `<!doctype html>
<html>
<head>${styles}</head>
<body>
<div id="root">${app}</div>
</body>
</html>`
res.end(html)
}
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.
Styles can be preprocessed via plugins.
Plugins are regular JavaScript modules that export a simple function with the following signature:
(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.
{
"plugins": [
[
"styled-jsx/babel",
{ "plugins": ["my-styled-jsx-plugin-package", "/full/path/to/local/plugin"] }
]
]
}
{
"presets": [
[
"next/babel",
{
"styled-jsx": {
"plugins": [
"styled-jsx-plugin-postcss"
]
}
}
]
]
}
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%%
Plugins won't transform expressions (eg. dynamic styles).
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>
Users can set plugin options by registering a plugin as an array that contains the plugin path and an options object.
{
"plugins": [
[
"styled-jsx/babel",
{
"plugins": [
["my-styled-jsx-plugin-package", { "exampleOption": true }]
],
"sourceMaps": true
}
]
]
}
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,
}
}
}
}
The following plugins are proof of concepts/sample:
jsx prop on <style> tagIf you get this warning it means that your styles were not compiled by styled-jsx.
Please take a look at your setup and make sure that everything is correct and that the styled-jsx transformation is ran by Babel.
No, this feature is not supported. However we support React Fragments, which are available in React 16.2.0 and above.
const StyledImage = ({ src, alt = '' }) => (
<React.Fragment>
<img src={src} alt={alt} />
<style jsx>{`img { max-width: 100% }`}</style>
</React.Fragment>
)
When the component accepts a className (or ad-hoc) prop that you can use to style those components then you can generate scoped styles locally in the parent component and resolve them to get a className and the actual scoped styles like so:
import Link from 'react-router-dom' // component to style
// Generate a `scope` fragment and resolve it
const scoped = resolveScopedStyles(
<scope>
<style jsx>{'.link { color: green }'}</style>
</scope>
)
// Your component that uses Link
export default ({ children }) => (
<div>
{children}
{/* use the scoped className */}
<Link to="/about" className={`link ${scoped.className}`}>
About
</Link>
{/* apply the scoped styles */}
{scoped.styles}
</div>
)
resolveScopedStyles looks like this:
function resolveScopedStyles(scope) {
return {
className: scope.props.className,
styles: scope.props.children
}
}
When the component doesn't accept any className or doesn't expose any API to customize the component, then you 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 >.
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 list please open a PR and let us now.
The language-babel package for the Atom editor has an option to extend the grammar for JavaScript tagged template literals.
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)
"(?<=<style jsx>{)|(?<=<style jsx global>{)":source.css.styled
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:
import { colors, spacing } from '../theme'
import { invertColor } from '../theme/utils'
const Button = ({ children }) => (
<button>
{ children }
{ /*language=CSS*/ }
<style jsx>{`
button {
padding: ${ spacing.medium };
background: ${ colors.primary };
color: ${ invertColor(colors.primary) };
}
`}</style>
</button>
)
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.
{
"html": {
"snippets": {
"style-jsx": "<style jsx>{`\n\t$1\n`}</style>"
}
}
}
Launch VS Code Quick Open (⌘+P), paste the following command, and press enter.
ext install vscode-styled-jsx
Launch VS Code Quick Open (⌘+P), paste the following command, and press enter.
ext install vscode-styled-jsx-languageserver
Install vim-styled-jsx with your plugin manager of choice.
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:
"settings": {"import/core-modules": ["styled-jsx/css"] }
murmurhash2 (minimal and fast hashing) and an efficient style injection logic.FAQs
Full CSS support for JSX without compromises
The npm package styled-jsx receives a total of 8,144,930 weekly downloads. As such, styled-jsx popularity was classified as popular.
We found that styled-jsx demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 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.
Research
Socket uncovered npm malware campaign mimicking popular Node.js libraries and packages from other ecosystems; packages steal data and execute remote code.
Research
Socket's research uncovers three dangerous Go modules that contain obfuscated disk-wiping malware, threatening complete data loss.
Research
Socket uncovers malicious packages on PyPI using Gmail's SMTP protocol for command and control (C2) to exfiltrate data and execute commands.