0
# Store Management
1

2
Mantine Spotlight uses a store-based state management system that allows both global and instance-based control over spotlight behavior. This enables programmatic control and supports multiple spotlight instances.
3

4
## Capabilities
5

6
### Creating Spotlight Instances
7

8
Create new spotlight instances with dedicated stores and actions.
9

10
```typescript { .api }
11
/**
12
 * Creates store and actions bundle for a new spotlight instance
13
 * @returns Tuple containing the store and action methods
14
 */
15
function createSpotlight(): readonly [SpotlightStore, SpotlightActions];
16

17
/**
18
 * Creates a new spotlight store instance
19
 * @returns New spotlight store with initial state
20
 */
21
function createSpotlightStore(): SpotlightStore;
22

23
interface SpotlightActions {
24
  /** Opens the spotlight */
25
  open(): void;
26
  /** Closes the spotlight */
27
  close(): void;
28
  /** Toggles the spotlight open/closed state */
29
  toggle(): void;
30
}
31

32
type SpotlightStore = MantineStore<SpotlightState>;
33

34
interface SpotlightState {
35
  /** Whether the spotlight is currently open */
36
  opened: boolean;
37
  /** Index of currently selected action */
38
  selected: number;
39
  /** ID of the actions list element */
40
  listId: string;
41
  /** Current search query */
42
  query: string;
43
  /** Whether the actions list is empty */
44
  empty: boolean;
45
  /** Set of registered action IDs */
46
  registeredActions: Set<string>;
47
}
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
import { createSpotlight, SpotlightRoot } from "@mantine/spotlight";
54

55
// Create a custom spotlight instance
56
function CustomSpotlightComponent() {
57
  const [store, spotlight] = createSpotlight();
58

59
  return (
60
    <div>
61
      <button onClick={spotlight.open}>Open Custom Spotlight</button>
62
      <button onClick={spotlight.close}>Close Custom Spotlight</button>
63
      <button onClick={spotlight.toggle}>Toggle Custom Spotlight</button>
64
      
65
      <SpotlightRoot store={store}>
66
        {/* Spotlight content */}
67
      </SpotlightRoot>
68
    </div>
69
  );
70
}
71
```
72

73
### Using Spotlight State
74

75
Hook into spotlight store state for reactive components.
76

77
```typescript { .api }
78
/**
79
 * Hook to consume spotlight store state
80
 * @param store - The spotlight store to subscribe to
81
 * @returns Current state of the spotlight store
82
 */
83
function useSpotlight(store: SpotlightStore): SpotlightState;
84
```
85

86
**Usage Example:**
87

88
```typescript
89
import { useSpotlight, createSpotlight } from "@mantine/spotlight";
90

91
function SpotlightStatus() {
92
  const [store] = createSpotlight();
93
  const { opened, query, selected } = useSpotlight(store);
94

95
  return (
96
    <div>
97
      <p>Spotlight is {opened ? 'open' : 'closed'}</p>
98
      <p>Current query: {query}</p>
99
      <p>Selected index: {selected}</p>
100
    </div>
101
  );
102
}
103
```
104

105
### Global Spotlight Instance
106

107
Use the pre-configured global spotlight instance for simple implementations.
108

109
```typescript { .api }
110
/** Global spotlight actions object */
111
const spotlight: SpotlightActions;
112

113
/** Global spotlight store instance */
114
const spotlightStore: SpotlightStore;
115

116
/**
117
 * Opens the global spotlight instance
118
 */
119
function openSpotlight(): void;
120

121
/**
122
 * Closes the global spotlight instance
123
 */
124
function closeSpotlight(): void;
125

126
/**
127
 * Toggles the global spotlight instance
128
 */
129
function toggleSpotlight(): void;
130
```
131

132
**Usage Examples:**
133

134
```typescript
135
import { 
136
  spotlight, 
137
  openSpotlight, 
138
  closeSpotlight, 
139
  toggleSpotlight 
140
} from "@mantine/spotlight";
141

142
// Using the global instance
143
function GlobalSpotlightControls() {
144
  return (
145
    <div>
146
      {/* Using the spotlight object */}
147
      <button onClick={spotlight.open}>Open</button>
148
      <button onClick={spotlight.close}>Close</button>
149
      <button onClick={spotlight.toggle}>Toggle</button>
150
      
151
      {/* Or using standalone functions */}
152
      <button onClick={openSpotlight}>Open Global</button>
153
      <button onClick={closeSpotlight}>Close Global</button>
154
      <button onClick={toggleSpotlight}>Toggle Global</button>
155
    </div>
156
  );
157
}
158
```
159

160
### Store Actions (Advanced)
161

162
Internal store actions for advanced use cases and custom implementations.
163

164
```typescript { .api }
165
const spotlightActions: {
166
  /** Opens the spotlight */
167
  open(store: SpotlightStore): void;
168
  /** Closes the spotlight */
169
  close(store: SpotlightStore): void;
170
  /** Toggles the spotlight */
171
  toggle(store: SpotlightStore): void;
172
  /** Updates store state */
173
  updateState(update: (state: SpotlightState) => Partial<SpotlightState>, store: SpotlightStore): void;
174
  /** Sets the selected action index */
175
  setSelectedAction(index: number, store: SpotlightStore): void;
176
  /** Sets the actions list ID */
177
  setListId(id: string, store: SpotlightStore): void;
178
  /** Selects an action by index */
179
  selectAction(index: number, store: SpotlightStore): number;
180
  /** Selects the next action */
181
  selectNextAction(store: SpotlightStore): number;
182
  /** Selects the previous action */
183
  selectPreviousAction(store: SpotlightStore): number;
184
  /** Triggers the currently selected action */
185
  triggerSelectedAction(store: SpotlightStore): void;
186
  /** Registers an action ID */
187
  registerAction(id: string, store: SpotlightStore): () => void;
188
  /** Sets the search query */
189
  setQuery(query: string, store: SpotlightStore): void;
190
  /** Clears the spotlight state */
191
  clearSpotlightState(options: { clearQuery: boolean | undefined }, store: SpotlightStore): void;
192
};
193
```
194

195
**Usage Example:**
196

197
```typescript
198
import { spotlightActions, createSpotlightStore } from "@mantine/spotlight";
199

200
function AdvancedSpotlightControl() {
201
  const store = createSpotlightStore();
202

203
  const handleCustomOpen = () => {
204
    // Set a custom query when opening
205
    spotlightActions.open(store);
206
    spotlightActions.setQuery("help", store);
207
  };
208

209
  const handleSelectFirst = () => {
210
    spotlightActions.selectAction(0, store);
211
  };
212

213
  return (
214
    <div>
215
      <button onClick={handleCustomOpen}>Open with Query</button>
216
      <button onClick={handleSelectFirst}>Select First Action</button>
217
    </div>
218
  );
219
}
220
```
221

222
## Multiple Spotlight Instances
223

224
You can create and manage multiple spotlight instances simultaneously:
225

226
```typescript
227
import { createSpotlight, SpotlightRoot } from "@mantine/spotlight";
228

229
function MultipleSpotlights() {
230
  const [mainStore, mainSpotlight] = createSpotlight();
231
  const [helpStore, helpSpotlight] = createSpotlight();
232

233
  const mainActions = [
234
    { id: "home", label: "Home", onClick: () => navigate("/") },
235
    { id: "settings", label: "Settings", onClick: () => navigate("/settings") },
236
  ];
237

238
  const helpActions = [
239
    { id: "docs", label: "Documentation", onClick: () => window.open("/docs") },
240
    { id: "support", label: "Support", onClick: () => window.open("/support") },
241
  ];
242

243
  return (
244
    <div>
245
      <button onClick={mainSpotlight.open}>Open Main Menu</button>
246
      <button onClick={helpSpotlight.open}>Open Help Menu</button>
247

248
      <SpotlightRoot store={mainStore} shortcut="mod + k">
249
        {/* Main spotlight content */}
250
      </SpotlightRoot>
251

252
      <SpotlightRoot store={helpStore} shortcut="mod + h">
253
        {/* Help spotlight content */}
254
      </SpotlightRoot>
255
    </div>
256
  );
257
}
258
```
259

260
## Store State Management
261

262
The spotlight store maintains internal state that can be observed and modified:
263

264
```typescript
265
import { useSpotlight, createSpotlight, spotlightActions } from "@mantine/spotlight";
266

267
function SpotlightStateManager() {
268
  const [store, spotlight] = createSpotlight();
269
  const state = useSpotlight(store);
270

271
  const setCustomQuery = () => {
272
    spotlightActions.setQuery("custom search", store);
273
  };
274

275
  const clearState = () => {
276
    spotlightActions.clearSpotlightState({ clearQuery: true }, store);
277
  };
278

279
  return (
280
    <div>
281
      <p>State: {JSON.stringify(state, null, 2)}</p>
282
      <button onClick={setCustomQuery}>Set Custom Query</button>
283
      <button onClick={clearState}>Clear State</button>
284
    </div>
285
  );
286
}
287
```