0
# Core TSS API
1

2
The TSS (Type-Safe Styles) API is the foundation of tss-react, providing a fluent interface for creating type-safe, dynamic styles with context support and plugin extensibility.
3

4
## Capabilities
5

6
### TSS Factory Function
7

8
Creates a TSS instance with custom context and optional plugin support.
9

10
```typescript { .api }
11
/**
12
 * Creates a TSS instance with context support
13
 * @param params - Configuration object with context provider and optional plugin
14
 * @returns Object containing the configured TSS instance
15
 */
16
function createTss<Context extends Record<string, unknown>>(params: {
17
  useContext: () => Context;
18
  usePlugin?: UsePlugin<Context, any>;
19
}): { tss: Tss<Context, {}, never, {}, never> };
20

21
type UsePlugin<Context, PluginParams> = (params: {
22
  classes: Record<string, string>;
23
  cx: Cx;
24
  css: Css;
25
  name: string | undefined;
26
  idOfUseStyles: string;
27
} & Context & PluginParams) => {
28
  classes?: Record<string, string>;
29
  cx?: Cx;
30
  css?: Css;
31
};
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
import { createTss } from "tss-react";
38

39
// Basic TSS with empty context
40
const { tss } = createTss({
41
  useContext: () => ({})
42
});
43

44
// TSS with theme context
45
const { tss } = createTss({
46
  useContext: () => {
47
    const theme = useMyTheme();
48
    return { theme };
49
  }
50
});
51

52
// TSS with plugin
53
const { tss } = createTss({
54
  useContext: () => ({ theme: useTheme() }),
55
  usePlugin: myCustomPlugin
56
});
57
```
58

59
### TSS Instance Interface
60

61
The main TSS interface providing chainable methods for configuration and style creation.
62

63
```typescript { .api }
64
interface Tss<
65
  Context extends Record<string, unknown>,
66
  Params extends Record<string, unknown>,
67
  RuleNameSubsetReferencableInNestedSelectors extends string,
68
  PluginParams extends Record<string, unknown>,
69
  ExcludedMethod extends "withParams" | "withName" | "withNestedSelectors" = never
70
> {
71
  /**
72
   * Creates a useStyles hook from CSS object or function
73
   * @param cssObjectByRuleNameOrGetCssObjectByRuleName - CSS rules definition
74
   * @returns React hook for generating styles
75
   */
76
  create<RuleName extends string>(
77
    cssObjectByRuleNameOrGetCssObjectByRuleName: CssObjectByRuleNameOrGetCssObjectByRuleName<
78
      Context,
79
      Params,
80
      RuleNameSubsetReferencableInNestedSelectors,
81
      RuleName
82
    >
83
  ): UseStyles<Context, Params, RuleName, PluginParams>;
84

85
  /**
86
   * Adds parameter typing to TSS instance
87
   * @returns New TSS instance with parameter support
88
   */
89
  withParams<NewParams extends Record<string, unknown>>(): Tss<
90
    Context,
91
    NewParams,
92
    RuleNameSubsetReferencableInNestedSelectors,
93
    PluginParams,
94
    ExcludedMethod | "withParams"
95
  >;
96

97
  /**
98
   * Adds component name for debugging and theme overrides
99
   * @param name - Component name or wrapped name object
100
   * @returns New TSS instance with name
101
   */
102
  withName(
103
    name: string | Record<string, unknown>
104
  ): Tss<
105
    Context,
106
    Params,
107
    RuleNameSubsetReferencableInNestedSelectors,
108
    PluginParams,
109
    ExcludedMethod | "withName"
110
  >;
111

112
  /**
113
   * Enables type-safe nested selectors
114
   * @returns New TSS instance with nested selector support
115
   */
116
  withNestedSelectors<NewRuleNameSubset extends string>(): Tss<
117
    Context,
118
    Params,
119
    NewRuleNameSubset,
120
    PluginParams,
121
    ExcludedMethod | "withNestedSelectors"
122
  >;
123
}
124
```
125

126
### CSS Object Definition Types
127

128
Types for defining CSS rules with functions and static objects.
129

130
```typescript { .api }
131
type CssObjectByRuleNameOrGetCssObjectByRuleName<
132
  Context,
133
  Params,
134
  RuleNameSubsetReferencableInNestedSelectors,
135
  RuleName extends string
136
> = 
137
  | Record<RuleName, CSSObject>
138
  | ((context: Context, params: Params, classes: Record<RuleNameSubsetReferencableInNestedSelectors, string>) => Record<RuleName, CSSObject>);
139

140
interface CSSObject {
141
  [property: string]: any;
142
  label?: string;
143
}
144
```
145

146
### UseStyles Hook Type
147

148
The return type of `tss.create()` providing the styles hook interface.
149

150
```typescript { .api }
151
type UseStyles<Context, Params, RuleName extends string, PluginParams> = 
152
  Params extends Record<string, never>
153
    ? () => {
154
        classes: Record<RuleName, string>;
155
        cx: Cx;
156
        css: Css;
157
        theme: Context extends { theme: infer Theme } ? Theme : never;
158
      }
159
    : (params: Params) => {
160
        classes: Record<RuleName, string>;
161
        cx: Cx;
162
        css: Css;
163
        theme: Context extends { theme: infer Theme } ? Theme : never;
164
      };
165
```
166

167
**Usage Examples:**
168

169
```typescript
170
import { createTss } from "tss-react";
171

172
const { tss } = createTss({
173
  useContext: () => ({ theme: { primaryColor: "blue" } })
174
});
175

176
// Static styles
177
const useStyles = tss.create({
178
  root: {
179
    backgroundColor: "white",
180
    padding: 16
181
  },
182
  button: {
183
    color: "blue",
184
    "&:hover": {
185
      color: "darkblue"
186
    }
187
  }
188
});
189

190
// Dynamic styles with parameters
191
const useStylesWithParams = tss
192
  .withParams<{ isActive: boolean; size: "small" | "large" }>()
193
  .create(({ theme }, { isActive, size }) => ({
194
    root: {
195
      backgroundColor: isActive ? theme.primaryColor : "gray",
196
      padding: size === "small" ? 8 : 16
197
    }
198
  }));
199

200
// With component name for debugging
201
const useNamedStyles = tss
202
  .withName("MyComponent")
203
  .create({
204
    root: { color: "red" }
205
  });
206

207
// With nested selectors
208
const useNestedStyles = tss
209
  .withNestedSelectors<"root" | "button">()
210
  .create(({}, {}, classes) => ({
211
    root: { 
212
      padding: 16,
213
      [`& .${classes.button}`]: {
214
        marginTop: 8
215
      }
216
    },
217
    button: { 
218
      backgroundColor: "blue" 
219
    }
220
  }));
221

222
// Usage in components
223
function MyComponent({ isActive }: { isActive: boolean }) {
224
  const { classes, cx, css, theme } = useStylesWithParams({ 
225
    isActive, 
226
    size: "large" 
227
  });
228
  
229
  return (
230
    <div className={classes.root}>
231
      <button className={cx(classes.button, css({ border: "1px solid red" }))}>
232
        Click me
233
      </button>
234
    </div>
235
  );
236
}
237
```
238

239
### Default TSS Instance
240

241
TSS-React provides a default TSS instance for immediate use without setup.
242

243
```typescript { .api }
244
const tss: Tss<{}, {}, never, {}, never>;
245
const useStyles: UseStyles<{}, {}, string, {}>;
246
```
247

248
**Usage Examples:**
249

250
```typescript
251
import { tss, useStyles } from "tss-react";
252

253
// Using the default instance
254
const useButtonStyles = tss.create({
255
  root: {
256
    backgroundColor: "blue",
257
    color: "white",
258
    padding: "8px 16px",
259
    border: "none",
260
    borderRadius: 4,
261
    cursor: "pointer"
262
  }
263
});
264

265
// Using the default hook (equivalent to tss.create({}))
266
const useEmptyStyles = useStyles;
267
```
268

269
## Advanced Patterns
270

271
### Chaining Methods
272

273
TSS methods can be chained in any order to build up the desired configuration:
274

275
```typescript
276
const useAdvancedStyles = tss
277
  .withName("AdvancedComponent")
278
  .withParams<{ variant: "primary" | "secondary" }>()
279
  .withNestedSelectors<"root" | "icon">()
280
  .create(({ theme }, { variant }, classes) => ({
281
    root: {
282
      backgroundColor: variant === "primary" ? theme.primaryColor : theme.secondaryColor,
283
      [`& .${classes.icon}`]: {
284
        marginRight: 8
285
      }
286
    },
287
    icon: {
288
      fontSize: 16
289
    }
290
  }));
291
```
292

293
### Context Integration
294

295
TSS instances automatically provide context values to style functions:
296

297
```typescript
298
const { tss } = createTss({
299
  useContext: () => {
300
    const theme = useTheme();
301
    const userPreferences = useUserPreferences();
302
    return { theme, userPreferences };
303
  }
304
});
305

306
const useContextStyles = tss.create(({ theme, userPreferences }) => ({
307
  root: {
308
    backgroundColor: theme.colors.background,
309
    fontSize: userPreferences.fontSize,
310
    fontFamily: userPreferences.fontFamily
311
  }
312
}));
313
```