group | package | title | order | slug | description | props | import | source | docs | installation | license | styles | ||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Other packages |
@mantine/spotlight |
Spotlight |
1 |
/others/spotlight/ |
Command center for your application |
|
import { SpotlightProvider } from '@mantine/spotlight'; |
mantine-spotlight/src |
others/spotlight.mdx |
@mantine/spotlight |
MIT |
|
import { SpotlightDemos } from '@mantine/demos';
Package depends on @mantine/core
and @mantine/hooks
.
Install with yarn:
yarn add @mantine/spotlight
Install with npm:
npm install @mantine/spotlight
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:
import { MantineProvider } from '@mantine/core';
import { SpotlightProvider } from '@mantine/spotlight';
function Demo() {
return (
<MantineProvider>
<SpotlightProvider actions={[]}>
<App />
</SpotlightProvider>
</MantineProvider>
);
}
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:
import { SpotlightProvider } from '@mantine/spotlight';
function Demo() {
return (
<SpotlightProvider shortcut={['mod + P', 'mod + K', '/']} actions={[]}>
<App />
</SpotlightProvider>
);
}
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
To disabled keyboard shortcuts set shortcut={null}
:
import { SpotlightProvider } from '@mantine/spotlight';
function Demo() {
return (
<SpotlightProvider shortcut={null} actions={[]}>
<App />
</SpotlightProvider>
);
}
use-spotlight
hook lets you control spotlight from anywhere in your application.
For example, it can be used to open spotlight with button click:
import { useSpotlight } from '@mantine/spotlight';
import { Button, Group } from '@mantine/core';
function SpotlightControl() {
const spotlight = useSpotlight();
return (
<Group position="center">
<Button onClick={spotlight.openSpotlight}>Open spotlight</Button>
</Group>
);
}
use-spotlight
returns an object with the following properties:
interface UseSpotlight {
/** Opens spotlight */
openSpotlight(): void;
/** Closes spotlight */
closeSpotlight(): void;
/** Toggles spotlight opened state */
toggleSpotlight(): void;
/** Triggers action with given id */
triggerAction(actionId: string): void;
/** Registers additional actions */
registerActions(action: SpotlightAction[]): void;
/** Removes actions with given ids */
removeActions(actionIds: string[]): void;
/** Current opened state */
opened: boolean;
/** List of registered actions */
actions: SpotlightAction[];
/** Search query */
query: string;
}
@mantine/spotlight
exports several functions which can be used to perform certain actions
from any part of your application:
// All functions can be called from anywhere (not only from components)
import {
openSpotlight,
closeSpotlight,
toggleSpotlight,
triggerSpotlightAction,
registerSpotlightActions,
removeSpotlightActions,
} from '@mantine/spotlight';
// Opens spotlight
openSpotlight();
// Closes spotlight
closeSpotlight();
// Toggles spotlight opened state
toggleSpotlight();
// triggers action with given id
triggerSpotlightAction('action-id');
// registers additional actions
registerSpotlightActions([
{
id: 'secret-action-1',
title: 'Secret action',
onTrigger: () => console.log('Secret'),
},
{
id: 'secret-action-2',
title: 'Another secret action',
onTrigger: () => console.log('Secret'),
},
]);
// removes actions
removeSpotlightActions(['secret-action-1', 'secret-action-2']);
actions
is the only required prop of SpotlightProvider
. Action shape:
interface SpotlightAction {
/** Action id, may be used to trigger action or find it in actions array,
* if not provided random string will be generated instead */
id?: string;
/** Action title, topmost large text, used for filtering */
title: string;
/** Action description, small text displayed after title, used for filtering */
description?: string;
/** Action group, used to render group label */
group?: string;
/** Keywords that are used for filtering, not displayed anywhere,
* can be a string: "react,router,javascript" or an array: ['react', 'router', 'javascript'] */
keywords?: string | string[];
/** Decorative icon */
icon?: ReactNode;
/** Function that is called when action is triggered */
onTrigger(action: SpotlightAction): void;
/** Any other properties that can be consumed by custom action component */
[key: string]: any;
}
You can import SpotlightAction
type from @mantine/spotlight
package:
import type { SpotlightAction } from '@mantine/spotlight';
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:
If you have a large list of actions, most of them will not be get to the initial list (when user have not enter any text yet).
You can control how many actions are displayed at a time with limit
prop:
You can register any amount of additional actions with registerActions
function on use-spotlight
hook.
To remove actions from the list use removeActions
function:
You can provide custom component to render actions, this feature can be used to customize how actions are displayed:
With custom actions wrapper component you can customize how actions list is rendered, for example, you can add a footer:
By default, spotlight will be closed with any action is triggered with mouse click or Enter
key.
To change this behavior set closeOnActionTrigger={false}
prop on SpotlightProvider
:
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.
Default action component supports highlighting search query with Highlight component.
To enable this option set highlightQuery
on SpotlightProvider
:
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}
: