After installation import package styles at the root of your application:
Spotlight component can be used as a search or as a command center of your application.
It is used as a search on mantine.dev website, you can trigger it with
Ctrl + K shortcut.
Spotlight is based on Modal component and supports most of its props.
@mantine/spotlight package exports an object with actions that can be used to control the spotlight:
These actions can be passed to event listeners or used anywhere in your application (not limited to React components):
You can also import actions directly from the
@mantine/spotlight package, if you prefer this syntax:
spotlight object documented above uses the default store, it works fine if you have only one spotlight
in your application. In case you need multiple spotlights, you need to create your own store for each of them:
Spotlight uses use-hotkeys hook to handle keyboard shortcuts.
Ctrl + K and
Cmd + K shortcuts are used to open spotlight, you can change them
limit prop to limit the maximum number of actions that can be displayed at a time.
Usually, 5–7 actions is a good number.
limit prop is crucial for performance in case
you have a lot of actions, it will prevent the spotlight from rendering all of them at once.
The example below renders 3000 actions, but only 7 of them are displayed at a time:
Spotlight actions list is not scrollable. If you have a lot of actions that
you need to display at a time, set
maxHeight props. Note that there are
caveats with both approaches:
- When the
scrollableprop is not set, actions list height is not limited and the spotlight body will grow to fit all actions. This can result in a very long spotlight body that will overflow the viewport. To prevent this, use
limitprop to define the maximum number of actions that can be displayed at a time. Usually, 5–7 actions is a good number.
- When the
scrollableprop is set, actions list height will always equal to the value of
maxHeightprop (it will not shrink if there are not enough actions to fill the space). When there are more actions than can fit into the list, it will become scrollable. Scrolling logic is handled by ScrollArea component.
In other words, if you want the actions list to shrink, do not set
scrollable prop and use
prop. If you want the actions list to always have a fixed height, set
Spotlight supports actions groups, you can use them to group actions by category:
If you need more control over spotlight rendering and logic, use compound components. Available components:
Spotlight.Root– root component, should be used as a wrapper for all other components, accepts all props to customize logic
Spotlight.Search– search input
Spotlight.ActionsList– list of actions, required to wrap all actions and actions groups
Spotlight.Action– action button
Spotlight.ActionsGroup- group of actions
Spotlight.Empty– empty state (nothing found)
For example, with compound components pattern you can customize actions contents: