0
# Main Spotlight Component
1

2
The main `Spotlight` component provides a complete command center interface with built-in search, action filtering, and keyboard navigation. It combines all the compound components into a single, easy-to-use interface.
3

4
## Capabilities
5

6
### Spotlight Component
7

8
Creates a complete command center overlay with search input, actions list, and keyboard navigation.
9

10
```typescript { .api }
11
/**
12
 * Complete spotlight interface with built-in search and actions
13
 * @param props - Configuration props for the spotlight component
14
 * @returns JSX element containing the complete spotlight interface
15
 */
16
function Spotlight(props: SpotlightProps): JSX.Element;
17

18
interface SpotlightProps extends SpotlightRootProps {
19
  /** Props passed down to the Spotlight.Search */
20
  searchProps?: SpotlightSearchProps;
21
  /** Actions data, passed down to Spotlight.Action component */
22
  actions: SpotlightActions[];
23
  /** Function to filter actions data based on search query, by default actions are filtered by title, description and keywords */
24
  filter?: SpotlightFilterFunction;
25
  /** Message displayed when none of the actions match given filter */
26
  nothingFound?: React.ReactNode;
27
  /** Determines whether search query should be highlighted in action label */
28
  highlightQuery?: boolean;
29
  /** Maximum number of actions displayed at a time */
30
  limit?: number;
31
}
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
import { Spotlight } from "@mantine/spotlight";
38
import { IconSearch, IconHome, IconDashboard } from "@tabler/icons-react";
39

40
// Basic spotlight with actions
41
function BasicSpotlight() {
42
  const actions = [
43
    {
44
      id: "home",
45
      label: "Home",
46
      description: "Navigate to home page",
47
      onClick: () => navigate("/"),
48
      leftSection: <IconHome size={16} />,
49
    },
50
    {
51
      id: "dashboard",
52
      label: "Dashboard", 
53
      description: "View dashboard",
54
      onClick: () => navigate("/dashboard"),
55
      leftSection: <IconDashboard size={16} />,
56
    },
57
  ];
58

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

72
// Spotlight with grouped actions
73
function GroupedSpotlight() {
74
  const actions = [
75
    {
76
      group: "Navigation",
77
      actions: [
78
        {
79
          id: "home",
80
          label: "Home",
81
          description: "Navigate to home page",
82
          onClick: () => navigate("/"),
83
        },
84
        {
85
          id: "settings",
86
          label: "Settings", 
87
          description: "Open settings page",
88
          onClick: () => navigate("/settings"),
89
        },
90
      ],
91
    },
92
    {
93
      id: "logout",
94
      label: "Logout",
95
      description: "Sign out of your account",
96
      onClick: () => logout(),
97
    },
98
  ];
99

100
  return (
101
    <Spotlight
102
      actions={actions}
103
      limit={10}
104
      filter={(query, actions) => 
105
        actions.filter(action => 
106
          action.label?.toLowerCase().includes(query.toLowerCase())
107
        )
108
      }
109
    />
110
  );
111
}
112
```
113

114
### Static Methods
115

116
The Spotlight component exposes static methods for programmatic control:
117

118
```typescript { .api }
119
/**
120
 * Opens the global spotlight instance
121
 */
122
Spotlight.open(): void;
123

124
/**
125
 * Closes the global spotlight instance  
126
 */
127
Spotlight.close(): void;
128

129
/**
130
 * Toggles the global spotlight instance
131
 */
132
Spotlight.toggle(): void;
133
```
134

135
**Usage Examples:**
136

137
```typescript
138
import { Spotlight } from "@mantine/spotlight";
139

140
// Programmatic control
141
function MyComponent() {
142
  return (
143
    <div>
144
      <button onClick={Spotlight.open}>Open Spotlight</button>
145
      <button onClick={Spotlight.close}>Close Spotlight</button>
146
      <button onClick={Spotlight.toggle}>Toggle Spotlight</button>
147
    </div>
148
  );
149
}
150
```
151

152
### Compound Component Access
153

154
Access individual components through static properties:
155

156
```typescript { .api }
157
Spotlight.Root: typeof SpotlightRoot;
158
Spotlight.Search: typeof SpotlightSearch;
159
Spotlight.ActionsList: typeof SpotlightActionsList;
160
Spotlight.Action: typeof SpotlightAction;
161
Spotlight.Empty: typeof SpotlightEmpty;
162
Spotlight.Footer: typeof SpotlightFooter;
163
Spotlight.ActionsGroup: typeof SpotlightActionsGroup;
164
```
165

166
## Action Data Types
167

168
```typescript { .api }
169
interface SpotlightActionData extends SpotlightActionProps {
170
  /** Unique identifier for the action */
171
  id: string;
172
  /** Optional group name for organizing actions */
173
  group?: string;
174
}
175

176
interface SpotlightActionGroupData {
177
  /** Group label displayed in the interface */
178
  group: string;
179
  /** Array of actions belonging to this group */
180
  actions: SpotlightActionData[];
181
}
182

183
type SpotlightActions = SpotlightActionData | SpotlightActionGroupData;
184

185
type SpotlightFilterFunction = (
186
  query: string,
187
  actions: SpotlightActions[]
188
) => SpotlightActions[];
189
```
190

191
## Default Configuration
192

193
The Spotlight component comes with sensible defaults:
194

195
```typescript { .api }
196
const defaultProps = {
197
  size: 600,
198
  yOffset: 80,
199
  limit: Infinity,
200
  zIndex: getDefaultZIndex('max'),
201
  overlayProps: { backgroundOpacity: 0.35, blur: 7 },
202
  transitionProps: { duration: 200, transition: 'pop' },
203
  store: spotlightStore,
204
  filter: defaultSpotlightFilter,
205
  clearQueryOnClose: true,
206
  closeOnActionTrigger: true,
207
  shortcut: 'mod + K',
208
};
209
```