0
# Compatibility Mode
1

2
TSS-React provides compatibility layers and alternative implementations for specific use cases and migration scenarios. These exports provide enhanced compatibility with certain environments or legacy code patterns.
3

4
## Capabilities
5

6
### Compatibility Mode Entry Point
7

8
The `tss-react/compat` export provides the same API as the main entry point but uses an alternative withStyles implementation for enhanced compatibility.
9

10
```typescript { .api }
11
// Import from tss-react/compat
12
import { 
13
  createTss, 
14
  createMakeStyles, 
15
  createWithStyles, 
16
  createMakeAndWithStyles,
17
  tss,
18
  useStyles,
19
  TssCacheProvider,
20
  GlobalStyles,
21
  keyframes
22
} from "tss-react/compat";
23

24
// Same types as main entry point
25
import type { 
26
  CSSInterpolation, 
27
  CSSObject, 
28
  Css, 
29
  Cx, 
30
  CxArg, 
31
  Tss 
32
} from "tss-react/compat";
33
```
34

35
**Usage Example:**
36

37
```typescript
38
import { createWithStyles } from "tss-react/compat";
39
import { useTheme } from "@mui/material/styles";
40

41
const { withStyles } = createWithStyles({ useTheme });
42

43
// Compatible withStyles implementation
44
const StyledComponent = withStyles(MyComponent, (theme, props) => ({
45
  root: {
46
    backgroundColor: theme.palette.background.paper,
47
    padding: theme.spacing(2)
48
  }
49
}));
50
```
51

52
### Combined Factory Function
53

54
Creates both makeStyles and withStyles functions together with a shared cache provider.
55

56
```typescript { .api }
57
/**
58
 * Creates makeStyles and withStyles functions with shared configuration
59
 * @param params Configuration object with theme hook and optional cache
60
 * @returns Object containing makeStyles, withStyles, and TssCacheProvider
61
 */
62
function createMakeAndWithStyles<Theme>(params: {
63
  useTheme: () => Theme;
64
  cache?: EmotionCache;
65
}): {
66
  makeStyles: MakeStylesFunction<Theme>;
67
  withStyles: WithStylesFunction<Theme>;
68
  TssCacheProvider: React.ComponentType<{ children: ReactNode }>;
69
};
70
```
71

72
**Usage Example:**
73

74
```typescript
75
import { createMakeAndWithStyles } from "tss-react";
76
import { useTheme } from "@mui/material/styles";
77

78
const { makeStyles, withStyles, TssCacheProvider } = createMakeAndWithStyles({
79
  useTheme
80
});
81

82
// Use both APIs with consistent theming
83
const useStyles = makeStyles((theme) => ({
84
  container: {
85
    backgroundColor: theme.palette.background.default,
86
    padding: theme.spacing(3)
87
  }
88
}));
89

90
const StyledButton = withStyles("button", (theme) => ({
91
  root: {
92
    backgroundColor: theme.palette.primary.main,
93
    color: theme.palette.primary.contrastText
94
  }
95
}));
96

97
function App() {
98
  return (
99
    <TssCacheProvider>
100
      <MyComponents />
101
    </TssCacheProvider>
102
  );
103
}
104
```
105

106
### MUI Compatibility Mode
107

108
Pre-configured MUI integration using compatibility mode withStyles implementation.
109

110
```typescript { .api }
111
// Import from tss-react/mui-compat
112
import { makeStyles, withStyles, tss, useStyles } from "tss-react/mui-compat";
113

114
/**
115
 * MUI-compatible makeStyles using compatibility layer
116
 */
117
const makeStyles: MakeStylesFunction<Theme>;
118

119
/**
120
 * MUI-compatible withStyles using compatibility layer
121
 */
122
const withStyles: WithStylesFunction<Theme>;
123

124
/**
125
 * Pre-configured TSS instance (same as tss-react/mui)
126
 */
127
const tss: Tss<{ theme: Theme }, {}, never, MuiThemeStyleOverridesPluginParams, never>;
128

129
/**
130
 * Default useStyles hook (same as tss-react/mui)
131
 */
132
const useStyles: UseStyles<{ theme: Theme }, {}, string, MuiThemeStyleOverridesPluginParams>;
133
```
134

135
**Usage Example:**
136

