Skip to main content
Homarr’s search feature (Spotlight) provides instant access to your apps, boards, and services. Use keyboard shortcuts to quickly search across all your resources without navigating through menus. Access search using the keyboard shortcut or UI button:

Keyboard Shortcut

Press Ctrl+K (Windows/Linux) or Cmd+K (Mac) from anywhere in Homarr.

Search Button

Click the search icon in the navigation bar.
// From packages/spotlight/src/components/spotlight.tsx:53
<MantineSpotlight.Root
  shortcut={hotkeys.openSpotlight} // Ctrl+K or Cmd+K
  yOffset={8}
  onSpotlightClose={() => {
    setMode(defaultMode);
    setChildrenOptions(null);
  }}
>

Search Modes

Spotlight supports multiple search modes for different types of content:

Home Mode (Default)

The default mode searches across all available resources:
  • Apps: Your configured applications
  • Boards: All accessible boards
  • Integrations: Configured integrations
  • Settings: System configuration pages
  • Actions: Common tasks and operations
Simply start typing to search across everything.

Help Mode

Press ? to open help mode and see:
  • Available search modes
  • Keyboard shortcuts
  • Search tips
  • Quick actions
Press Esc or Backspace to return to home mode.

Specialized Modes

Access specialized search modes using keyboard shortcuts:

Mode Switching

// From packages/spotlight/src/components/spotlight.tsx:65
onQueryChange={(query) => {
  // Detect mode character
  const modeToActivate = searchModes.find(
    mode => mode.character === query
  );
  
  if (modeToActivate) {
    setMode(modeToActivate.modeKey);
    setQuery(""); // Clear the mode character
  } else {
    setQuery(query);
  }
}}
Type a mode character (i, b, a, ?) to instantly switch modes.

Keyboard Navigation

Navigate search results efficiently with keyboard:

Navigate Results

↑ / ↓: Move selection up/downTab: Next resultShift+Tab: Previous result

Actions

Enter: Execute selected actionCtrl+Enter: Open in new tab (if applicable)Esc: Close search or go back one level

Mode Control

Backspace (empty query): Return to home mode?: Open helpi/b/a: Switch to specific mode

Quick Clear

Ctrl+U: Clear search queryEsc: Close search completely

Searching Across Integrations

Search supports querying data from integrations that implement the SearchableIntegration interface:

Searchable Integrations

Search for:
  • Movies by title, actors, directors
  • TV shows and episodes
  • Music artists and albums
  • Collections
Actions:
  • Play media
  • View details
  • Open in app
Search for:
  • Movies and TV shows
  • Existing requests
  • Available content
Actions:
  • Request content
  • View request status
  • Cancel request
Search for:
  • Monitored series/movies
  • Missing episodes
  • Calendar events
Actions:
  • Search for releases
  • Add to library
  • View details

Integration Search Implementation

// From packages/integrations/src/base/searchable-integration.ts
export interface SearchableIntegration {
  searchAsync(query: string, options?: SearchOptions): Promise<SearchResult[]>;
}

interface SearchResult {
  id: string;
  title: string;
  description?: string;
  imageUrl?: string;
  type: "movie" | "tv" | "music" | "other";
  actions: SearchAction[];
}

interface SearchAction {
  label: string;
  icon: TablerIcon;
  action: () => Promise<void>;
}

Search Groups

Results are organized into groups for better navigation:
// From packages/spotlight/src/components/actions/groups/action-group.tsx
<SpotlightActionGroups
  query={query}
  groups={groups}
  setMode={setMode}
  setChildrenOptions={setChildrenOptions}
/>

Group Types

  1. Apps: Configured applications on boards
  2. Boards: All accessible boards
  3. Integrations: Searchable integration results
  4. Settings: System configuration options
  5. Recent: Recently accessed items

Advanced Features

Fuzzy Matching

Search uses fuzzy matching to find results even with typos:
  • “pls” matches “Plex”
  • “snarr” matches “Sonarr”
  • “ovsrr” matches “Overseerr”

Query Highlighting

Matching characters are highlighted in results for clarity:
Query: "pls"
Result: [P]ex Media [L]i[S]erver

Deep Linking

Search results can link directly to:
  • Specific boards
  • Settings pages
  • Integration detail pages
  • External apps

Child Actions

Some results have nested actions:
// From packages/spotlight/src/components/actions/children-actions.tsx
<SpotlightChildrenActions
  childrenOptions={childrenOptions}
  query={query}
  setChildrenOptions={setChildrenOptions}
/>
Example: Selecting a media server shows:
  • View library
  • Open web interface
  • Check status
  • Configure settings

Search UI Components

Search Input

