Gathering detailed insights and metrics for styled-jsx
Gathering detailed insights and metrics for styled-jsx
Gathering detailed insights and metrics for styled-jsx
Gathering detailed insights and metrics for styled-jsx
npm install styled-jsx
89.4
Supply Chain
98.5
Quality
82.6
Maintenance
100
Vulnerability
100
License
Module System
Unable to determine the module system for this package.
Min. Node Version
Typescript Support
Node Version
NPM Version
7,725 Stars
411 Commits
261 Forks
99 Watching
7 Branches
141 Contributors
Updated on 26 Nov 2024
Minified
Minified + Gzipped
JavaScript (99.97%)
TypeScript (0.03%)
Cumulative downloads
Total Downloads
Last day
-4.9%
1,288,791
Compared to previous day
Last week
3.9%
7,507,869
Compared to previous week
Last month
9.3%
31,377,712
Compared to previous month
Last year
36.7%
296,785,058
Compared to previous year
1
1
31
Full, scoped and component-friendly CSS support for JSX (rendered on the server or the client).
Code and docs are for v3 which we highly recommend you to try. Looking for styled-jsx v2? Switch to the v2 branch.
Firstly, install the package:
1npm install --save styled-jsx
Next, add styled-jsx/babel
to plugins
in your babel configuration:
1{ 2 "plugins": ["styled-jsx/babel"] 3}
Now add <style jsx>
to your code and fill it with CSS:
1export default () => ( 2 <div> 3 <p>only this paragraph will get the style :)</p> 4 5 {/* you can include <Component />s here that include 6 other <p>s that don't get unexpected styles! */} 7 8 <style jsx>{` 9 p { 10 color: red; 11 } 12 `}</style> 13 </div> 14)
The following are optional settings for the babel plugin.
optimizeForSpeed
Blazing fast and optimized CSS rules injection system based on the CSSOM APIs.
1{ 2 "plugins": [["styled-jsx/babel", { "optimizeForSpeed": true }]] 3}
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
)
vendorPrefixes
Turn on/off automatic vendor prefixing (default: true
)
Next.js automatically configures styled-jsx
with babel or swc, you don't have to configure it manually.
The example above transpiles to the following:
1import _JSXStyle from 'styled-jsx/style' 2 3export default () => ( 4 <div className="jsx-123"> 5 <p className="jsx-123">only this paragraph will get the style :)</p> 6 <_JSXStyle id="123">{`p.jsx-123 {color: red;}`}</_JSXStyle> 7 </div> 8)
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:
1export default () => ( 2 <div className="root"> 3 <style jsx>{` 4 .root { 5 color: green; 6 } 7 `}</style> 8 </div> 9)
To skip scoping entirely, you can make the global-ness of your styles explicit by adding global.
1export default () => ( 2 <div> 3 <style jsx global>{` 4 body { 5 background: red; 6 } 7 `}</style> 8 </div> 9)
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
:
1import Select from 'react-select' 2export default () => ( 3 <div> 4 <Select optionClassName="react-select" /> 5 6 <style jsx>{` 7 /* "div" will be prefixed, but ".react-select" won't */ 8 9 div :global(.react-select) { 10 color: red; 11 } 12 `}</style> 13 </div> 14)
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.
1const Button = props => ( 2 <button> 3 {props.children} 4 <style jsx>{` 5 button { 6 padding: ${'large' in props ? '50' : '20'}px; 7 background: ${props.theme.background}; 8 color: #999; 9 display: inline-block; 10 font-size: 1em; 11 } 12 `}</style> 13 </button> 14)
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.
1const Button = props => ( 2 <button> 3 {props.children} 4 <style jsx>{` 5 button { 6 color: #999; 7 display: inline-block; 8 font-size: 2em; 9 } 10 `}</style> 11 <style jsx>{` 12 button { 13 padding: ${'large' in props ? '50' : '20'}px; 14 background: ${props.theme.background}; 15 } 16 `}</style> 17 </button> 18)
className
togglingThe second option is to pass properties that toggle class names.
1const Button = props => ( 2 <button className={'large' in props && 'large'}> 3 {props.children} 4 <style jsx>{` 5 button { 6 padding: 20px; 7 background: #eee; 8 color: #999; 9 } 10 .large { 11 padding: 50px; 12 } 13 `}</style> 14 </button> 15)
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:
1const Button = ({ padding, children }) => ( 2 <button style={{ padding }}> 3 {children} 4 <style jsx>{` 5 button { 6 padding: 20px; 7 background: #eee; 8 color: #999; 9 } 10 `}</style> 11 </button> 12)
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:
1import { colors, spacing } from '../theme' 2import { invertColor } from '../theme/utils' 3 4const Button = ({ children }) => ( 5 <button> 6 {children} 7 <style jsx>{` 8 button { 9 padding: ${spacing.medium}; 10 background: ${colors.primary}; 11 color: ${invertColor(colors.primary)}; 12 } 13 `}</style> 14 </button> 15)
Please keep in mind that constants defined outside of the component scope are treated as static styles.
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.
1import React from 'react' 2import ReactDOM from 'react-dom/server' 3import { StyleRegistry, useStyleRegistry } from 'styled-jsx' 4import App from './app' 5 6function Styles() { 7 const registry = useStyleRegistry() 8 const styles = registry.styles() 9 return <>{styles}</> 10} 11 12export default (req, res) => { 13 const app = ReactDOM.renderToString(<App />) 14 const html = ReactDOM.renderToStaticMarkup( 15 <StyleRegistry> 16 <html> 17 <head> 18 <Styles /> 19 </head> 20 <body> 21 <div id="root" dangerouslySetInnerHTML={{ __html: app }} /> 22 </body> 23 </html> 24 </StyleRegistry> 25 ) 26 res.end('<!doctype html>' + html) 27}
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()
).
1const registry = createStyleRegistry() 2const styles = registry.styles() // access styles 3 4function Page() { 5 return ( 6 <StyleRegistry registry={registry}> 7 <App /> 8 </StyleRegistry> 9 ) 10}
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.
Strict CSP is supported.
You should generate a nonce per request.
1import nanoid from 'nanoid' 2 3const 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';
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.In an external file:
1/* styles.js */ 2import css from 'styled-jsx/css' 3 4// Scoped styles 5export const button = css` 6 button { 7 color: hotpink; 8 } 9` 10 11// Global styles 12export const body = css.global`body { margin: 0; }` 13 14// Resolved styles 15export const link = css.resolve`a { color: green; }` 16// link.className -> scoped className to apply to `a` elements e.g. jsx-123 17// link.styles -> styles element to render inside of your component 18 19// Works also with default exports 20export default css` 21 div { 22 color: green; 23 } 24`
You can then import and use those styles:
1import styles, { button, body } from './styles' 2 3export default () => ( 4 <div> 5 <button>styled-jsx</button> 6 <style jsx>{styles}</style> 7 <style jsx>{button}</style> 8 <style jsx global> 9 {body} 10 </style> 11 </div> 12)
N.B. All the tags except for resolve
don't support dynamic styles.
resolve
and global
can also be imported individually:
1import { resolve } from 'styled-jsx/css' 2import { 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.
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.
1import css from 'styled-jsx/css' 2 3export default () => ( 4 <div> 5 <button>styled-jsx</button> 6 <style jsx>{button}</style> 7 </div> 8) 9 10const button = css` 11 button { 12 color: hotpink; 13 } 14`
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.
resolve
tagThe 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
.
1import React from 'react' 2import Link from 'some-library' 3 4import css from 'styled-jsx/css' 5 6const { className, styles } = css.resolve` 7 a { color: green } 8` 9 10export default () => ( 11 <div> 12 {/* use the className */} 13 <Link className={className}>About</Link> 14 15 {/* render the styles for it */} 16 {styles} 17 </div> 18)
The resolve
tag also supports dynamic styles, via template string interpolation:
1import React from 'react' 2import css from 'styled-jsx/css' 3 4function getLinkStyles(color) { 5 return css.resolve` 6 a { color: ${color} } 7 ` 8} 9 10export default props => { 11 const { className, styles } = getLinkStyles(props.theme.color) 12 13 return ( 14 <div> 15 <Link className={className}>About</Link> 16 {styles} 17 </div> 18 ) 19}
resolve
as a Babel macroIf 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
:
1npm i --save styled-jsx 2npm i --save-dev babel-plugin-macros
Next, add babel-plugin-macros
to your Babel configuration:
1{ 2 "plugins": ["babel-plugin-macros"] 3}
You can then use resolve
by importing it from styled-jsx/macro
.
1import css from 'styled-jsx/macro' 2 3const { className, styles } = css.resolve` 4 a { color: green } 5` 6 7export default () => ( 8 <div> 9 <Link className={className}>About</Link> 10 {styles} 11 </div> 12)
create-react-app
Create React App comes with babel-plugin-macros
already installed, so the only thing that needs to be done is to install styled-jsx
:
1npm i --save styled-jsx
Then resolve
can be imported from styled-jsx/macro
and used the same way as in the example in the Using resolve
as a Babel macro section above.
styled-jsx v3 comes with a webpack loader that lets you write styles in regular css
files and consume them in React.
1import styles from '../components/button/styles.css' 2 3export default () => ( 4 <div> 5 <button>styled-jsx</button> 6 <style jsx>{styles}</style> 7 </div> 8)
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
1config: { 2 module: { 3 rules: [ 4 { 5 test: /\.css$/, 6 use: [ 7 { 8 loader: require('styled-jsx/webpack').loader, 9 options: { 10 type: 'scoped' 11 } 12 } 13 ] 14 } 15 ] 16 } 17}
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.
1type validTypes = 'scoped' | 'global' | 'resolve' 2type fileName = string 3type Options = {| 4 type: validTypes | ((fileName, options) => validTypes) 5|}
1import styles from './styles.css?type=global' 2 3// webpack 4config: { 5 module: { 6 rules: [ 7 { 8 test: /\.css$/, 9 use: [ 10 { 11 loader: require('styled-jsx/webpack').loader, 12 options: { 13 type: (fileName, options) => options.query.type || 'scoped' 14 } 15 } 16 ] 17 } 18 ] 19 } 20}
The type can also be set per individual CSS file via CSS comment:
1/* @styled-jsx=scoped */ 2 3button { 4 color: red; 5}
The CSS comment option will override the one in the webpack configuration only for this specific file.
Example of next.config.js
to integrate styled-jsx/webpack
:
1module.exports = { 2 webpack: (config, { defaultLoaders }) => { 3 config.module.rules.push({ 4 test: /\.css$/, 5 use: [ 6 defaultLoaders.babel, 7 { 8 loader: require('styled-jsx/webpack').loader, 9 options: { 10 type: 'scoped' 11 } 12 } 13 ] 14 }) 15 16 return config 17 } 18}
Styles can be preprocessed via plugins.
Plugins are regular JavaScript modules that export a simple function with the following signature:
1function 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.
1{ 2 "plugins": [ 3 [ 4 "styled-jsx/babel", 5 { 6 "plugins": [ 7 "my-styled-jsx-plugin-package", 8 "/full/path/to/local/plugin" 9 ] 10 } 11 ] 12 ] 13}
1{ 2 "presets": [ 3 [ 4 "next/babel", 5 { 6 "styled-jsx": { 7 "plugins": ["styled-jsx-plugin-postcss"] 8 } 9 } 10 ] 11 ] 12}
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.
1/* `ExprNumber` is a number */ 2%%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.
1{ 2 "plugins": [ 3 [ 4 "styled-jsx/babel", 5 { 6 "plugins": [ 7 ["my-styled-jsx-plugin-package", { "exampleOption": true }] 8 ], 9 "sourceMaps": true 10 } 11 ] 12 ] 13}
Each plugin receives a options
object as second argument which contains
the babel and user options:
1;(css, options) => { 2 /* ... */ 3}
The options
object has the following shape:
1{ 2 // user options go here 3 // eg. exampleOption: true 4 5 // babel options 6 babel: { 7 sourceMaps: boolean, 8 vendorPrefixes: boolean, 9 isGlobal: boolean, 10 filename: ?string, // defined only when the filename option is passed to Babel, such as when using Babel CLI or Webpack 11 location: { // the original location of the CSS block in the JavaScript file 12 start: { 13 line: number, 14 column: number, 15 }, 16 end: { 17 line: number, 18 column: number, 19 } 20 } 21 } 22}
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:
1{ 2 "env": { 3 "production": { 4 "plugins": ["styled-jsx/babel"] 5 }, 6 "development": { 7 "plugins": ["styled-jsx/babel"] 8 }, 9 "test": { 10 "plugins": ["styled-jsx/babel-test"] 11 } 12 } 13}
When using styled-jsx/babel-test
, styled-jsx/css
throws the following error:
styled-jsx/css: if you are getting this error it means that your `css` tagged template literals were not transpiled.
to solve this issue you need to mock styled-jsx/css
. You can find a guide at the following link https://kevinjalbert.com/jest-snapshots-reducing-styled-jsx-noise/
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.
1const StyledImage = ({ src, alt = '' }) => ( 2 <React.Fragment> 3 <img src={src} alt={alt} /> 4 <style jsx>{` 5 img { 6 max-width: 100%; 7 } 8 `}</style> 9 </React.Fragment> 10)
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:
1export default () => ( 2 <div> 3 <ExternalComponent /> 4 5 <style jsx>{` 6 /* "div" will be prefixed, but ".nested-element" won't */ 7 8 div > :global(.nested-element) { 9 color: red; 10 } 11 `}</style> 12 </div> 13)
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 >
.
There's an article explaining how to bundle React components with Rollup and styled-jsx as an external dependency.
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>{)|(?<=css)":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:
1import { colors, spacing } from '../theme' 2import { invertColor } from '../theme/utils' 3 4const Button = ({ children }) => ( 5 <button> 6 {children} 7 8 {/*language=CSS*/} 9 <style jsx>{` 10 button { 11 padding: ${spacing.medium}; 12 background: ${colors.primary}; 13 color: ${invertColor(colors.primary)}; 14 } 15 `}</style> 16 </button> 17)
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.
1{ 2 "html": { 3 "snippets": { 4 "style-jsx": "<style jsx>{`\n\t$1\n`}</style>" 5 } 6 } 7}
Launch VS Code Quick Open (⌘+P), paste the following command, and press enter.
ext install Divlo.vscode-styled-jsx-syntax
If you use Stylus instead of plain CSS, install vscode-styled-jsx-stylus or paste the command below.
ext install vscode-styled-jsx-stylus
Launch VS Code Quick Open (⌘+P), paste the following command, and press enter.
ext install Divlo.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"] }
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:
1/// <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.
murmurhash2
(minimal and fast hashing) and an efficient style injection logic.No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
all changesets reviewed
Reason
no binaries found in the repo
Reason
license file detected
Details
Reason
security policy file detected
Details
Reason
0 commit(s) and 1 issue activity found in the last 90 days -- score normalized to 0
Reason
detected GitHub workflow tokens with excessive permissions
Details
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
project is not fuzzed
Details
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
Reason
24 existing vulnerabilities detected
Details
Score
Last Scanned on 2024-11-18
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More