# styled-jsx [![build status](https://github.com/vercel/styled-jsx/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/vercel/styled-jsx/actions?query=branch%3Amain) 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](https://github.com/vercel/styled-jsx/tree/v2). - [Getting started](#getting-started) - [Configuration options](#configuration-options) - [`optimizeForSpeed`](#optimizeforspeed) - [`sourceMaps`](#sourcemaps) - [`styleModule`](#stylemodule) - [`vendorPrefixes`](#vendorprefixes) - [Features](#features) - [How It Works](#how-it-works) - [Why It Works Like This](#why-it-works-like-this) - [Targeting The Root](#targeting-the-root) - [Global styles](#global-styles) - [One-off global selectors](#one-off-global-selectors) - [Dynamic styles](#dynamic-styles) - [Via interpolated dynamic props](#via-interpolated-dynamic-props) - [Via `className` toggling](#via-classname-toggling) - [Via inline `style`](#via-inline-style) - [Constants](#constants) - [Server-Side Rendering](#server-side-rendering) - [External CSS and styles outside of the component](#external-css-and-styles-outside-of-the-component) - [External styles](#external-styles) - [Styles outside of components](#styles-outside-of-components) - [The `resolve` tag](#the-resolve-tag) - [Styles in regular CSS files](#styles-in-regular-css-files) - [CSS Preprocessing via Plugins](#css-preprocessing-via-plugins) - [Plugin options](#plugin-options) - [Example plugins](#example-plugins) - [Rendering in tests](#rendering-in-tests) - [FAQ](#faq) - [Warning: unknown `jsx` prop on <style> tag](#warning-unknown-jsx-prop-on-style-tag) - [Can I return an array of components when using React 16?](#can-i-return-an-array-of-components-when-using-react-16) - [Styling third parties / child components from the parent](#styling-third-parties--child-components-from-the-parent) - [Some styles are missing in production](https://github.com/vercel/styled-jsx/issues/319#issuecomment-349239326) - [Build a component library with styled-jsx](#build-a-component-library-with-styled-jsx) - [Syntax Highlighting](#syntax-highlighting) - [ESLint](#eslint) - [TypeScript](#typescript) - [Credits](#credits) ## Getting started Firstly, install the package: ```bash npm install --save styled-jsx ``` Next, add `styled-jsx/babel` to `plugins` in your babel configuration: ```json { "plugins": ["styled-jsx/babel"] } ``` Now add ` ) ``` ## 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. ```json { "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`) #### `styleModule` Module that the transpiled files should import (default: `styled-jsx/style`) #### `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 ## 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: ```jsx import _JSXStyle from 'styled-jsx/style' export default () => (

only this paragraph will get the style :)

<_JSXStyle id="123">{`p.jsx-123 {color: red;}`}

) ``` ### 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 `

` 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`](https://web.dev/articles/shadowdom-v1) works with Shadow DOM. If you want to target _only_ the host, we suggest you use a class: ```jsx export default () => (

) ``` ### Global styles To skip scoping entirely, you can make the global-ness of your styles explicit by adding _global_. ```jsx export default () => (

) ``` The advantage of using this over `

) ``` ### 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. ```jsx const Button = props => ( ) ``` 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. ```jsx const Button = props => ( ) ``` #### Via `className` toggling The second option is to pass properties that toggle class names. ```jsx const Button = props => ( ) ``` Then you would use this component as either `` or ``. #### 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: ```jsx const Button = ({ padding, children }) => ( ) ``` In this example, the padding defaults to the one set in ` ) ``` 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. ```jsx import React from 'react' import ReactDOM from 'react-dom/server' import { StyleRegistry, useStyleRegistry } from 'styled-jsx' import App from './app' function Styles() { const registry = useStyleRegistry() const styles = registry.styles() return <>{styles} } export default (req, res) => { const app = ReactDOM.renderToString() const html = ReactDOM.renderToStaticMarkup(

) res.end('' + html) } ``` 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()`). ```js const registry = createStyleRegistry() const styles = registry.styles() // access styles function Page() { return ( ) } ``` By default `` 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. ### Content Security Policy Strict [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) is supported. You should generate a nonce **per request**. ```js 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 `` 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: ```js /* 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: ```jsx import styles, { button, body } from './styles' export default () => (

) ``` N.B. All the tags except for [`resolve`](#the-resolve-tag) don't support dynamic styles. `resolve` and `global` can also be imported individually: ```js 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. ```jsx import css from 'styled-jsx/css' export default () => (

) 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 `

) ``` To consume the styles in your component you can import them from your CSS file and render them using a ` ) ``` ### 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`](#the-resolve-tag). 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: ```jsx export default () => (

) ``` 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](https://medium.com/@tomaszmularczyk89/guide-to-building-a-react-components-library-with-rollup-and-styled-jsx-694ec66bd2) 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 ` ) ``` ### 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. ```json { "html": { "snippets": { "style-jsx": "" } } } ``` ### Syntax Highlighting [Visual Studio Code Extension](https://marketplace.visualstudio.com/items?itemName=Divlo.vscode-styled-jsx-syntax) 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](https://marketplace.visualstudio.com/items?itemName=samuelroy.vscode-styled-jsx-stylus) or paste the command below. ``` ext install vscode-styled-jsx-stylus ``` ### Autocomplete [Visual Studio Code Extension](https://marketplace.visualstudio.com/items?itemName=Divlo.vscode-styled-jsx-languageserver) Launch VS Code Quick Open (⌘+P), paste the following command, and press enter. ``` ext install Divlo.vscode-styled-jsx-languageserver ``` ### Vim Install [vim-styled-jsx](https://github.com/alampros/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"] } ``` ## TypeScript If you're using TypeScript, then in order to allow `

套件	下載數	Stars	大小	Issues	發布時間	許可

styled-jsx	12,661,489	7,790	1.03 MB	83	5 個月前	MIT