styled-jsx-preact
v3.0.2-rc1
Published
Full CSS support for JSX without compromises
Downloads
7
Maintainers
Readme
styled-jsx
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.
- Getting started
- Configuration options
- Features
- How It Works
- Targeting The Root
- Global styles
- Dynamic styles
- Constants
- Server-Side Rendering
- External CSS and styles outside of the component
- CSS Preprocessing via Plugins
- FAQ
- Syntax Highlighting
Getting started
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>
)
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.
{
"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'
sourceMaps
Generates source maps (default: false
)
vendorPrefixes
Turn on/off automatic vendor prefixing (default: true
)
Features
- Full CSS support, no tradeoffs in power
- Runtime size of just 3kb (gzipped, from 12kb)
- Complete isolation: Selectors, animations, keyframes
- Built-in CSS vendor prefixing
- 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
How It Works
The example above transpiles to the following:
import _JSXStyle from 'styled-jsx-preact/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>
)
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:
export default () => (
<div className="root">
<style jsx>{`
.root {
color: green;
}
`}</style>
</div>
)
Global styles
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.
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.
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>
)
Via className
toggling
The 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>
.
Via inline 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}>
.
Constants
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.
Server-Side Rendering
styled-jsx/server
The 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.
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 scopedclassName
and astyles
element.
External styles
In an external file:
/* styles.js */
import css from 'styled-jsx/css'
// Scoped styles
export const button = css`button { color: hotpink; }`
// Global styles
export const body = css.global`body { margin: 0; }`
// Resolved styles
export 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 exports
export default css`div { color: green; }`
You can then import and use those styles:
import styles, { button, body } from './styles'
export default () => (
<div>
<button>styled-jsx</button>
<style jsx>{styles}</style>
<style jsx>{button}</style>
<style jsx global>{body}</style>
</div>
)
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.
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.
The resolve
tag
The resolve
tag from styled-jsx/css
can be used when you need to scope some CSS and want back the generated scoped className
and styles
. This is usually the case when you want to style nested components from the parent.
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}
<style jsx>{`div { border: 5px solid green }`}</style>
</div>
)
The resolve
tag also supports dynamic styles:
import React from 'react'
import css from 'styled-jsx/css'
function getLinkStyles(color) {
return css.resolve`
a { color: ${color} }
`
}
export default (props) => {
const { className, styles } = getLinkStyles(props.theme.color)
return (
<div>
<Link className={className}>About</Link>
{styles}
</div>
)
}
Using resolve
as a babel macro
The resolve
tag can be used as a Babel macro thanks to the babel-plugin-macros
system.
npm i --save styled-jsx
npm i --save-dev babel-plugin-macros
Next add babel-plugin-macros
to your babel configuration:
{
"plugins": [
"babel-plugin-macros"
]
}
You can then start to use resolve
by importing it from styled-jsx/macro
.
import css, { resolve } from 'styled-jsx/macro'
const stylesInfo = css.resolve`a { color: green; }`
const stylesInfo2 = resolve`a { color: green; }`
Create React App comes with babel-plugin-macros
pre-installed so you just need to install styled-jsx
and you can start to use `resolve right away.
Styles in regular CSS files
styled-jsx v3 comes with a webpack loader that lets you write styles in regular css
files and consume them in React.
import styles from '../components/button/styles.css'
export default () => (
<div>
<button>styled-jsx</button>
<style jsx>{styles}</style>
</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
config: {
module: {
rules: [
test: /\.css$/,
use: [{
loader: require('styled-jsx/webpack').loader,
options: {
type: 'scoped'
}
}]
]
}
}
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 file name that is being transpiled and must return a valid type.
type validTypes = 'scoped' | 'global' | 'resolve'
type fileName = string
type Options = {|
type: validTypes | (fileName) => validTypes
|}
The type can also be set per individual CSS file via CSS comment:
/* @styled-jsx=scoped */
button { color: red }
The CSS comment option will override the one in the webpack configuration only for this specific file.
Next.js
Example of next.config.js
to integrate styled-jsx/webpack
:
module.exports = {
webpack: (config, { defaultLoaders }) => {
config.module.rules.push({
test: /\.css$/,
use: [
defaultLoaders.babel,
{
loader: require('styled-jsx/webpack').loader,
options: {
type: 'scoped'
}
}
]
})
return config
}
}
CSS Preprocessing via Plugins
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>
Plugin options
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,
}
}
}
}
Example plugins
The following plugins are proof of concepts/sample:
- styled-jsx-plugin-sass
- styled-jsx-plugin-postcss
- styled-jsx-plugin-stylelint
- styled-jsx-plugin-less
- styled-jsx-plugin-stylus
FAQ
Warning: unknown jsx
prop on <style> tag
If 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.
Can I return an array of components when using React 16?
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>
)
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 list please open a PR and let us now.
Atom
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
Webstorm/Idea
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>
)
Emmet
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>"
}
}
}
Syntax Highlighting Visual Studio Code Extension
Launch VS Code Quick Open (⌘+P), paste the following command, and press enter.
ext install vscode-styled-jsx
Autocomplete Visual Studio Code Extension
Launch VS Code Quick Open (⌘+P), paste the following command, and press enter.
ext install vscode-styled-jsx-languageserver
Vim
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:
"settings": {"import/core-modules": ["styled-jsx/css"] }
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.
Authors
- Guillermo Rauch (@rauchg) - ▲ZEIT
- Naoyuki Kanezawa (@nkzawa) - ▲ZEIT
- Giuseppe Gurgone (@giuseppegurgone)