0
# styled-jsx
1

2
styled-jsx provides full CSS support for JSX without compromises, enabling developers to write scoped, component-friendly CSS directly within JSX components. It offers complete CSS capabilities with automatic scoping, server-side rendering support, and a compact 3kb gzipped runtime.
3

4
## Package Information
5

6
- **Package Name**: styled-jsx
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install styled-jsx`
10

11
## Core Imports
12

13
```javascript
14
import { StyleRegistry, createStyleRegistry, useStyleRegistry } from "styled-jsx";
15
```
16

17
For CSS utilities:
18

19
```javascript
20
import css from "styled-jsx/css";
21
```
22

23
For style component (usually auto-imported by Babel):
24

25
```javascript
26
import JSXStyle from "styled-jsx/style";
27
```
28

29
For babel macro support:
30

31
```javascript
32
import { resolve } from "styled-jsx/macro";
33
```
34

35
## Basic Usage
36

37
```jsx
38
// Basic scoped styles
39
function Button({ children }) {
40
  return (
41
    <button>
42
      {children}
43
      <style jsx>{`
44
        button {
45
          padding: 20px;
46
          background: #eee;
47
          color: #999;
48
          border: none;
49
          border-radius: 4px;
50
        }
51
      `}</style>
52
    </button>
53
  );
54
}
55

56
// Global styles
57
function App() {
58
  return (
59
    <div>
60
      <Button>Click me</Button>
61
      <style jsx global>{`
62
        body {
63
          margin: 0;
64
          font-family: Arial, sans-serif;
65
        }
66
      `}</style>
67
    </div>
68
  );
69
}
70
```
71

72
## Architecture
73

74
styled-jsx is built around several key concepts:
75

76
- **Scoped Styles**: CSS is automatically scoped to components using unique class names
77
- **Style Registry**: Manages style injection, deduplication, and server-side rendering
78
- **Babel Transformation**: Compile-time processing transforms styled-jsx syntax into optimized runtime code
79
- **External CSS Support**: css.resolve and css.global provide utilities for styles outside JSX
80
- **SSR Integration**: Full server-side rendering support with style extraction and hydration
81

82
## Capabilities
83

84
### Component Scoped Styles
85

86
Core CSS-in-JS functionality for writing scoped styles directly in JSX components. Perfect for component-level styling with full CSS support.
87

88
```jsx { .api }
89
// JSX Style Tag (transformed by Babel)
90
<style jsx>{`/* CSS */`}</style>
91
<style jsx global>{`/* Global CSS */`}</style>
92
```
93

94
[Component Styling](./component-styling.md)
95

96
### Style Registry Management
97

98
Server-side rendering and style management system for handling style injection, deduplication, and extraction.
99

100
```typescript { .api }
101
function StyleRegistry({
102
  children,
103
  registry
104
}: {
105
  children: JSX.Element | import('react').ReactNode;
106
  registry?: StyledJsxStyleRegistry;
107
}): JSX.Element;
108

109
function createStyleRegistry(): StyledJsxStyleRegistry;
110

111
function useStyleRegistry(): StyledJsxStyleRegistry;
112

113
interface StyledJsxStyleRegistry {
114
  styles(options?: { nonce?: string }): JSX.Element[];
115
  flush(): void;
116
  add(props: any): void;
117
  remove(props: any): void;
118
}
119
```
120

121
[Style Registry](./style-registry.md)
122

123
### External CSS Utilities
124

125
CSS utilities for creating styles outside of JSX components, including scoped class generation and global style definition.
126

127
```typescript { .api }
128
function css(chunks: TemplateStringsArray, ...args: any[]): JSX.Element;
129

130
namespace css {
131
  function global(
132
    chunks: TemplateStringsArray,
133
    ...args: any[]
134
  ): JSX.Element;
135
  
136
  function resolve(
137
    chunks: TemplateStringsArray,
138
    ...args: any[]
139
  ): { className: string; styles: JSX.Element };
140
}
141
```
142

143
[External CSS](./external-css.md)
144

145
### Babel Macro Support
146

147
Babel macro functionality for using css.resolve without babel configuration, supporting the babel-plugin-macros ecosystem.
148

149
```typescript { .api }
150
function resolve(
151
  chunks: TemplateStringsArray,
152
  ...args: any[]
153
): {
154
  className: string;
155
  styles: JSX.Element;
156
}
157
```
158

159
[Babel Macro](./babel-macro.md)
160

161
### Build Tool Integration
162

163
Babel plugin and webpack loader for transforming styled-jsx syntax and processing external CSS files.
164

165
```javascript { .api }
166
// Babel plugin (styled-jsx/babel)
167
module.exports = function styledJsxBabelPlugin(options?: {
168
  optimizeForSpeed?: boolean;
169
  sourceMaps?: boolean;
170
  styleModule?: string;
171
  vendorPrefixes?: boolean;
172
  plugins?: Array<any>;
173
}): any;
174

175
// Webpack loader (styled-jsx/webpack)  
176
module.exports = {
177
  loader: string; // Path to webpack loader
178
}
179
```
180

181
[Build Integration](./build-integration.md)
182

183
## Types
184

185
```typescript { .api }
186
interface StyledJsxStyleRegistry {
187
  /** Get array of style elements for rendering */
188
  styles(options?: { nonce?: string }): JSX.Element[];
189
  /** Clear all styles from registry */
190
  flush(): void;
191
  /** Add style to registry */
192
  add(props: any): void;
193
  /** Remove style from registry */
194
  remove(props: any): void;
195
}
196

197
// React module augmentation for jsx and global props
198
declare module 'react' {
199
  interface StyleHTMLAttributes<T> extends HTMLAttributes<T> {
200
    jsx?: boolean;
201
    global?: boolean;
202
  }
203
}
204
```