Spotlight
Installation
Package depends on @mantine/core
and @mantine/hooks
.
Install with yarn:
Install with npm:
Usage
Spotlight
component let you build a popup search interface which can be triggered with keyboard
shortcut or programmatically from anywhere inside your application. To get started, wrap your application
with SpotlightProvider
component:
Note that if you are using MantineProvider, SpotlightProvider
must be used as its child:
Keyboard shortcuts
SpotlightProvider
uses use-hotkeys hook to add keyboard shortcuts,
the default shortcut to trigger popup is mod + K
, it means that it will be shown
when users press ⌘ + K
on MacOS and Ctrl + K
on any other os.
You can setup multiple shortcuts, for example, Mantine documentation uses the following setup:
It means that user will be able to open documentation search with the following shortcuts:
⌘ + K
/Ctrl + K
⌘ + P
/Ctrl + P
/
– single keys are also supported
Note that provided shortcuts will prevent the default behavior, for example, mod + P
will
disable "Print page" native browser function, choose those shortcuts that will not interfere
with desired default browser behavior.
Keyboard shortcuts will not work if:
- focus is not on current page
input
,textarea
orselect
elements are focused (these can be overriden with thetagsToIgnore
arg)- elements have
contentEditable=true
(can be overriden with thetriggerOnContentEditable
arg)
To disabled keyboard shortcuts set shortcut={null}
:
use-spotlight hook
useSpotlight
hook lets you control spotlight from anywhere in your application.
For example, it can be used to open spotlight with button click:
useSpotlight
returns an object with the following properties:
Event based functions
@mantine/spotlight
exports several functions which can be used to perform certain actions
from any part of your application:
Spotlight actions
actions
is the only required prop of SpotlightProvider
. Action shape:
You can import SpotlightAction
type from @mantine/spotlight
package:
Actions filtering
When user searches, spotlight actions are filtered based on the following action properties:
title
–string
description
–string
keywords
–string | string[]
You can change filtering logic by setting filter
prop on SpotlightProvider
.
The following example filters actions only by title
:
Actions limit
If you have a large list of actions, most of them won't be presented in the initial list (when user have not entered any text yet).
You can control how many actions are displayed at a time with the limit
prop:
Register additional actions
You can register any amount of additional actions with registerActions
function on useSpotlight
hook.
To remove actions from the list use removeActions
function:
Group actions
Custom action component
You can provide custom component to render actions, this feature can be used to customize how actions are displayed:
Custom actions wrapper component
With custom actions wrapper component you can customize how actions list is rendered, for example, you can add a footer:
Close spotlight on action trigger
By default, spotlight will be closed when any action is triggered with mouse click or Enter
key.
To change this behavior set closeOnActionTrigger={false}
prop on SpotlightProvider
:
Close spotlight on specific action trigger
Other than with the global closeOnActionTrigger
property, the closeOnTrigger
property can be defined
for specific actions. The action will then ignore the closeOnActionTrigger
property and use its own definition.
Highlight query
Default action component supports highlighting search query with Highlight component.
To enable this option set highlightQuery
on SpotlightProvider
:
Change transitions
Component presence is animated with Transition component, it supports all premade and custom transitions. To change transition set the following properties:
transition
– premade transition name or custom transition objecttransitionDuration
– transition duration in ms
To disable transitions set transitionDuration={0}
:
SpotlightProvider component props
Name | Type | Description |
---|---|---|
actionComponent | FC<DefaultActionProps> | Component that is used to render actions |
actions * | SpotlightAction[] | ((query: string) => SpotlightAction[]) | Actions list |
actionsWrapperComponent | string | FC<{ children: ReactNode; }> | Component that is used to wrap actions list |
centered | boolean | Should spotlight be rendered in the center of the screen |
children | ReactNode | Your application |
cleanQueryOnClose | boolean | Should search be cleared when spotlight closes |
closeOnActionTrigger | boolean | Should spotlight be closed when action is triggered |
disabled | boolean | Spotlight will not render if disabled is set to true |
filter | (query: string, actions: SpotlightAction[]) => SpotlightAction[] | Function used to determine how actions will be filtered based on user input |
highlightColor | MantineColor | The highlight color |
highlightQuery | boolean | Should user query be highlighted in actions title |
limit | number | Number of actions displayed at a time |
maxWidth | number | Max spotlight width |
nothingFoundMessage | ReactNode | Message displayed when actions were not found |
onQueryChange | (query: string) => void | Called when user enters text in search input |
onSpotlightClose | () => void | Called when spotlight closes |
onSpotlightOpen | () => void | Called when spotlight opens |
overlayBlur | number | Backdrop overlay blur in px |
overlayColor | string | Backdrop overlay color, e.g. #000 |
overlayOpacity | number | Backdrop overlay opacity (0-1), e.g. 0.65 |
radius | number | "xs" | "sm" | "md" | "lg" | "xl" | Radius from theme.radius, or number to set border-radius in px, defaults to theme.defaultRadius |
searchIcon | ReactNode | Search input icon |
searchInputProps | TextInputProps | Props spread to search input |
searchPlaceholder | string | Search input placeholder |
shadow | MantineShadow | Value from theme.shadows or any valid css box-shadow value |
shortcut | string | string[] | Keyboard shortcut or list of shortcuts to trigger spotlight |
tagsToIgnore | string[] | Tags to ignore shortcut hotkeys on. |
topOffset | number | Top offset when spotlight is not centered |
transition | MantineTransition | Premade transition or transition object |
transitionDuration | number | Transition duration in ms, set to 0 to disable all transitions |
triggerOnContentEditable | boolean | Whether shortcuts should trigger based on contentEditable. |
withinPortal | boolean | Should spotlight be rendered within Portal |
zIndex | ZIndex | Spotlight z-index |
SpotlightProvider component Styles API
Name | Static selector | Description |
---|---|---|
root | .mantine-SpotlightProvider-root | Root element |
spotlight | .mantine-SpotlightProvider-spotlight | Spotlight itself |
overlay | .mantine-SpotlightProvider-overlay | Backdrop overlay |
inner | .mantine-SpotlightProvider-inner | Inner element, used for spotlight positioning |
searchInput | .mantine-SpotlightProvider-searchInput | Search input |
nothingFound | .mantine-SpotlightProvider-nothingFound | Nothing found message |
actions | .mantine-SpotlightProvider-actions | Actions list |
actionsGroup | .mantine-SpotlightProvider-actionsGroup | Actions group label |
action | .mantine-SpotlightProvider-action | Action |
actionHovered | .mantine-SpotlightProvider-actionHovered | Hovered action modifier |
actionIcon | .mantine-SpotlightProvider-actionIcon | Action icon wrapper |
actionBody | .mantine-SpotlightProvider-actionBody | Action body |