0
# Mantine Spotlight
1

2
Mantine Spotlight provides command center components for React applications built with the Mantine design system. It enables developers to create keyboard-accessible search overlays that can be triggered with shortcuts (like Ctrl+K), allowing users to quickly find and execute actions within an application.
3

4
## Package Information
5

6
- **Package Name**: @mantine/spotlight
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @mantine/spotlight @mantine/core @mantine/hooks`
10

11
## Core Imports
12

13
```typescript
14
import { Spotlight, spotlight } from "@mantine/spotlight";
15
```
16

17
For individual components:
18

19
```typescript
20
import { 
21
  SpotlightRoot, 
22
  SpotlightSearch, 
23
  SpotlightActionsList,
24
  SpotlightAction,
25
  createSpotlight
26
} from "@mantine/spotlight";
27
```
28

29
CSS imports (required):
30

31
```css
32
/* Standard styles */
33
@import "@mantine/spotlight/styles.css";
34

35
/* Layer styles (alternative) */
36
@import "@mantine/spotlight/styles.layer.css";
37
```
38

39
## Basic Usage
40

41
```typescript
42
import { Spotlight } from "@mantine/spotlight";
43

44
function App() {
45
  const actions = [
46
    {
47
      id: "home",
48
      label: "Home",
49
      description: "Get to home page",
50
      onClick: () => navigate("/"),
51
    },
52
    {
53
      id: "dashboard", 
54
      label: "Dashboard",
55
      description: "Get full information about current system status",
56
      onClick: () => navigate("/dashboard"),
57
    },
58
  ];
59

60
  return (
61
    <div>
62
      <Spotlight
63
        actions={actions}
64
        nothingFound="Nothing found..."
65
        highlightQuery
66
        searchProps={{
67
          placeholder: "Search...",
68
          leftSection: <IconSearch size={16} />,
69
        }}
70
      />
71
    </div>
72
  );
73
}
74
```
75

76
## Architecture
77

78
Mantine Spotlight is built around several key components:
79

80
- **Main Component**: `Spotlight` provides a complete command center with search and actions
81
- **Compound Components**: Granular components for custom implementations (`SpotlightRoot`, `SpotlightSearch`, etc.)
82
- **Store Management**: Global and instance-based stores for state management
83
- **Action System**: Support for individual actions and grouped actions with filtering
84
- **Keyboard Navigation**: Built-in arrow key navigation and configurable shortcuts
85

86
## Capabilities
87

88
### Main Spotlight Component
89

90
Complete spotlight interface with built-in search, action filtering, and keyboard navigation. Perfect for quick implementation of command centers.
91

92
```typescript { .api }
93
function Spotlight(props: SpotlightProps): JSX.Element;
94

95
interface SpotlightProps extends SpotlightRootProps {
96
  /** Props passed down to the Spotlight.Search */
97
  searchProps?: SpotlightSearchProps;
98
  /** Actions data, passed down to Spotlight.Action component */
99
  actions: SpotlightActions[];
100
  /** Function to filter actions data based on search query */
101
  filter?: SpotlightFilterFunction;
102
  /** Message displayed when none of the actions match given filter */
103
  nothingFound?: React.ReactNode;
104
  /** Determines whether search query should be highlighted in action label */
105
  highlightQuery?: boolean;
106
  /** Maximum number of actions displayed at a time */
107
  limit?: number;
108
}
109

110
type SpotlightActions = SpotlightActionData | SpotlightActionGroupData;
111

112
interface SpotlightActionData extends SpotlightActionProps {
113
  id: string;
114
  group?: string;
115
}
116

117
interface SpotlightActionGroupData {
118
  group: string;
119
  actions: SpotlightActionData[];
120
}
121
```
122

123
[Main Component](./main-component.md)
124

125
### Compound Components
126

127
Individual components for building custom spotlight interfaces with full control over layout and behavior.
128

129
```typescript { .api }
130
function SpotlightRoot(props: SpotlightRootProps): JSX.Element;
131
function SpotlightSearch(props: SpotlightSearchProps): JSX.Element;
132
function SpotlightActionsList(props: SpotlightActionsListProps): JSX.Element;
133
function SpotlightAction(props: SpotlightActionProps): JSX.Element;
134
```
135

136
[Compound Components](./compound-components.md)
137

138
### Store Management
139

140
Store-based state management for controlling spotlight behavior programmatically, supporting both global and instance-based stores.
141

142
```typescript { .api }
143
function createSpotlight(): readonly [SpotlightStore, SpotlightActions];
144
function createSpotlightStore(): SpotlightStore;
145
function useSpotlight(store: SpotlightStore): SpotlightState;
146

147
// Global instance
148
const spotlight: SpotlightActions;
149
function openSpotlight(): void;
150
function closeSpotlight(): void;
151
function toggleSpotlight(): void;
152

