0
# Stitches React
1

2
Stitches React is a CSS-in-JS library that combines performance with developer experience, offering type-safe styling for React components with near-zero runtime overhead. It provides a styled API similar to styled-components but with better performance characteristics, compile-time optimizations, and advanced features like automatic vendor prefixing, responsive design utilities, and color manipulation functions.
3

4
## Package Information
5

6
- **Package Name**: @stitches/react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @stitches/react`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  styled, 
16
  css, 
17
  globalCss, 
18
  keyframes, 
19
  createTheme, 
20
  createStitches, 
21
  defaultThemeMap,
22
  getCssText,
23
  reset
24
} from "@stitches/react";
25
```
26

27
For CommonJS:
28

29
```javascript
30
const { 
31
  styled, 
32
  css, 
33
  globalCss, 
34
  keyframes, 
35
  createTheme, 
36
  createStitches, 
37
  defaultThemeMap,
38
  getCssText,
39
  reset
40
} = require("@stitches/react");
41
```
42

43
## Basic Usage
44

45
```typescript
46
import { styled, css } from "@stitches/react";
47

48
// Create styled components
49
const Button = styled('button', {
50
  backgroundColor: 'blue',
51
  color: 'white',
52
  padding: '12px 16px',
53
  border: 'none',
54
  borderRadius: '4px',
55
  
56
  variants: {
57
    size: {
58
      small: { padding: '8px 12px' },
59
      large: { padding: '16px 24px' }
60
    },
61
    color: {
62
      primary: { backgroundColor: 'blue' },
63
      secondary: { backgroundColor: 'gray' }
64
    }
65
  }
66
});
67

68
// Use the component
69
function App() {
70
  return (
71
    <Button size="large" color="primary">
72
      Click me
73
    </Button>
74
  );
75
}
76

77
// Create CSS classes
78
const buttonClass = css({
79
  padding: '10px',
80
  border: '1px solid black'
81
});
82

83
// Server-side rendering support
84
function getServerSideStyles() {
85
  return getCssText();
86
}
87

88
// Reset styles (useful for testing)
89
function clearStyles() {
90
  reset();
91
}
92
```
93

94
## Architecture
95

96
Stitches React is built around several key components:
97

98
- **Configuration System**: `createStitches()` function for setting up themes, media queries, and utilities
99
- **Styled Components**: React components with type-safe styling and variant support
100
- **CSS Generation**: Atomic CSS class generation with efficient caching and deduplication
101
- **Theme System**: Design token management with type-safe theme references
102
- **Responsive Design**: Built-in media query support with breakpoint configuration
103
- **Server-Side Rendering**: Full SSR support with hydration safety
104

105
## Capabilities
106

107
### Styled Components
108

109
Create React components with CSS-in-JS styling, variants, and responsive design support.
110

111
```typescript { .api }
112
function styled<
113
  Type extends keyof JSX.IntrinsicElements | React.ComponentType<any>,
114
  Composers extends Array<string | React.ComponentType<any> | Function | { [name: string]: unknown }>
115
>(
116
  type: Type,
117
  ...composers: Composers
118
): StyledComponent<Type, StyledComponentProps<Composers>, {}, CSS>;
119

120
interface StyledComponent<Type, Props = {}, Media = {}, CSS = {}> 
121
  extends React.ForwardRefExoticComponent<
122
    ComponentProps<Type> & TransformProps<Props, Media> & { css?: CSS }
123
  > {
124
  // Standard component call
125
  (props: ComponentProps<Type> & TransformProps<Props, Media> & { css?: CSS }): React.ReactElement | null;
126
  
127
  // Polymorphic 'as' prop call
128
  <As extends keyof JSX.IntrinsicElements | React.ComponentType<any>>(
129
    props: ComponentProps<As> & TransformProps<Props, Media> & { as: As; css?: CSS }
130
  ): React.ReactElement | null;
131
  
132
  className: string;
133
  selector: string;
134
  
135
  [$$StyledComponentType]: Type;
136
  [$$StyledComponentProps]: Props;
137
  [$$StyledComponentMedia]: Media;
138
}
139

140
type StyledComponentProps<Composers extends readonly unknown[]> = 
141
  Composers extends readonly [infer First, ...infer Rest]
142
    ? First extends { variants?: infer V }
143
      ? V & StyledComponentProps<Rest>
144
      : StyledComponentProps<Rest>
145
    : {};
146
```
147

148
[Styled Components](./styled-components.md)
149

150
### CSS Class Generation
151

152
Generate CSS classes with variants and compound variants for maximum flexibility.
153

154
```typescript { .api }
155
function css<
156
  Composers extends Array<string | React.ComponentType<any> | Function | { [name: string]: unknown }>
157
>(
158
  ...composers: Composers
159
): CssComponent<'span', StyledComponentProps<Composers>, {}, CSS>;
160

161
interface CssComponent<Type = 'span', Props = {}, Media = {}, CSS = {}> {
162
  (props?: TransformProps<Props, Media> & { css?: CSS } & { [name: string]: any }): 
163
    string & { className: string; selector: string; props: any };
164
  
165
  className: string;
166
  selector: string;
167
  
168
  [$$StyledComponentType]: Type;
169
  [$$StyledComponentProps]: Props;
170
  [$$StyledComponentMedia]: Media;
171
}
172
```
173

174
[CSS Classes](./css-classes.md)
175

176
### Theme Management
177

178
Create and manage design tokens with type-safe theme references and dynamic theme switching.
179

180
```typescript { .api }
181
function createTheme<Theme extends ThemeObject>(
182
  theme: Theme
183
): string & { className: string; selector: string } & ThemeTokens<Theme>;
184

185
function createTheme<Theme extends ThemeObject>(
186
  name: string, 
187
  theme: Theme
188
): string & { className: string; selector: string } & ThemeTokens<Theme>;
189

190
interface ThemeObject {
191
  colors?: { [token: string]: string | number | boolean };
192
  space?: { [token: string]: string | number | boolean };
193
  fontSizes?: { [token: string]: string | number | boolean };
194
  fonts?: { [token: string]: string | number | boolean };
195
  fontWeights?: { [token: string]: string | number | boolean };
196
  lineHeights?: { [token: string]: string | number | boolean };
197
  letterSpacings?: { [token: string]: string | number | boolean };
198
  sizes?: { [token: string]: string | number | boolean };
199
  borderWidths?: { [token: string]: string | number | boolean };
200
  borderStyles?: { [token: string]: string | number | boolean };
201
  radii?: { [token: string]: string | number | boolean };
202
  shadows?: { [token: string]: string | number | boolean };
203
  zIndices?: { [token: string]: string | number | boolean };
204
  transitions?: { [token: string]: string | number | boolean };
205
  [scale: string]: { [token: string]: string | number | boolean };
206
}
207

208
type ThemeTokens<Theme> = {
209
  [Scale in keyof Theme]: {
210
    [Token in keyof Theme[Scale]]: Token extends string | number
211
      ? string & { token: Token; scale: Scale }
212
      : never;
213
  };
214
};
215
```
216

217
[Theme Management](./theme-management.md)
218

219
### Global Styles
220

221
Apply global CSS styles including imports, font faces, and keyframes.
222

223
```typescript { .api }
224
function globalCss(...styles: GlobalStyleObject[]): () => string;
225

226
interface GlobalStyleObject {
227
  '@import'?: string | string[];
228
  '@font-face'?: FontFaceRule | FontFaceRule[];
229
  [selector: string]: any;
230
}
231
```
232

233
[Global Styles](./global-styles.md)
234

235
### Animation Support
236

237
Create CSS animations with keyframes and integrate with theme tokens.
238

239
```typescript { .api }
240
function keyframes(styles: KeyframesObject): KeyframesResult;
241

242
interface KeyframesObject {
243
  [percentage: string]: StyleObject;
244
}
245

246
interface KeyframesResult {
247
  (): string;
248
  name: string;
249
}
250
```
251

252
[Animations](./animations.md)
253

254
### Configuration
255

256
Set up Stitches with custom themes, media queries, utilities, and type mappings.
257

258
```typescript { .api }
259
function createStitches<Config extends StitchesConfig>(
260
  config?: Config
261
): StitchesInstance<Config>;
262

263
interface StitchesConfig {
264
  prefix?: string;
265
  media?: { [name: string]: string };
266
  theme?: ThemeObject;
267
  themeMap?: { [property: string]: keyof ThemeObject };
268
  utils?: { [name: string]: (value: any) => StyleObject };
269
}
270
```
271

272
[Configuration](./configuration.md)
273

274
### Server-Side Rendering Support
275

276
Extract CSS for server-side rendering and hydration safety.
277

278
```typescript { .api }
279
function getCssText(): string;
280
```
281

