Opening Search
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.
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
Help Mode
Press? to open help mode and see:
- Available search modes
- Keyboard shortcuts
- Search tips
- Quick actions
Esc or Backspace to return to home mode.
Specialized Modes
Access specialized search modes using keyboard shortcuts:- Integration Search
- Board Search
- App Search
Search across your integrations for specific content:Trigger: Press
i in searchFeatures:- Search media in Plex/Jellyfin/Emby
- Find content in Overseerr/Jellyseerr
- Search across multiple integrations simultaneously
- Quick actions (play, request, open)
Mode Switching
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 theSearchableIntegration interface:
Searchable Integrations
Media Services (Plex, Jellyfin, Emby)
Media Services (Plex, Jellyfin, Emby)
Search for:
- Movies by title, actors, directors
- TV shows and episodes
- Music artists and albums
- Collections
- Play media
- View details
- Open in app
Media Requests (Overseerr, Jellyseerr, Seerr)
Media Requests (Overseerr, Jellyseerr, Seerr)
Search for:
- Movies and TV shows
- Existing requests
- Available content
- Request content
- View request status
- Cancel request
Media Management (Sonarr, Radarr)
Media Management (Sonarr, Radarr)
Search for:
- Monitored series/movies
- Missing episodes
- Calendar events
- Search for releases
- Add to library
- View details
Integration Search Implementation
Search Groups
Results are organized into groups for better navigation:Group Types
- Apps: Configured applications on boards
- Boards: All accessible boards
- Integrations: Searchable integration results
- Settings: System configuration options
- 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:Deep Linking
Search results can link directly to:- Specific boards
- Settings pages
- Integration detail pages
- External apps
Child Actions
Some results have nested actions:- View library
- Open web interface
- Check status
- Configure settings
Search UI Components
Search Input
The search input provides visual feedback:- 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
Customization
Search Hotkeys
Customize search keyboard shortcuts:Search Filters
Filter search results by category:- Open search
- Type your query
- Use arrow keys to navigate groups
- 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
Search not opening
Search not opening
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)
- Try clicking the search icon
- Check browser console for errors
- Disable conflicting extensions
- Refresh the page
No results found
No results found
Check:
- Items exist in Homarr
- You have permission to access items
- Spelling of search query
- Current search mode
- Try different search terms
- Switch to home mode (Backspace)
- Check permissions
- Verify items are configured
Integration search not working
Integration search not working
Check:
- Integration is configured
- Integration implements search
- You have integration permissions
- Integration connection is working
- Test integration connection
- Verify search is supported for integration type
- Check integration permissions
- Review server logs
Slow search results
Slow search results
Check:
- Number of integrations being searched
- Network latency to integrations
- Server performance
- Number of total items
- 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
