0
# Radium
1

2
Radium is a React library that enables CSS-in-JS styling by managing inline styles on React elements. It provides powerful styling capabilities without traditional CSS, including browser state handling (:hover, :focus, :active), media queries, automatic vendor prefixing, and keyframe animations.
3

4
## Package Information
5

6
- **Package Name**: radium
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install radium`
10
- **Peer Dependencies**: React ^16.8.0 || ^17.0.0
11

12
## Core Imports
13

14
```javascript
15
import Radium from 'radium';
16
import { Plugins, Style, StyleRoot, getState, keyframes } from 'radium';
17
```
18

19
For CommonJS:
20

21
```javascript
22
const Radium = require('radium');
23
const { Plugins, Style, StyleRoot, getState, keyframes } = require('radium');
24
```
25

26
## Basic Usage
27

28
```javascript
29
import Radium from 'radium';
30
import React from 'react';
31

32
class Button extends React.Component {
33
  render() {
34
    return (
35
      <button style={[styles.base, styles[this.props.kind]]}>
36
        {this.props.children}
37
      </button>
38
    );
39
  }
40
}
41

42
Button = Radium(Button);
43

44
const styles = {
45
  base: {
46
    color: '#fff',
47
    backgroundColor: '#0074d9',
48
    border: 0,
49
    borderRadius: '0.3em',
50
    padding: '0.4em 1em',
51
    
52
    ':hover': {
53
      backgroundColor: '#0088FF'
54
    },
55
    
56
    ':focus': {
57
      backgroundColor: '#0088FF'
58
    },
59
    
60
    '@media (min-width: 992px)': {
61
      padding: '0.6em 1.2em'
62
    }
63
  },
64
  
65
  primary: {
66
    backgroundColor: '#0074d9'
67
  }
68
};
69
```
70

71
## Architecture
72

73
Radium is built around several key components:
74

75
- **Higher-Order Component (HOC)**: The main `Radium()` function wraps React components to enable enhanced styling
76
- **Plugin System**: Modular architecture where styling features are implemented as plugins
77
- **Style Processing**: Runtime style resolution through a plugin chain
78
- **Context System**: React Context for sharing configuration and style management
79
- **Style Management**: Global style injection for keyframes and media queries
80

81
## Capabilities
82

83
### Component Enhancement
84

85
Core higher-order component that wraps React components to enable Radium's styling features.
86

87
```javascript { .api }
88
function Radium(component: React.Component, config?: RadiumConfig): React.Component;
89

90
interface RadiumConfig {
91
  matchMedia?: (query: string) => MediaQueryList;
92
  plugins?: Plugin[];
93
  userAgent?: string;
94
}
95
```
96

97
[Component Enhancement](./component-enhancement.md)
98

99
### Style Components
100

101
React components for rendering CSS rules and managing global styles.
102

103
```javascript { .api }
104
// Style component for rendering CSS rules
105
const Style: React.ComponentType<{
106
  rules: object;
107
  scopeSelector?: string;
108
  radiumConfig?: RadiumConfig;
109
}>;
110

111
// StyleRoot component for global style management
112
const StyleRoot: React.ComponentType<{
113
  children: React.ReactNode;
114
  radiumConfig?: RadiumConfig;
115
}>;
116
```
117

118
[Style Components](./style-components.md)
119

120
### State Management
121

122
Utilities for managing and querying component browser state.
123

124
```javascript { .api }
125
function getState(
126
  state: object,
127
  elementKey: string,
128
  value: ':hover' | ':focus' | ':active'
129
): boolean;
130
```
131

132
[State Management](./state-management.md)
133

134
### Keyframe Animations
135

136
System for creating and managing CSS keyframe animations.
137

138
```javascript { .api }
139
function keyframes(
140
  keyframeRules: { [percentage: string]: object },
141
  name?: string
142
): KeyframesObject;
143

144
interface KeyframesObject {
145
  __radiumKeyframes: boolean;
146
  __process(userAgent?: string): { animationName: string; css: string };
147
}
148
```
149

150
[Keyframe Animations](./keyframes.md)
151

152
### Plugin System
153

154
Extensible plugin architecture for customizing Radium's behavior.
155

156
```javascript { .api }
157
interface Plugin {
158
  (config: PluginConfig): PluginResult | void;
159
}
160

161
interface PluginConfig {
162
  componentName: string;
163
  config: RadiumConfig;
164
  props: object;
165
  style: object;
166
  addCSS: (css: string) => { remove: () => void };
167
  getState: (stateKey: string, elementKey?: string) => any;
168
  setState: (stateKey: string, value: any, elementKey?: string) => void;
169
}
170

171
interface PluginResult {
172
  componentFields?: object;
173
  globalState?: object;
174
  props?: object;
175
  style?: object;
176
}
177
```
178

179
[Plugin System](./plugins.md)
180

181
### Test Utilities
182

183
Development-only utilities for testing and debugging Radium components.
184

185
```javascript { .api }
186
// Available only in development builds (NODE_ENV !== 'production')
187
interface TestMode {
188
  /** Clear all global Radium state */
189
  clearState(): void;
190
  /** Enable test mode (reduces warnings/errors) */
191
  enable(): void;
192
  /** Disable test mode */
193
  disable(): void;
194
}
195

196
// Access via Radium.TestMode in development
197
const testMode: TestMode | undefined;
198
```
199

200
## Types
201

202
```javascript { .api }
203
interface RadiumConfig {
204
  /** Custom matchMedia implementation for server rendering */
205
  matchMedia?: (query: string) => MediaQueryList;
206
  /** Array of plugins to use (replaces defaults) */
207
  plugins?: Plugin[];
208
  /** User agent string for vendor prefixing */
209
  userAgent?: string;
210
}
211

212
interface MediaQueryList {
213
  matches: boolean;
214
  addListener(listener: (mql: MediaQueryList) => void): void;
215
  removeListener(listener: (mql: MediaQueryList) => void): void;
216
}
217
```