153
interface SpotlightState {
154
  opened: boolean;
155
  selected: number;
156
  listId: string;
157
  query: string;
158
  empty: boolean;
159
  registeredActions: Set<string>;
160
}
161

162
interface SpotlightActions {
163
  open(): void;
164
  close(): void;
165
  toggle(): void;
166
}
167
```
168

169
[Store Management](./store-management.md)
170

171
### Utility Functions  
172

173
Helper functions for action filtering, grouping, and type checking.
174

175
```typescript { .api }
176
function isActionsGroup(
177
  item: SpotlightActionData | SpotlightActionGroupData
178
): item is SpotlightActionGroupData;
179

180
type SpotlightFilterFunction = (
181
  query: string,
182
  actions: SpotlightActions[]
183
) => SpotlightActions[];
184

185
const defaultSpotlightFilter: SpotlightFilterFunction;
186
```
187

188
[Utilities](./utilities.md)
189

190
## Types
191

192
```typescript { .api }
193
type SpotlightStore = MantineStore<SpotlightState>;
194

195
type SpotlightRootStylesNames =
196
  | ModalStylesNames
197
  | 'search'
198
  | 'actionsList'
199
  | 'action'
200
  | 'empty'
201
  | 'footer'
202
  | 'actionBody'
203
  | 'actionLabel'
204
  | 'actionDescription'
205
  | 'actionSection'
206
  | 'actionsGroup';
207

208
type SpotlightFactory = Factory<{
209
  props: SpotlightProps;
210
  ref: HTMLDivElement;
211
  stylesNames: SpotlightStylesNames;
212
  staticComponents: {
213
    Search: typeof SpotlightSearch;
214
    ActionsList: typeof SpotlightActionsList;
215
    Action: typeof SpotlightAction;
216
    Empty: typeof SpotlightEmpty;
217
    Footer: typeof SpotlightFooter;
218
    ActionsGroup: typeof SpotlightActionsGroup;
219
    Root: typeof SpotlightRoot;
220
    open: typeof spotlight.open;
221
    close: typeof spotlight.close;
222
    toggle: typeof spotlight.toggle;
223
  };
224
}>;
225

226
type SpotlightRootFactory = Factory<{
227
  props: SpotlightRootProps;
228
  ref: HTMLDivElement;
229
  stylesNames: SpotlightRootStylesNames;
230
  compound: true;
231
}>;
232

233
interface SpotlightActionProps extends BoxProps {
234
  /** Action label, pass string to use in default filter */
235
  label?: string;
236
  /** Action description, pass string to use in default filter */
237
  description?: string;
238
  /** Section displayed on the left side of the label, for example, icon */
239
  leftSection?: React.ReactNode;
240
  /** Section displayed on the right side of the label, for example, hotkey */
241
  rightSection?: React.ReactNode;
242
  /** Children override default action elements */
243
  children?: React.ReactNode;
244
  /** Determines whether left and right sections should have dimmed styles */
245
  dimmedSections?: boolean;
246
  /** Determines whether search query should be highlighted in action label */
247
  highlightQuery?: boolean;
248
  /** Key of theme.colors for highlighting search query */
249
  highlightColor?: MantineColor;
250
  /** Determines whether the spotlight should be closed when action is triggered */
251
  closeSpotlightOnTrigger?: boolean;
252
  /** Keywords that are used for default filtering */
253
  keywords?: string | string[];
254
}
255

256
interface SpotlightRootProps extends StylesApiProps<SpotlightRootFactory>, Omit<ModalProps, 'opened' | 'onClose' | 'withCloseButton'> {
257
  /** Spotlight store, can be used to create multiple instances */
258
  store?: SpotlightStore;
259
  /** Controlled Spotlight search query */
260
  query?: string;
261
  /** Called when query changes */
262
  onQueryChange?: (query: string) => void;
263
  /** Determines whether the search query should be cleared when the spotlight is closed */
264
  clearQueryOnClose?: boolean;
265
  /** Keyboard shortcut or list of shortcuts to trigger spotlight */
266
  shortcut?: string | string[] | null;
267
  /** List of tags which when focused will be ignored by shortcut */
268
  tagsToIgnore?: string[];
269
  /** Determines whether shortcut should trigger based in contentEditable */
270
  triggerOnContentEditable?: boolean;
271
  /** If set, spotlight will not be rendered */
272
  disabled?: boolean;
273
  /** Called when spotlight opens */
274
  onSpotlightOpen?: () => void;
275
  /** Called when spotlight closes */
276
  onSpotlightClose?: () => void;
277
  /** Forces opened state, useful for tests */
278
  forceOpened?: boolean;
279
  /** Determines whether spotlight should be closed when one of the actions is triggered */
280
  closeOnActionTrigger?: boolean;
281
  /** Spotlight content max-height. Ignored unless scrollable prop is set */
282
  maxHeight?: React.CSSProperties['maxHeight'];
283
  /** Determines whether the actions list should be scrollable */
284
  scrollable?: boolean;
285
}
286
```