Guides and Sample Code


macOS Human Interface Guidelines



Spotlight is a powerful macOS search technology that makes searching for files on the computer as easy as searching the web. Using Spotlight, users can search for things using attributes that have meaning for them, such as the intended audience for a document, the orientation of an image, or the key signature of the music in an audio file. Information like this (called metadata) is embedded in a file by the app that created it. Spotlight’s power comes from being able to extract, store, update, and organize the metadata of files to allow fast, comprehensive searches.

image: ../Art/spotlight_2x.png

Spotlight is also available to you, the developer, to find files to display and data to use in your app. The guidelines in this section help you extend Spotlight capabilities to your users and take advantage of its benefits in your app.

Use Spotlight to give advanced file-search capabilities to users within the context of your app. For example, you might choose to replicate the Spotlight contextual-menu item, using a button that initiates a Spotlight search for the user’s selected text. You might then display a custom window that contains all the search results or a filtered subset of them.

Consider providing Spotlight-powered search instead of a Finder-based Open dialog. Users often need to work on a file that was saved in an atypical place or given an unexpected or forgotten name. If you offer only a Finder-based Open dialog, it might force the user to waste time navigating the file system, trying to remember what the file was named and where it was saved. Instead, provide a Spotlight-powered search that allows users to search the entire file system, using attributes that are meaningful to them.

Consider using Spotlight behind the scenes to find needed files. For example, an app that provides a back-up service might allow users to choose a broad category of file type to back up, such as images. Instead of asking users to identify all the folders that contain their images or only backing up a Pictures folder, the app could perform a Spotlight search to find every image file in the file system, regardless of its location.

Use Search Kit (not Spotlight) to do fine-grained textual searching within a document. Spotlight is tuned to search for files; it’s not intended to do extensive text-based searching within a document. An app that stores data in database records, for example, should not base its database search on Spotlight because the data are not stored in separate files. For more information on using Search Kit in your app, see SearchKit Programming Guide.

Include a Quick Look generator if your app creates documents in an uncommon or custom format. Spotlight uses Quick Look technology to display thumbnails and full-size previews of the documents returned in a search. If your app produces documents in common content types, such as HTML, RTF, plain text, TIFF, PNG, JPEG, PDF, and QuickTime movies, Spotlight can display the thumbnails and previews automatically. Otherwise, you should include a Quick Look generator to convert your native document format into a format Spotlight can display. To learn how to create a Quick Look generator, see Quick Look Programming Guide.

Supply a Spotlight importer that describes the types of metadata your file format contains. Supplying an importer (also called a plug-in) ensures that users can search for the files your app creates using the attributes described by the metadata your files contain. For comprehensive information on how to create a Spotlight importer, see Spotlight Importer Programming Guide.