282
### Style Sheet Management
283

284
Reset generated styles and clear cache.
285

286
```typescript { .api }
287
function reset(): void;
288
```
289

290
## Type System
291

292
```typescript { .api }
293
// Component prop extraction
294
type ComponentProps<Component> = Component extends ((...args: any[]) => any) 
295
  ? Parameters<Component>[0] 
296
  : never;
297

298
// Variant prop extraction
299
type VariantProps<Component extends { [key: string]: any }> = 
300
  Component extends { [$$StyledComponentProps]: infer Props, [$$StyledComponentMedia]: infer Media }
301
    ? TransformProps<Props, Media>
302
    : never;
303

304
// CSS property values with theme support
305
type PropertyValue<Property extends keyof CSSProperties, Config = null> = 
306
  Config extends null 
307
    ? { readonly [K in $$PropertyValue]: Property }
308
    : CSS<Config['media'], Config['theme'], Config['themeMap'], Config['utils']>[Property];
309

310
// Theme scale values
311
type ScaleValue<Scale, Config = null> = 
312
  Config extends null
313
    ? { readonly [K in $$ScaleValue]: Scale }
314
    : Scale extends keyof Config['theme']
315
      ? `$${string & keyof Config['theme'][Scale]}`
316
      : never;
317

318
// Styled component symbols (internal)
319
declare const $$StyledComponentType: unique symbol;
320
declare const $$StyledComponentProps: unique symbol;
321
declare const $$StyledComponentMedia: unique symbol;
322

323
// CSS utility symbols
324
declare const $$PropertyValue: unique symbol;
325
declare const $$ScaleValue: unique symbol;
326
declare const $$ThemeValue: unique symbol;
327

328
// Transform props with responsive variants
329
type TransformProps<Props, Media> = {
330
  [K in keyof Props]: (
331
    | Props[K]
332
    | (
333
      & { [KMedia in `@${keyof Media | 'initial'}`]?: Props[K] }
334
      & { [KMedia in string]: Props[K] }
335
    )
336
  );
337
};
338

339
// CSS properties interface with full variant support
340
interface CSS<Media = {}, Theme = {}, ThemeMap = {}, Utils = {}> {
341
  [property: string]: any;
342
  variants?: {
343
    [name: string]: {
344
      [value: string | number]: CSS<Media, Theme, ThemeMap, Utils>;
345
    };
346
  };
347
  compoundVariants?: Array<{
348
    [variant: string]: any;
349
    css: CSS<Media, Theme, ThemeMap, Utils>;
350
  }>;
351
  defaultVariants?: {
352
    [variant: string]: any;
353
  };
354
}
355

356
// Default theme map
357
declare const defaultThemeMap: DefaultThemeMap;
358

359
interface DefaultThemeMap {
360
  // Space scale mappings
361
  gap: 'space';
362
  gridGap: 'space';
363
  columnGap: 'space';
364
  gridColumnGap: 'space';
365
  rowGap: 'space';
366
  gridRowGap: 'space';
367
  margin: 'space';
368
  marginTop: 'space';
369
  marginRight: 'space';
370
  marginBottom: 'space';
371
  marginLeft: 'space';
372
  padding: 'space';
373
  paddingTop: 'space';
374
  paddingRight: 'space';
375
  paddingBottom: 'space';
376
  paddingLeft: 'space';
377
  top: 'space';
378
  right: 'space';
379
  bottom: 'space';
380
  left: 'space';
381
  
382
  // Color scale mappings
383
  color: 'colors';
384
  backgroundColor: 'colors';
385
  borderColor: 'colors';
386
  
387
  // Size scale mappings
388
  width: 'sizes';
389
  height: 'sizes';
390
  minWidth: 'sizes';
391
  minHeight: 'sizes';
392
  maxWidth: 'sizes';
393
  maxHeight: 'sizes';
394
  
395
  // Typography scale mappings
396
  fontSize: 'fontSizes';
397
  fontFamily: 'fonts';
398
  fontWeight: 'fontWeights';
399
  lineHeight: 'lineHeights';
400
  letterSpacing: 'letterSpacings';
401
  
402
  // Border scale mappings
403
  borderWidth: 'borderWidths';
404
  borderRadius: 'radii';
405
  
406
  // Other scale mappings
407
  boxShadow: 'shadows';
408
  textShadow: 'shadows';
409
  zIndex: 'zIndices';
410
  transition: 'transitions';
411
}
412
```