📱 Capacitor SpotSearch

A simple Capacitor plugin to index and manage iOS Spotlight search items.

@daniele-rolli/capacitor-spotsearch

This plugin lets you programmatically add, update, and remove searchable items from iOS Spotlight, using the native CoreSpotlight API. Supports optional opt-in indexing and provides a Web fallback for testing.

✨ Features

• Add (indexItems) searchable content to iOS Spotlight
• Delete specific items by ID (deleteItems)
• Delete all items in a domain (deleteDomain)
• Optional opt-in indexing mode for user privacy
• Web plugin fallback (stores items in-memory)

📦 Installation

npm install @daniele-rolli/capacitor-spotsearch
npx cap sync

iOS deployment target: 14.0+

🛠 Usage

Import & Register

import { SpotSearch } from '@daniele-rolli/capacitor-spotsearch';

// Example: Enable indexing (Web fallback only)
await SpotSearch.enableIndexing?.(true);

Index Items

import { SpotSearch } from '@daniele-rolli/capacitor-spotsearch';

await SpotSearch.indexItems({
  items: [
    {
      id: 'article-123',
      domain: 'news',
      title: 'Breaking News: Cats Take Over',
      snippet: 'A mysterious feline uprising...',
      keywords: ['cats', 'news', 'funny'],
      url: 'https://example.com/cats',
      thumbnailBase64: 'iVBORw0KGgoAAAANSUhEUgAA...', // optional
      extra: { category: 'animals' },
    },
  ],
});

Delete Specific Items

await SpotSearch.deleteItems({
  ids: ['article-123', 'article-456'],
});

Delete All Items in a Domain

await SpotSearch.deleteDomain({
  domain: 'news',
});

📚 API

SpotItem

Field	Type	Required	Description
id	string	✅	Unique item identifier
domain	string	✅	Logical grouping (e.g., news, products)
title	string	✅	Main display title
snippet	string	❌	Short description for Spotlight
keywords	string[]	❌	Keywords to improve search
url	string	❌	Deep link or website URL
thumbnailBase64	string	❌	Base64 thumbnail image
extra	Record<string, any>	❌	Additional metadata

---

Methods

indexItems(options: IndexItemsOptions): Promise<void>

Indexes an array of SpotItem objects.

deleteItems(options: DeleteItemsOptions): Promise<void>

Deletes items by their unique IDs.

deleteDomain(options: DeleteDomainOptions): Promise<void>

Deletes all items within a given domain.

(Web only) enableIndexing(enabled: boolean): Promise<void>

Opt-in to allow Web plugin indexing. Defaults to false.

🖥 Web Fallback

• Stores items in memory (Map) for development/testing.
• Requires calling enableIndexing(true) before adding items.

📱 iOS Notes

• Uses CSSearchableItem and CSSearchableIndex.
• Images are provided via thumbnailBase64.
• Deleting a domain removes all items indexed under it.

📄 License

MIT

Author: Daniele Rolli