0
# TSS-React
1

2
TSS-React is a type-safe CSS-in-JS solution built on top of Emotion that provides dynamic style generation for React applications. It offers seamless integration with MUI, Next.js support, and maintains JSX readability while eliminating CSS priority conflicts. With minimal bundle impact (~5kB minzipped alongside MUI), it serves as a modern replacement for @material-ui makeStyles and react-jss.
3

4
## Package Information
5

6
- **Package Name**: tss-react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install tss-react`
10
- **Dependencies**: `@emotion/react`, `@emotion/cache`, `@emotion/serialize`, `@emotion/utils`
11
- **Peer Dependencies**: `react` (^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0), `@types/react`, `@emotion/react` (^11.4.1)
12
- **Optional Peer Dependencies**: `@mui/material` (^5.0.0 || ^6.0.0 || ^7.0.0), `@emotion/server` (^11.4.0)
13

14
## Core Imports
15

16
**Factory Functions:**
17

18
```typescript
19
import { createTss, createMakeStyles, createWithStyles, createMakeAndWithStyles } from "tss-react";
20
```
21

22
**Pre-configured Instances:**
23

24
```typescript
25
import { tss, useStyles } from "tss-react";
26
```
27

28
**Types and Utilities:**
29

30
```typescript
31
import type { Tss, Css, Cx, CSSObject, CSSInterpolation, CxArg } from "tss-react";
32
import { GlobalStyles, keyframes, TssCacheProvider } from "tss-react";
33
```
34

35
**MUI Integration:**
36

37
```typescript
38
import { tss, makeStyles, withStyles, useStyles } from "tss-react/mui";
39
```
40

41
**Next.js Integration:**
42

43
```typescript
44
import { NextAppDirEmotionCacheProvider } from "tss-react/next/appDir";
45
import { createEmotionSsrAdvancedApproach } from "tss-react/next/pagesDir";
46
```
47

48
**DSFR Integration:**
49

50
```typescript
51
import { tss, useStyles } from "tss-react/dsfr";
52
```
53

54
**CSS Utilities:**
55

56
```typescript
57
import { createCssAndCx, createUseCssAndCx } from "tss-react/cssAndCx";
58
```
59

60
**Compatibility Mode:**
61

62
```typescript
63
import { createTss, createMakeStyles, createWithStyles } from "tss-react/compat";
64
import { makeStyles, withStyles } from "tss-react/mui-compat";
65
```
66

67
**CommonJS:**
68

69
```javascript
70
const { createTss, tss, useStyles } = require("tss-react");
71
```
72

73
## Basic Usage
74

75
```typescript
76
import { tss } from "tss-react";
77

78
// Simple component styling
79
const useStyles = tss.create({
80
  root: {
81
    backgroundColor: "red",
82
    color: "white",
83
    padding: 16
84
  },
85
  button: {
86
    fontSize: 18,
87
    "&:hover": {
88
      backgroundColor: "darkred"
89
    }
90
  }
91
});
92

93
function MyComponent() {
94
  const { classes } = useStyles();
95
  return (
96
    <div className={classes.root}>
97
      <button className={classes.button}>Click me</button>
98
    </div>
99
  );
100
}
101
```
102

103
## Architecture
104

105
TSS-React is built around several key architectural components:
106

107
- **TSS Factory System**: `createTss()` creates customized TSS instances with context and plugin support
108
- **Style Generation**: Dynamic CSS generation based on component props and theme context
109
- **Integration Layer**: Specialized integrations for MUI themes, Next.js SSR, and DSFR design system
110
- **Type Safety**: Full TypeScript support with type-safe nested selectors and parameter inference
111
- **Emotion Foundation**: Built on Emotion's proven CSS-in-JS infrastructure with custom caching strategies
112
- **Plugin Architecture**: Extensible system allowing custom style processing and theme integration
113

114
## Capabilities
115

116
### Core TSS API
117

118
Foundation functionality for creating type-safe, dynamic styles. The TSS system provides chainable methods for adding parameters, names, and nested selectors.
119

120
```typescript { .api }
121
function createTss<Context>(params: {
122
  useContext: () => Context;
123
  usePlugin?: UsePlugin<Context, any>;
124
}): { tss: Tss<Context, {}, never, {}, never> };
125

