0
# State Management
1

2
Utilities for managing and querying component browser state such as hover, focus, and active states.
3

4
## Capabilities
5

6
### getState Function
7

8
Queries Radium's internal state to determine if an element is in a particular browser state.
9

10
```javascript { .api }
11
/**
12
 * Query Radium's knowledge of element browser state
13
 * @param state - Component state object (typically this.state)
14
 * @param elementKey - Element identifier (key or ref attribute)
15
 * @param value - State to check (':hover', ':focus', or ':active')
16
 * @returns true if element is in the specified state, false otherwise
17
 */
18
function getState(
19
  state: object,
20
  elementKey: string,
21
  value: ':hover' | ':focus' | ':active'
22
): boolean;
23
```
24

25
**Usage Examples:**
26

27
```javascript
28
import Radium, { getState } from 'radium';
29

30
class InteractiveComponent extends React.Component {
31
  render() {
32
    const isButtonHovered = getState(this.state, 'myButton', ':hover');
33
    
34
    return (
35
      <div>
36
        <button
37
          key="myButton"
38
          style={[
39
            styles.button,
40
            isButtonHovered && styles.buttonHovered
41
          ]}
42
        >
43
          Click me
44
        </button>
45
        
46
        {isButtonHovered && (
47
          <div style={styles.tooltip}>
48
            Button is being hovered!
49
          </div>
50
        )}
51
      </div>
52
    );
53
  }
54
}
55

56
InteractiveComponent = Radium(InteractiveComponent);
57

58
const styles = {
59
  button: {
60
    padding: '10px 20px',
61
    ':hover': {} // Required to track hover state
62
  },
63
  tooltip: {
64
    position: 'absolute',
65
    background: 'black',
66
    color: 'white',
67
    padding: '5px'
68
  }
69
};
70
```
71

72
### State Tracking Requirements
73

74
For `getState` to work properly, the target element must have the corresponding state defined in its style object, even if empty.
75

76
```javascript { .api }
77
interface StateTrackingStyle {
78
  ':hover'?: object;
79
  ':focus'?: object;
80
  ':active'?: object;
81
}
82
```
83

84
**Usage Examples:**
85

86
```javascript
87
// Required: Define states you want to track
88
const trackingStyles = {
89
  base: {
90
    padding: '10px',
91
    // These enable state tracking
92
    ':hover': {},
93
    ':focus': {},
94
    ':active': {}
95
  }
96
};
97

98
// Then you can query these states
99
const isHovered = getState(this.state, 'elementKey', ':hover');
100
const isFocused = getState(this.state, 'elementKey', ':focus');
101
const isActive = getState(this.state, 'elementKey', ':active');
102
```
103

104
### Element Identification
105

106
Elements are identified using their `key` or `ref` attributes. If neither is provided, 'main' is used as the default key.
107

108
```javascript { .api }
109
interface ElementIdentification {
110
  /** Using key attribute */
111
  key: string;
112
  /** Or using ref attribute */
113
  ref: string;
114
  /** Default key when neither key nor ref is provided */
115
  defaultKey: 'main';
116
}
117
```
118

119
**Usage Examples:**
120

121
```javascript
122
// Using key attribute
123
<button key="submitButton" style={styles.button}>
124
  Submit
125
</button>
126
const isSubmitHovered = getState(this.state, 'submitButton', ':hover');
127

128
// Using ref attribute
129
<input ref="emailInput" style={styles.input} />
130
const isEmailFocused = getState(this.state, 'emailInput', ':focus');
131

132
// Default key (when no key or ref provided)
133
<div style={styles.container}>Content</div>
134
const isMainHovered = getState(this.state, 'main', ':hover');
135
```
136

137
### Cross-Element State Dependencies
138

139
Use `getState` to create styles that depend on the state of other elements.
140

141
**Usage Examples:**
142

143
```javascript
144
class CrossElementExample extends React.Component {
145
  render() {
146
    const isMenuHovered = getState(this.state, 'menu', ':hover');
147
    
148
    return (
149
      <div>
150
        <nav
151
          key="menu"
152
          style={[
153
            styles.menu,
154
            isMenuHovered && styles.menuExpanded
155
          ]}
156
        >
157
          <ul style={styles.menuList}>
158
            <li>Item 1</li>
159
            <li>Item 2</li>
160
          </ul>
161
        </nav>
162
        
163
        <div style={[
164
          styles.content,
165
          isMenuHovered && styles.contentShifted
166
        ]}>
167
          Main content area
168
        </div>
169
      </div>
170
    );
171
  }
172
}
173

174
const styles = {
175
  menu: {
176
    width: '200px',
177
    transition: 'width 0.3s',
178
    ':hover': {} // Enable hover tracking
179
  },
180
  menuExpanded: {
181
    width: '300px'
182
  },
183
  content: {
184
    marginLeft: '200px',
185
    transition: 'margin-left 0.3s'
186
  },
187
  contentShifted: {
188
    marginLeft: '300px'
189
  }
190
};
191
```
192

193
### Lifecycle Integration
194

195
`getState` can be used in component lifecycle methods for state-dependent logic.
196

197
**Usage Examples:**
198

199
```javascript
200
class LifecycleExample extends React.Component {
201
  componentDidUpdate(prevProps, prevState) {
202
    const wasHovered = getState(prevState, 'button', ':hover');
203
    const isHovered = getState(this.state, 'button', ':hover');
204
    
205
    if (!wasHovered && isHovered) {
206
      // Element just became hovered
207
      this.onHoverStart();
208
    } else if (wasHovered && !isHovered) {
209
      // Element is no longer hovered
210
      this.onHoverEnd();
211
    }
212
  }
213
  
214
  shouldComponentUpdate(nextProps, nextState) {
215
    const currentHover = getState(this.state, 'button', ':hover');
216
    const nextHover = getState(nextState, 'button', ':hover');
217
    
218
    // Only update if hover state changed
219
    return currentHover !== nextHover;
220
  }
221
}
222
```
223

224
## Limitations
225

226
- **Stateless Components**: `getState` cannot be used in stateless components since they don't have access to Radium's internal state
227
- **State Definition**: Target elements must have the queried state defined in their style object
228
- **Element Keys**: Elements must have unique `key` or `ref` attributes for identification
229

230
## Types
231

232
```javascript { .api }
233
/**
234
 * Valid state values for querying
235
 */
236
type StateValue = ':hover' | ':focus' | ':active';
237

238
/**
239
 * Element key type - string identifier
240
 */
241
type ElementKey = string;
242

243
/**
244
 * Component state object containing Radium's internal state
245
 */
246
interface RadiumState {
247
  _radiumStyleState: {
248
    [elementKey: string]: {
249
      [stateValue: string]: boolean;
250
    };
251
  };
252
}
253
```