0
# Core Styling
1

2
Primary styling functionality for creating styled React components with both static and dynamic styles. The core styling system provides the `styled` function for creating styled components and utilities for custom styling configurations.
3

4
## Capabilities
5

6
### Styled Function
7

8
Creates styled React components with static or dynamic styles.
9

10
```typescript { .api }
11
/**
12
 * Creates styled React components with static or dynamic styles
13
 * @param component - React element type or component to style (e.g., "div", "button", CustomComponent)
14
 * @param style - Style object or function that returns style object based on props
15
 * @returns StyletronComponent that can be used as a React component
16
 */
17
function styled<T extends React.ElementType, Props extends {}>(
18
  component: T,
19
  style: StyleObject | ((props: Props) => StyleObject)
20
): StyletronComponent<T, Props>;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { styled } from "styletron-react";
27

28
// Static styling
29
const BlueButton = styled("button", {
30
  backgroundColor: "blue",
31
  color: "white",
32
  padding: "8px 16px",
33
  border: "none",
34
  borderRadius: "4px",
35
});
36

37
// Dynamic styling based on props
38
const ConditionalButton = styled("button", (props: {$primary: boolean}) => ({
39
  backgroundColor: props.$primary ? "blue" : "gray",
40
  color: "white",
41
  padding: "8px 16px",
42
  ":hover": {
43
    opacity: 0.8,
44
  },
45
}));
46

47
// Styling custom components
48
const CustomCard = ({ title, children, ...props }) => (
49
  <div {...props}>
50
    <h3>{title}</h3>
51
    {children}
52
  </div>
53
);
54

55
const StyledCard = styled(CustomCard, {
56
  border: "1px solid #ccc",
57
  borderRadius: "8px",
58
  padding: "16px",
59
  boxShadow: "0 2px 4px rgba(0,0,0,0.1)",
60
});
61
```
62

63
### Create Styled Function
64

65
Creates a custom styled function with specific configuration options.
66

67
```typescript { .api }
68
/**
69
 * Creates a custom styled function with specific configuration
70
 * @param options - Configuration object with getInitialStyle, driver, and wrapper functions
71
 * @returns Custom styled function with the provided configuration
72
 */
73
function createStyled(options: {
74
  getInitialStyle: () => StyleObject;
75
  driver: (style: StyleObject, engine: StandardEngine) => string;
76
  wrapper: (component: React.FC<any>) => React.ComponentType<any>;
77
}): StyledFn;
78

79
type StyledFn = {
80
  <T extends React.ElementType, Props extends {}>(
81
    component: T,
82
    style: StyleObject | ((props: Props) => StyleObject)
83
  ): StyletronComponent<T, Props>;
84
};
85
```
86

87
**Usage Example:**
88

89
```typescript
90
import { createStyled, styled } from "styletron-react";
91
import { driver, getInitialStyle } from "styletron-standard";
92

93
// Create custom styled function with wrapper
94
const customStyled = createStyled({
95
  getInitialStyle,
96
  driver,
97
  wrapper: (Component) => (props) => (
98
    <div className="custom-wrapper">
99
      <Component {...props} />
100
    </div>
101
  ),
102
});
103

104
// Use custom styled function
105
const WrappedButton = customStyled("button", {
106
  padding: "8px 16px",
107
  backgroundColor: "green",
108
});
109
```
110

111
## Component Props
112

113
All styled components support the following special props:
114

115
### $style Prop
116

117
Override or extend component styles dynamically.
118

119
```typescript { .api }
120
type $style = StyleObject | ((props: any) => StyleObject);
121
```
122

123
**Usage Examples:**
124

125
```typescript
126
// Static style override
127
<StyledButton $style={{backgroundColor: "red"}}>
128
  Red Button
129
</StyledButton>
130

131
// Dynamic style override
132
<StyledButton $style={(props) => ({
133
  backgroundColor: props.error ? "red" : "blue"
134
})}>
135
  Conditional Button
136
</StyledButton>
137
```
138

139
### $as Prop
140

141
Render the styled component as a different element or component.
142

143
```typescript { .api }
144
type $as = React.ComponentType<any> | keyof JSX.IntrinsicElements;
145
```
146

147
**Usage Examples:**
148

149
```typescript
150
// Render button styles on an anchor element
151
<StyledButton $as="a" href="/link">
152
  Link Button
153
</StyledButton>
154

155
// Render with custom component
156
<StyledButton $as={CustomComponent} customProp="value">
157
  Custom Component Button
158
</StyledButton>
159
```
160

161
### Standard React Props
162

163
All styled components accept standard React props including `className` and `ref`.
164

165
```typescript
166
// Combine with existing className
167
<StyledButton className="additional-class">Button</StyledButton>
168

169
// Forward refs
170
const buttonRef = useRef<HTMLButtonElement>(null);
171
<StyledButton ref={buttonRef}>Button</StyledButton>
172
```
173

174
## Types
175

176
```typescript { .api }
177
interface StyletronComponent<D extends React.ElementType, P extends {}> {
178
  <C extends React.ElementType = D>(
179
    props: {
180
      $as?: C;
181
    } & OverrideProps<C, P>
182
  ): JSX.Element;
183
  __STYLETRON__: any;
184
  displayName?: string;
185
}
186

187
type StyleObject = {
188
  [property: string]: string | number | StyleObject;
189
  // Supports CSS properties and pseudo-selectors/media queries
190
  ":hover"?: StyleObject;
191
  ":focus"?: StyleObject;
192
  ":active"?: StyleObject;
193
  "@media (max-width: 768px)"?: StyleObject;
194
  // ... other CSS properties and selectors
195
};
196

197
type StandardEngine = {
198
  renderStyle: (style: StyleObject) => string;
199
  renderKeyframes: (keyframes: any) => string;
200
  renderFontFace: (fontFace: any) => string;
201
};
202
```