126
interface Tss<Context, Params, RuleNameSubsetReferencableInNestedSelectors, PluginParams, ExcludedMethod> {
127
  create<RuleName extends string>(
128
    cssObjectByRuleNameOrGetCssObjectByRuleName: CssObjectByRuleNameOrGetCssObjectByRuleName<Context, Params, RuleNameSubsetReferencableInNestedSelectors, RuleName>
129
  ): UseStyles<Context, Params, RuleName, PluginParams>;
130
  withParams<NewParams extends Record<string, unknown>>(): Tss<Context, NewParams, RuleNameSubsetReferencableInNestedSelectors, PluginParams, ExcludedMethod | "withParams">;
131
  withName(name: string | Record<string, unknown>): Tss<Context, Params, RuleNameSubsetReferencableInNestedSelectors, PluginParams, ExcludedMethod | "withName">;
132
}
133
```
134

135
[Core TSS API](./core-tss-api.md)
136

137
### MakeStyles API
138

139
React hook-based styling API compatible with Material-UI v4 patterns. Provides theme integration and dynamic style generation.
140

141
```typescript { .api }
142
function createMakeStyles<Theme>(params: {
143
  useTheme: () => Theme;
144
  cache?: EmotionCache;
145
}): {
146
  makeStyles<Params = void>(params?: { name?: string; uniqId?: string }): (
147
    cssObjectByRuleNameOrGetCssObjectByRuleName: CSSObjectByRuleName | ((theme: Theme, params: Params) => CSSObjectByRuleName)
148
  ) => (params: Params) => { classes: Record<string, string>; cx: Cx; css: Css; theme: Theme };
149
  TssCacheProvider: React.ComponentType<{ children: ReactNode }>;
150
};
151
```
152

153
[MakeStyles API](./makestyles-api.md)
154

155
### WithStyles HOC
156

157
Higher-order component pattern for injecting styles into React components. Supports both function and class components with full TypeScript integration.
158

159
```typescript { .api }
160
function createWithStyles<Theme>(params: {
161
  useTheme: () => Theme;
162
  cache?: EmotionCache;
163
}): {
164
  withStyles<Component, Props, CssObjectByRuleName>(
165
    Component: Component,
166
    cssObjectByRuleNameOrGetCssObjectByRuleName: CssObjectByRuleName | ((theme: Theme, props: Props, classes: Record<string, string>) => CssObjectByRuleName)
167
  ): ComponentType<Props>;
168
};
169
```
170

171
[WithStyles HOC](./withstyles-hoc.md)
172

173
### MUI Integration
174

175
Specialized integration for Material-UI applications with theme support and style overrides compatibility.
176

177
```typescript { .api }
178
// Pre-configured MUI instances
179
const tss: Tss<{ theme: Theme }, {}, never, MuiThemeStyleOverridesPluginParams, never>;
180
const makeStyles: MakeStylesFunction<Theme>;
181
const withStyles: WithStylesFunction<Theme>;
182
const useStyles: UseStyles<{ theme: Theme }, {}, string, MuiThemeStyleOverridesPluginParams>;
183

184
function useMuiThemeStyleOverridesPlugin(params: {
185
  classes: Record<string, string>;
186
  theme: MuiThemeLike;
187
  muiStyleOverridesParams?: MuiThemeStyleOverridesPluginParams;
188
  css: Css;
189
  cx: Cx;
190
  name?: string;
191
}): Record<string, string>;
192
```
193

194
[MUI Integration](./mui-integration.md)
195

196
### Next.js SSR Support
197

198
Server-side rendering utilities for Next.js applications supporting both App Router and Pages Router patterns.
199

200
```typescript { .api }
201
// App Router support
202
function NextAppDirEmotionCacheProvider(props: NextAppDirEmotionCacheProviderProps): JSX.Element;
203

204
interface NextAppDirEmotionCacheProviderProps {
205
  options: Omit<OptionsOfCreateCache, "insertionPoint"> & { prepend?: boolean };
206
  CacheProvider?: React.Provider<EmotionCache>;
207
  children: ReactNode;
208
}
209

210
// Pages Router support
211
function createEmotionSsrAdvancedApproach(
212
  options: Omit<OptionsOfCreateCache, "insertionPoint"> & { prepend?: boolean },
213
  CacheProvider?: Function
214
): {
215
  withAppEmotionCache<AppComponent>(App: AppComponent): AppComponent;
216
  augmentDocumentWithEmotionCache(Document: NextComponentType): void;
217
};
218
```
219

220
[Next.js SSR Support](./nextjs-ssr.md)
221

222
### CSS Utilities
223

224
Low-level CSS generation and class manipulation utilities for advanced use cases.
225

226
```typescript { .api }
227
function createCssAndCx(params: { cache: EmotionCache }): {
228
  css: Css;
229
  cx: Cx;
230
};
231

232
function createUseCssAndCx(params: {
233
  useCache: () => EmotionCache;
234
}): {
235
  useCssAndCx(): { css: Css; cx: Cx };
236
};
237

238
function mergeClasses<T extends string, U extends string>(
239
  classesFromUseStyles: Record<T, string>,
240
  classesOverrides: Partial<Record<U, string>> | undefined,
241
  cx: Cx
242
): Record<T, string> & Partial<Record<Exclude<U, T>, string>>;
243
```
244

245
[CSS Utilities](./css-utilities.md)
246

247
### Global Styles & Keyframes
248

249
Global CSS injection and animation keyframe support built on Emotion primitives.
250

251
```typescript { .api }
252
function GlobalStyles(props: { styles: CSSInterpolation }): JSX.Element;
253

254
function keyframes(template: TemplateStringsArray, ...args: CSSInterpolation[]): string;
255
function keyframes(...args: CSSInterpolation[]): string;
256
```
257

258
[Global Styles & Keyframes](./global-styles-keyframes.md)
259

260
### DSFR Integration
261

262
French Government Design System integration with dark mode detection. Provides pre-configured TSS instance with theme context.
263

264
```typescript { .api }
265
// Pre-configured DSFR instances with dark mode context
266
const tss: Tss<{ isDark: boolean }, {}, never, {}, never>;
267
const useStyles: UseStyles<{ isDark: boolean }, {}, string, {}>;
268
```
269

270
[DSFR Integration](./dsfr-integration.md)
271

272
### Compatibility Mode
273

274
Compatibility layer providing alternative withStyles implementation for specific use cases and migration scenarios.
275

276
```typescript { .api }
277
function createMakeAndWithStyles<Theme>(params: {
278
  useTheme: () => Theme;
279
  cache?: EmotionCache;
280
}): {
281
  makeStyles: MakeStylesFunction<Theme>;
282
  withStyles: WithStylesFunction<Theme>;
283
  TssCacheProvider: React.ComponentType<{ children: ReactNode }>;
284
};
285
```
286

287
[Compatibility Mode](./compatibility.md)
288

289
### TSS Cache Provider
290

291
React context provider for managing Emotion cache instances across the component tree. Ensures proper style injection and cache isolation.
292

293
```typescript { .api }
294
/**
295
 * React context provider for Emotion cache
296
 * Ensures proper CSS-in-JS style injection and hydration
297
 */
298
function TssCacheProvider(props: {
299
  children: ReactNode;
300
}): JSX.Element;
301
```
302

303
**Usage Examples:**
304

305
```typescript
306
import { TssCacheProvider } from "tss-react";
307
import createCache from "@emotion/cache";
308

309
// Basic usage with default cache
310
function App() {
311
  return (
312
    <TssCacheProvider>
313
      <MyAppComponents />
314
    </TssCacheProvider>
315
  );
316
}
317

318
// Custom cache configuration
319
const customCache = createCache({
320
  key: "my-app",
321
  prepend: true, // Insert styles at beginning of head
322
  speedy: process.env.NODE_ENV === "production"
323
});
324

325
function AppWithCustomCache() {
326
  return (
327
    <TssCacheProvider value={customCache}>
328
      <MyAppComponents />
329
    </TssCacheProvider>
330
  );
331
}
332

333
// SSR setup with cache provider
334
import { CacheProvider } from "@emotion/react";
335

336
function ServerApp({ cache }: { cache: EmotionCache }) {
337
  return (
338
    <CacheProvider value={cache}>
339
      <TssCacheProvider>
340
        <MyAppComponents />
341
      </TssCacheProvider>
342
    </CacheProvider>
343
  );
344
}
345
```
346

347
## Types
348

349
```typescript { .api }
350
interface CSSObject extends CSSObject_base {
351
  label?: string;
352
}
353

354
interface Css {
355
  (template: TemplateStringsArray, ...args: CSSInterpolation[]): string;
356
  (...args: CSSInterpolation[]): string;
357
}
358

359
type Cx = (...classNames: CxArg[]) => string;
360

361
type CxArg = 
362
  | string 
363
  | number 
364
  | boolean 
365
  | undefined 
366
  | null 
367
  | { [className: string]: boolean | undefined | null };
368

369
type CSSInterpolation = CSSObject | string | number | false | null | undefined;
370
```