0
# Root Provider
1

2
The RecoilRoot component manages the Recoil state graph and provides the context for all Recoil hooks. Most Recoil functionality requires components to be nested inside a RecoilRoot.
3

4
## Capabilities
5

6
### RecoilRoot Component
7

8
Root component that manages Recoil state for all child components.
9

10
```typescript { .api }
11
/**
12
 * Root component for managing Recoil state. Most Recoil hooks should be
13
 * called from a component nested in a <RecoilRoot>
14
 */
15
const RecoilRoot: React.FC<RecoilRootProps>;
16

17
type RecoilRootProps = {
18
  /** Function to initialize state when the root is created */
19
  initializeState?: (mutableSnapshot: MutableSnapshot) => void;
20
  /** Allow overriding an existing RecoilRoot */
21
  override?: true;
22
  children: React.ReactNode;
23
} | {
24
  /** Disable override, preventing nested RecoilRoots */
25
  override: false;
26
  children: React.ReactNode;
27
};
28
```
29

30
**Usage Examples:**
31

32
```typescript
33
import React from 'react';
34
import { RecoilRoot, atom } from 'recoil';
35

36
// Basic usage
37
function App() {
38
  return (
39
    <RecoilRoot>
40
      <MyComponent />
41
    </RecoilRoot>
42
  );
43
}
44

45
// With state initialization
46
const userState = atom({
47
  key: 'userState',
48
  default: null,
49
});
50

51
function AppWithInitialization() {
52
  return (
53
    <RecoilRoot
54
      initializeState={({set}) => {
55
        set(userState, {id: 1, name: 'John'});
56
      }}
57
    >
58
      <MyComponent />
59
    </RecoilRoot>
60
  );
61
}
62

63
// Override existing root
64
function NestedApp() {
65
  return (
66
    <RecoilRoot override={true}>
67
      <ChildComponent />
68
    </RecoilRoot>
69
  );
70
}
71
```
72

73
### Store ID Management
74

75
Hook for accessing the unique identifier of the current RecoilRoot store.
76

77
```typescript { .api }
78
/**
79
 * Returns an ID for the currently active state store of the host <RecoilRoot>
80
 */
81
function useRecoilStoreID(): StoreID;
82

83
interface StoreID {
84
  readonly [StoreID_OPAQUE]: true;
85
}
86
```
87

88
**Usage Examples:**
89

90
```typescript
91
import { useRecoilStoreID } from 'recoil';
92

93
function StoreInfo() {
94
  const storeID = useRecoilStoreID();
95
  
96
  // Use store ID for debugging or store coordination
97
  console.log('Current store ID:', storeID);
98
  
99
  return <div>Store: {JSON.stringify(storeID)}</div>;
100
}
101
```
102

103
### Cross-Root Bridge
104

105
Experimental hook for sharing state across multiple React roots.
106

107
```typescript { .api }
108
/**
109
 * Returns a component that acts like a <RecoilRoot> but shares the same store
110
 * as the current <RecoilRoot>
111
 */
112
function useRecoilBridgeAcrossReactRoots_UNSTABLE(): typeof RecoilBridge;
113

114
const RecoilBridge: React.FC<{children: React.ReactNode}>;
115
```
116

117
**Usage Examples:**
118

119
```typescript
120
import { useRecoilBridgeAcrossReactRoots_UNSTABLE } from 'recoil';
121
import { createRoot } from 'react-dom/client';
122

123
function MainApp() {
124
  const RecoilBridge = useRecoilBridgeAcrossReactRoots_UNSTABLE();
125
  
126
  // Create a new React root that shares Recoil state
127
  React.useEffect(() => {
128
    const container = document.getElementById('portal');
129
    const root = createRoot(container);
130
    
131
    root.render(
132
      <RecoilBridge>
133
        <PortalContent />
134
      </RecoilBridge>
135
    );
136
  }, [RecoilBridge]);
137
  
138
  return <div>Main App Content</div>;
139
}
140
```
141

142
### Environment Configuration
143

144
Global environment settings for configuring Recoil behavior.
145

146
```typescript { .api }
147
interface RecoilEnv {
148
  /** Enable checking for duplicate atom keys */
149
  RECOIL_DUPLICATE_ATOM_KEY_CHECKING_ENABLED: boolean;
150
  /** Set of enabled feature flags */
151
  RECOIL_GKS_ENABLED: Set<string>;
152
}
153

154
const RecoilEnv: RecoilEnv;
155
```
156

157
**Usage Examples:**
158

159
```typescript
160
import { RecoilEnv } from 'recoil';
161

162
// Enable duplicate key checking (typically for development)
163
RecoilEnv.RECOIL_DUPLICATE_ATOM_KEY_CHECKING_ENABLED = true;
164

165
// Enable specific feature flags
166
RecoilEnv.RECOIL_GKS_ENABLED.add('recoil_memory_managament_2020');
167
```