137
```typescript
138
import { makeStyles, withStyles } from "tss-react/mui-compat";
139
import { Button } from "@mui/material";
140

141
// Compatible makeStyles for migration scenarios
142
const useStyles = makeStyles((theme) => ({
143
  customButton: {
144
    backgroundColor: theme.palette.secondary.main,
145
    "&:hover": {
146
      backgroundColor: theme.palette.secondary.dark
147
    }
148
  }
149
}));
150

151
// Compatible withStyles for legacy components
152
const StyledButton = withStyles(Button, (theme) => ({
153
  root: {
154
    borderRadius: theme.shape.borderRadius * 2,
155
    textTransform: "none"
156
  }
157
}));
158

159
function MigratedComponent() {
160
  const classes = useStyles();
161
  return (
162
    <div>
163
      <Button className={classes.customButton}>
164
        Migrated Button
165
      </Button>
166
      <StyledButton variant="contained">
167
        Legacy Styled Button
168
      </StyledButton>
169
    </div>
170
  );
171
}
172
```
173

174
## Compatibility Differences
175

176
### WithStyles Implementation
177

178
The compatibility mode uses an alternative withStyles implementation (`withStyles_compat.tsx`) that provides enhanced compatibility for certain edge cases:
179

180
- **Class Component Support**: Better handling of class components with complex inheritance patterns
181
- **Props Forwarding**: Enhanced props forwarding behavior for specific component patterns
182
- **Theme Context**: More robust theme context handling in complex component hierarchies
183

184
```typescript
185
// Standard withStyles
186
import { createWithStyles } from "tss-react";
187

188
// Compatibility withStyles  
189
import { createWithStyles } from "tss-react/compat";
190
```
191

192
### When to Use Compatibility Mode
193

194
Use compatibility mode when:
195

196
1. **Migrating from @material-ui/core v4**: Enhanced compatibility with legacy patterns
197
2. **Complex Component Hierarchies**: Better handling of deeply nested styled components
198
3. **Third-party Component Integration**: More reliable integration with external component libraries
199
4. **SSR Edge Cases**: Additional server-side rendering compatibility
200

201
## Migration Guide
202

203
### From @material-ui/core makeStyles
204

205
```typescript
206
// Before (Material-UI v4)
207
import { makeStyles } from "@material-ui/core/styles";
208

209
// After (TSS-React compatibility)
210
import { makeStyles } from "tss-react/mui-compat";
211

212
// Same API, enhanced compatibility
213
const useStyles = makeStyles((theme) => ({
214
  root: {
215
    backgroundColor: theme.palette.background.paper
216
  }
217
}));
218
```
219

220
### From @material-ui/core withStyles
221

222
```typescript
223
// Before (Material-UI v4)
224
import { withStyles } from "@material-ui/core/styles";
225

226
// After (TSS-React compatibility)
227
import { withStyles } from "tss-react/mui-compat";
228

229
// Enhanced compatibility for complex scenarios
230
const StyledComponent = withStyles(MyComponent, (theme) => ({
231
  root: {
232
    padding: theme.spacing(2)
233
  }
234
}));
235
```
236

237
## Type Definitions
238

239
All compatibility exports use the same type definitions as the main entry point:
240

241
```typescript { .api }
242
// Identical type interfaces
243
interface MakeStylesFunction<Theme> {
244
  <Params = void>(params?: { name?: string; uniqId?: string }): (
245
    cssObjectByRuleNameOrGetCssObjectByRuleName: 
246
      | Record<string, CSSObject>
247
      | ((theme: Theme, params: Params) => Record<string, CSSObject>)
248
  ) => (params: Params) => {
249
    classes: Record<string, string>;
250
    cx: Cx;
251
    css: Css;
252
    theme: Theme;
253
  };
254
}
255

256
interface WithStylesFunction<Theme> {
257
  <Component extends React.ComponentType<any>, Props = ComponentProps<Component>>(
258
    Component: Component,
259
    cssObjectByRuleNameOrGetCssObjectByRuleName:
260
      | Record<string, CSSObject>
261
      | ((theme: Theme, props: Props, classes: Record<string, string>) => Record<string, CSSObject>)
262
  ): ComponentType<Props>;
263
}
264
```
265

266
## Performance Considerations
267

268
Compatibility mode maintains the same performance characteristics as the standard implementation:
269

270
- **Bundle Size**: No significant size difference
271
- **Runtime Performance**: Equivalent performance with additional compatibility checks
272
- **Memory Usage**: Similar memory footprint with enhanced component lifecycle handling
273

274
## Best Practices
275

276
1. **Use Standard Mode First**: Only use compatibility mode when specific compatibility issues are encountered
277
2. **Test Thoroughly**: Verify component behavior when switching between modes
278
3. **Gradual Migration**: Migrate components incrementally rather than switching entire applications at once
279
4. **Monitor Performance**: Profile components after migration to ensure expected performance