0
# Styletron React
1

2
Styletron React provides React bindings for Styletron, a CSS-in-JS toolkit that enables component-oriented styling with atomic CSS generation. It offers styled components through a chainable API, enabling developers to create styled components with prop interfaces for conditional and dynamic styling.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { styled, Provider, useStyletron, type StyletronComponent } from "styletron-react";
15
import type { StyleObject } from "styletron-standard";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { styled, Provider, useStyletron } = require("styletron-react");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import React from "react";
28
import { styled, Provider } from "styletron-react";
29
import { Client } from "styletron-engine-atomic";
30

31
// Initialize Styletron engine
32
const engine = new Client();
33

34
// Create styled components
35
const Button = styled("button", {
36
  backgroundColor: "blue",
37
  color: "white",
38
  padding: "8px 16px",
39
  border: "none",
40
  borderRadius: "4px",
41
});
42

43
// Dynamic styling based on props
44
const DynamicButton = styled("button", (props: {$primary: boolean}) => ({
45
  backgroundColor: props.$primary ? "blue" : "gray",
46
  color: "white",
47
  padding: "8px 16px",
48
}));
49

50
function App() {
51
  return (
52
    <Provider value={engine}>
53
      <Button>Static Button</Button>
54
      <DynamicButton $primary={true}>Primary Button</DynamicButton>
55
    </Provider>
56
  );
57
}
58
```
59

60
## Architecture
61

62
Styletron React is built around several key components:
63

64
- **Styled Function**: Primary API for creating styled React components with static or dynamic styles
65
- **Composition Utilities**: Functions to extend and modify existing styled components (`withStyle`, `withTransform`, `withWrapper`)
66
- **Context System**: Provider component that supplies the Styletron engine to all styled components
67
- **Hooks API**: `useStyletron` hook for direct CSS class generation within functional components
68
- **Development Tools**: Debug engine and devtools integration for development mode
69

70
## Capabilities
71

72
### Core Styling
73

74
Primary styling functionality for creating styled React components with both static and dynamic styles.
75

76
```typescript { .api }
77
function styled<T extends React.ElementType, Props extends {}>(
78
  component: T,
79
  style: StyleObject | ((props: Props) => StyleObject)
80
): StyletronComponent<T, Props>;
81
```
82

83
[Core Styling](./core-styling.md)
84

85
### Component Composition
86

87
Utilities for extending and modifying existing styled components with additional styles and transformations.
88

89
```typescript { .api }
90
function withStyle<Base extends StyletronComponent<any, any>, Props = {}>(
91
  component: Base,
92
  style: StyleObject | ((props: Props) => StyleObject)
93
): StyletronComponent<any, any>;
94

95
function withTransform<Base extends StyletronComponent<any, any>, Props>(
96
  component: Base,
97
  style: (style: StyleObject, props: Props) => StyleObject
98
): StyletronComponent<any, any>;
99

100
function withWrapper<Base extends StyletronComponent<any, any>, Props>(
101
  component: Base,
102
  wrapper: (component: Base) => React.ComponentType<Props>
103
): StyletronComponent<any, any>;
104
```
105

106
[Component Composition](./component-composition.md)
107

108
### React Hooks
109

110
Hook-based API for direct CSS class generation and integration with React functional components.
111

112
```typescript { .api }
113
function useStyletron(): [(style: StyleObject) => string];
114
```
115

116
[React Hooks](./react-hooks.md)
117

118
### Context and Provider
119

120
Context system for providing Styletron engine instances to styled components throughout the React component tree.
121

122
```typescript { .api }
123
const Provider: React.ComponentType<{
124
  children: React.ReactNode;
125
  value: StandardEngine;
126
  debugAfterHydration?: boolean;
127
  debug?: any;
128
}>;
129
```
130

131
[Context and Provider](./context-provider.md)
132

133
## Core Types
134

135
```typescript { .api }
136
interface StyletronComponent<D extends React.ElementType, P extends {}> {
137
  <C extends React.ElementType = D>(
138
    props: {
139
      $as?: C;
140
    } & OverrideProps<C, P>
141
  ): JSX.Element;
142
  __STYLETRON__: any;
143
  displayName?: string;
144
}
145

146
type StyletronProps<Props = {}> = Partial<{
147
  $style: StyleObject | ((props: Props) => StyleObject);
148
  $as: React.ComponentType<any> | keyof JSX.IntrinsicElements;
149
  className: string;
150
  /** @deprecated Use ref instead */
151
  $ref: Props extends {ref?: infer T} ? T : React.Ref<any>;
152
  ref: Props extends {ref?: infer T} ? T : React.Ref<any>;
153
}>;
154

155
type StyleObject = {
156
  [property: string]: string | number | StyleObject;
157
  // Supports pseudo-selectors and media queries
158
  ":hover"?: StyleObject;
159
  ":focus"?: StyleObject;
160
  ":active"?: StyleObject;
161
  "@media (max-width: 768px)"?: StyleObject;
162
  // ... other CSS properties, pseudo-selectors, and media queries
163
};
164
```