0
# React JSS
1

2
React JSS provides seamless React integration for JSS (JavaScript Style Sheets), enabling developers to write CSS-in-JS styles with dynamic theming capabilities and React-specific optimizations. It offers multiple styling approaches including Higher-Order Components, React Hooks, styled components, and JSX factories, all supporting theme injection and dynamic style generation.
3

4
## Package Information
5

6
- **Package Name**: react-jss
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install react-jss`
10

11
## Core Imports
12

13
```typescript
14
import { withStyles, createUseStyles, JssProvider, ThemeProvider } from 'react-jss';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { withStyles, createUseStyles, JssProvider, ThemeProvider } = require('react-jss');
21
```
22

23
## Basic Usage
24

25
```typescript
26
import React from 'react';
27
import { createUseStyles } from 'react-jss';
28

29
// Define styles
30
const useStyles = createUseStyles({
31
  container: {
32
    padding: '20px',
33
    backgroundColor: '#f5f5f5',
34
    borderRadius: '8px'
35
  },
36
  title: {
37
    fontSize: '24px',
38
    color: (props) => props.theme.primaryColor || '#333',
39
    marginBottom: '16px'
40
  }
41
});
42

43
// Use in component
44
function MyComponent(props) {
45
  const classes = useStyles(props);
46
  return (
47
    <div className={classes.container}>
48
      <h1 className={classes.title}>Hello World</h1>
49
    </div>
50
  );
51
}
52
```
53

54
## Architecture
55

56
React JSS is built around several key architectural components:
57

58
- **Multiple Styling APIs**: Four distinct approaches (withStyles HOC, createUseStyles hooks, styled components, jsx factory) for different use cases and preferences
59
- **Theme System**: Comprehensive theming support with providers, context, and injection capabilities
60
- **JSS Integration**: Built on top of JSS core with default preset plugins for vendor prefixing, nesting, and other CSS features  
61
- **Provider System**: JssProvider for configuration management and stylesheet registry control
62
- **Context Architecture**: JssContext for sharing JSS instances and configuration across component trees
63
- **Server-Side Rendering**: Full SSR support with registry management and style extraction capabilities
64
- **Dynamic Styles**: Support for function-based styles that respond to props and theme changes
65
- **Performance Optimizations**: Sheet caching, reference counting, and React optimization patterns
66

67
## Capabilities
68

69
### Higher-Order Component API
70

71
Classic React pattern for injecting styles into components as a `classes` prop. Ideal for class components and when following traditional HOC patterns.
72

73
```typescript { .api }
74
function withStyles<ClassNames extends string | number | symbol, Props, Theme>(
75
  styles: Styles<ClassNames, Props, Theme> | ((theme: Theme) => Styles<ClassNames, Props, undefined>),
76
  options?: WithStylesOptions
77
): <C>(comp: C) => ComponentType<
78
  JSX.LibraryManagedAttributes<
79
    C,
80
    Omit<GetProps<C>, 'classes'> & {
81
      classes?: Partial<ClassesForStyles<typeof styles>>;
82
      innerRef?: RefObject<any> | ((instance: any) => void);
83
    }
84
  >
85
>;
86

87
interface WithStylesOptions extends BaseOptions {
88
  injectTheme?: boolean;
89
  jss?: Jss;
90
}
91
```
92

93
[Higher-Order Component API](./withstyles.md)
94

95
### React Hooks API
96

97
Modern React hooks approach for using JSS styles. Perfect for functional components and when you need fine-grained control over style lifecycle.
98

99
```typescript { .api }
100
function createUseStyles<C extends string = string, Props = unknown, Theme = DefaultTheme>(
101
  styles: Styles<C, Props, Theme> | ((theme: Theme) => Styles<C, Props, undefined>),
102
  options?: CreateUseStylesOptions<Theme>
103
): (data?: Props & {theme?: Theme}) => Classes<C>;
104

105
interface CreateUseStylesOptions<Theme = DefaultTheme> extends BaseOptions<Theme> {
106
  name?: string;
107
}
108
```
109

110
[React Hooks API](./hooks.md)
111

112
### Styled Components API
113

114
Styled-components-like API for creating styled React components. Best for component libraries and when you prefer component-based styling approaches.
115

116
```typescript { .api }
117
function styled(
118
  tagOrComponent: string | ComponentType<any>,
119
  options?: StyledOptions
120
): (...styles: Array<CSSObject | ((props: any) => CSSObject)>) => ComponentType<any>;
121

122
interface StyledOptions extends BaseOptions {
123
  shouldForwardProp?: (prop: string) => boolean;
124
}
125
```
126

127
[Styled Components API](./styled.md)
128

129
### JSX Factory
130

131
Custom JSX factory that supports inline CSS via `css` prop. Useful for quick styling and prototyping without defining separate style objects.
132

133
```typescript { .api }
134
function jsx(type: any, props: any, ...children: any[]): ReactElement;
135
function createJsx(css?: CSSProcessor): typeof jsx;
136

137
interface CSSProcessor {
138
  (styles: CSSObject): string;
139
}
140
```
141

142
[JSX Factory](./jsx.md)
143

144
### Theme System
145

146
Comprehensive theming capabilities with providers, context access, and theme injection. Essential for applications requiring consistent design systems and theme switching.
147

148
```typescript { .api }
149
const ThemeProvider: ComponentType<{theme: any; children: ReactNode}>;
150
function useTheme<T = DefaultTheme>(): T;
151
function withTheme<P>(component: ComponentType<P>): ComponentType<P & {theme: any}>;
152
function createTheming<T>(defaultTheme?: T): Theming<T>;
153