The search input provides visual feedback:
// From packages/spotlight/src/components/spotlight.tsx:76
<MantineSpotlight.Search
  placeholder={`${t("search.placeholder")}...`}
  leftSection={
    <Group>
      <IconSearch stroke={1.5} />
      {mode !== "home" ? <Kbd>{mode.character}</Kbd> : null}
    </Group>
  }
  rightSection={
    mode === "home" ? (
      <ActionIcon onClick={() => setMode("help")}>
        <IconQuestionMark />
      </ActionIcon>
    ) : (
      <ActionIcon onClick={() => setMode("home")}>
        <IconX />
      </ActionIcon>
    )
  }
/>
Visual indicators:
  • Search icon: Always visible on left
  • Mode badge: Shows current mode character
  • Help button: Quick access to help (home mode)
  • Close button: Return to home mode (other modes)

Result Display

App Results

  • App icon
  • App name
  • Description (if configured)
  • Status indicator (if ping enabled)

Board Results

  • Board name
  • Description
  • Last modified date
  • Permission indicator

Integration Results

  • Service icon
  • Content title
  • Description/metadata
  • Available actions

No Results

  • “No results found” message
  • Search tips
  • Suggestion to try different query
  • Help mode shortcut

Empty State

// From packages/spotlight/src/components/no-results.tsx
export const NoResults = () => (
  <Stack align="center" p="xl">
    <IconSearch size={48} stroke={1} opacity={0.3} />
    <Text size="sm" c="dimmed">
      No results found
    </Text>
    <Text size="xs" c="dimmed">
      Try a different search term or press ? for help
    </Text>
  </Stack>
);

Customization

Search Hotkeys

Customize search keyboard shortcuts:
// From packages/definitions/src/hotkeys.ts
const hotkeys = {
  openSpotlight: ["mod+K"], // Ctrl/Cmd + K
  // Can be customized in settings
};

Search Filters

Filter search results by category:
  1. Open search
  2. Type your query
  3. Use arrow keys to navigate groups
  4. Press Enter on a group to expand

Search Scope

Control what appears in search:
  • User preferences: Hide specific categories
  • Permissions: Only show accessible items
  • Board context: Prioritize items from current board

Performance

Debouncing

Search queries are debounced to prevent excessive API calls:
  • Waits 300ms after last keystroke
  • Cancels previous requests
  • Shows loading indicator

Caching

Search results are cached for better performance:
  • Recent searches cached for 5 minutes
  • Integration results cached per query
  • Apps and boards cached until change

Prefetching

Common searches are prefetched:
  • All apps loaded on search open
  • Accessible boards preloaded
  • Integration endpoints pre-warmed

Accessibility

Keyboard Only

Complete search experience without mouse:
  • Open with shortcut
  • Navigate with arrows
  • Execute with Enter
  • Close with Esc

Screen Readers

Full screen reader support:
  • ARIA labels on all elements
  • Results announced
  • Mode changes announced
  • Loading states communicated

High Contrast

Readable in high contrast mode:
  • Sufficient color contrast
  • Focus indicators visible
  • Icons with text labels
  • State clearly indicated

Reduced Motion

Respects motion preferences:
  • Animations disabled when requested
  • Instant mode transitions
  • No auto-scrolling
  • Smooth focus changes optional

Best Practices

Quick Access

  • Learn mode shortcuts (i, b, a)
  • Use Ctrl+K frequently instead of clicking
  • Remember recent searches
  • Create bookmarks for common queries

Efficient Searching

  • Use fuzzy matching (type quickly, don’t fix typos)
  • Start with mode character for better results
  • Use keyboard navigation exclusively
  • Close with Esc to maintain flow

Organization

  • Name apps descriptively for easier search
  • Use consistent naming conventions
  • Tag related items similarly
  • Keep board names searchable

Integration Search

  • Set up searchable integrations
  • Test search functionality
  • Grant appropriate permissions
  • Monitor search performance

Troubleshooting

Check:
  • Keyboard shortcut is correct (Ctrl+K or Cmd+K)
  • No conflicting browser extensions
  • JavaScript is enabled
  • Not in an input field (which might capture the shortcut)
Solution:
  • Try clicking the search icon
  • Check browser console for errors
  • Disable conflicting extensions
  • Refresh the page
Check:
  • Items exist in Homarr
  • You have permission to access items
  • Spelling of search query
  • Current search mode
Solution:
  • Try different search terms
  • Switch to home mode (Backspace)
  • Check permissions
  • Verify items are configured
Check:
  • Integration is configured
  • Integration implements search
  • You have integration permissions
  • Integration connection is working
Solution:
  • Test integration connection
  • Verify search is supported for integration type
  • Check integration permissions
  • Review server logs
Check:
  • Number of integrations being searched
  • Network latency to integrations
  • Server performance
  • Number of total items
Solution:
  • Limit searchable integrations
  • Use specific search modes
  • Optimize integration performance
  • Increase server resources

Next Steps

Creating Widgets

Add widgets to make them searchable

Set Up Integrations

Enable integration search functionality

Boards

Search across multiple boards

Permissions

Configure what users can search

Build docs developers (and LLMs) love