tessl/npm-mantine--spotlight

Command center components for react and Mantine

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Main Spotlight Component

Name: tessl/npm-mantine--spotlight
Author: tessl

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.

Capabilities

Spotlight Component

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

/**
 * Complete spotlight interface with built-in search and actions
 * @param props - Configuration props for the spotlight component
 * @returns JSX element containing the complete spotlight interface
 */
function Spotlight(props: SpotlightProps): JSX.Element;

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

Usage Examples:

import { Spotlight } from "@mantine/spotlight";
import { IconSearch, IconHome, IconDashboard } from "@tabler/icons-react";

// Basic spotlight with actions
function BasicSpotlight() {
  const actions = [
    {
      id: "home",
      label: "Home",
      description: "Navigate to home page",
      onClick: () => navigate("/"),
      leftSection: <IconHome size={16} />,
    },
    {
      id: "dashboard",
      label: "Dashboard", 
      description: "View dashboard",
      onClick: () => navigate("/dashboard"),
      leftSection: <IconDashboard size={16} />,
    },
  ];

  return (
    <Spotlight
      actions={actions}
      nothingFound="Nothing found..."
      highlightQuery
      searchProps={{
        placeholder: "Search...",
        leftSection: <IconSearch size={16} />,
      }}
    />
  );
}

// Spotlight with grouped actions
function GroupedSpotlight() {
  const actions = [
    {
      group: "Navigation",
      actions: [
        {
          id: "home",
          label: "Home",
          description: "Navigate to home page",
          onClick: () => navigate("/"),
        },
        {
          id: "settings",
          label: "Settings", 
          description: "Open settings page",
          onClick: () => navigate("/settings"),
        },
      ],
    },
    {
      id: "logout",
      label: "Logout",
      description: "Sign out of your account",
      onClick: () => logout(),
    },
  ];

  return (
    <Spotlight
      actions={actions}
      limit={10}
      filter={(query, actions) => 
        actions.filter(action => 
          action.label?.toLowerCase().includes(query.toLowerCase())
        )
      }
    />
  );
}

Static Methods

The Spotlight component exposes static methods for programmatic control:

/**
 * Opens the global spotlight instance
 */
Spotlight.open(): void;

/**
 * Closes the global spotlight instance  
 */
Spotlight.close(): void;

/**
 * Toggles the global spotlight instance
 */
Spotlight.toggle(): void;

Usage Examples:

import { Spotlight } from "@mantine/spotlight";

// Programmatic control
function MyComponent() {
  return (
    <div>
      <button onClick={Spotlight.open}>Open Spotlight</button>
      <button onClick={Spotlight.close}>Close Spotlight</button>
      <button onClick={Spotlight.toggle}>Toggle Spotlight</button>
    </div>
  );
}

Compound Component Access

Access individual components through static properties:

Spotlight.Root: typeof SpotlightRoot;
Spotlight.Search: typeof SpotlightSearch;
Spotlight.ActionsList: typeof SpotlightActionsList;
Spotlight.Action: typeof SpotlightAction;
Spotlight.Empty: typeof SpotlightEmpty;
Spotlight.Footer: typeof SpotlightFooter;
Spotlight.ActionsGroup: typeof SpotlightActionsGroup;

Action Data Types

interface SpotlightActionData extends SpotlightActionProps {
  /** Unique identifier for the action */
  id: string;
  /** Optional group name for organizing actions */
  group?: string;
}

interface SpotlightActionGroupData {
  /** Group label displayed in the interface */
  group: string;
  /** Array of actions belonging to this group */
  actions: SpotlightActionData[];
}

type SpotlightActions = SpotlightActionData | SpotlightActionGroupData;

type SpotlightFilterFunction = (
  query: string,
  actions: SpotlightActions[]
) => SpotlightActions[];

Default Configuration

The Spotlight component comes with sensible defaults:

const defaultProps = {
  size: 600,
  yOffset: 80,
  limit: Infinity,
  zIndex: getDefaultZIndex('max'),
  overlayProps: { backgroundOpacity: 0.35, blur: 7 },
  transitionProps: { duration: 200, transition: 'pop' },
  store: spotlightStore,
  filter: defaultSpotlightFilter,
  clearQueryOnClose: true,
  closeOnActionTrigger: true,
  shortcut: 'mod + K',
};