154
interface Theming<Theme> {
155
  context: Context<Theme>;
156
  withTheme: (component: ComponentType<any>) => ComponentType<any>;
157
  useTheme: () => Theme;
158
  ThemeProvider: ComponentType<{theme: Theme; children: ReactNode}>;
159
}
160
```
161

162
[Theme System](./theming.md)
163

164
### Provider and Context System
165

166
JSS configuration management and context system for sharing JSS instances, registries, and settings across your application component tree.
167

168
```typescript { .api }
169
const JssProvider: ComponentType<{
170
  jss?: Jss;
171
  registry?: SheetsRegistry;
172
  generateId?: GenerateId;
173
  classNamePrefix?: string;
174
  disableStylesGeneration?: boolean;
175
  children: ReactNode;
176
  id?: CreateGenerateIdOptions;
177
  isSSR?: boolean;
178
}>;
179

180
const JssContext: Context<JssContextValue>;
181

182
interface JssContextValue {
183
  jss?: Jss;
184
  registry?: SheetsRegistry;
185
  managers?: Managers;
186
  sheetOptions: StyleSheetFactoryOptions;
187
  disableStylesGeneration: boolean;
188
  isSSR: boolean;
189
}
190
```
191

192
[Provider and Context System](./providers.md)
193

194
## Core Types
195

196
```typescript { .api }
197
interface WithStylesProps<S extends Styles<any, any, any> | ((theme: any) => Styles<any, any, undefined>)> {
198
  classes: ClassesForStyles<S>;
199
}
200

201
type ClassesForStyles<S extends Styles<any, any, any> | ((theme: any) => Styles<any, any, undefined>)> = 
202
  Classes<S extends (theme: any) => Styles<any, any, undefined> ? keyof ReturnType<S> : keyof S>;
203

204
interface BaseOptions<Theme = DefaultTheme> extends StyleSheetFactoryOptions {
205
  index?: number;
206
  theming?: Theming<Theme>;
207
}
208

209
type DefaultTheme = Jss.Theme;
210

211
type GetProps<C> = C extends ComponentType<infer P> ? P : never;
212

213
interface StyledOptions extends BaseOptions {
214
  shouldForwardProp?: (prop: string) => boolean;
215
}
216

217
interface CSSProcessor {
218
  (styles: CSSObject): string;
219
}
220

221
interface CSSObject {
222
  [key: string]: any;
223
}
224

225
declare global {
226
  namespace Jss {
227
    /** You can use the global Jss.Theme interface to define a project-wide default theme. */
228
    export interface Theme {}
229
  }
230
}
231
```
232

233
## All Exports
234

235
```typescript { .api }
236
// Main styling APIs
237
function withStyles<ClassNames extends string | number | symbol, Props, Theme>(
238
  styles: Styles<ClassNames, Props, Theme> | ((theme: Theme) => Styles<ClassNames, Props, undefined>),
239
  options?: WithStylesOptions
240
): <C>(comp: C) => ComponentType<
241
  JSX.LibraryManagedAttributes<
242
    C,
243
    Omit<GetProps<C>, 'classes'> & {
244
      classes?: Partial<ClassesForStyles<typeof styles>>;
245
      innerRef?: RefObject<any> | ((instance: any) => void);
246
    }
247
  >
248
>;
249

250
function createUseStyles<C extends string = string, Props = unknown, Theme = DefaultTheme>(
251
  styles: Styles<C, Props, Theme> | ((theme: Theme) => Styles<C, Props, undefined>),
252
  options?: CreateUseStylesOptions<Theme>
253
): (data?: Props & {theme?: Theme}) => Classes<C>;
254

255
function styled(
256
  tagOrComponent: string | ComponentType<any>,
257
  options?: StyledOptions
258
): (...styles: Array<CSSObject | ((props: any) => CSSObject)>) => ComponentType<any>;
259

260
function jsx(type: any, props: any, ...children: any[]): ReactElement;
261
function createJsx(css?: CSSProcessor): typeof jsx;
262

263
// Provider and context
264
const JssProvider: ComponentType<{
265
  jss?: Jss;
266
  registry?: SheetsRegistry;
267
  generateId?: GenerateId;
268
  classNamePrefix?: string;
269
  disableStylesGeneration?: boolean;
270
  children: ReactNode;
271
  id?: CreateGenerateIdOptions;
272
  isSSR?: boolean;
273
}>;
274

275
const JssContext: Context<JssContextValue>;
276

277
// Re-exported from JSS core
278
const jss: Jss;
279
const SheetsRegistry: typeof JSSSheetsRegistry;
280
const createGenerateId: CreateGenerateId;
281

282
// Re-exported from theming package  
283
const ThemeProvider: ComponentType<{theme: any; children: ReactNode}>;
284
const useTheme: <T = DefaultTheme>() => T;
285
const withTheme: <P>(component: ComponentType<P>) => ComponentType<P & {theme: any}>;
286
const createTheming: <T>(defaultTheme?: T) => Theming<T>;
287

288
// Default export
289
export default withStyles;
290
```