Safari Extensions JS

Extend the browsing experience with injected scripts and style sheets for web content, custom buttons in the Safari toolbar, and contextual menu items.


Legacy Safari Extensions provide a way for you to add features to the Safari browser and extend the browsing experience. These extensions can add custom buttons to the Safari toolbar, create additional bars, add contextual menu items, display content, and inject scripts and style sheets into webpages.




Instances of the SafariActivateEvent class are used to notify listeners when a tab or window is activated.


The SafariAppExtension class is used by a content script to represent your extension; an instance of the class is accessible as safari.extension.


The SafariAppExtensionPage class represents a web content area; an instance of the class is accessible as safari.self. Your extension can listen for events, such as SafariExtensionMessageEvent, using safari.self.addEventListener. See “Registering Event Listeners” in SafariEventTarget.


The SafariApplication class allows a Safari extension to interact with the application's SafariBrowserWindow and SafariBrowserTab objects.


Instances of the SafariAvailableEvent class are used to notify listeners when Reader is available.


Instances of the SafariBeforeNavigateEvent class are used to notify listeners when the user navigates to a new page, before the page is loaded. You can use the preventDefault method to prevent the new page from loading.


The SafariBeforeSearchEvent event fires before the Smart Search Field performs a search, allowing you to intercept the query and execute an alternate task. SafariBeforeSearchEvent can be used with SafariBeforeNavigateEvent to determine what the user intends to do in the Smart Search Field.


Instances of the SafariBrowserTab class represent tabs in the user’s browser window.


Instances of the SafariBrowserWindow class represent browser windows. Each window contains one or more tabs, which display web content.


Instances of the SafariCloseEvent class are used to notify listeners when a tab or window is closed.


Instances of the SafariCommandEvent class represent events being used to send a command.


Instances of the SafariContentBrowserTabProxy class serve as proxy objects, allowing scripts injected in the web content to communicate with SafariBrowserTab objects and the rest of the extension.


The SafariContentExtension class represents your extension to scripts running inside the web content; an instance of the class is accessible as safari.extension. Its counterpart class outside of the web content is SafariExtension.


The SafariContentNamespace class is a namespace that provides access to the Safari Extensions functionality inside of a web content area.


The SafariContentReader class allows you to inject content into the Reader view.


Instances of the SafariContentWebPage class represent a web content area.


Instances of the SafariDeactivateEvent class are used to notify listeners when a browser tab or a browser window is deactivated.


The SafariEvent class is a base class used to encapsulate events. Developers who are familiar with DOM events will notice many similarities in design and behavior.


The SafariEventTarget class serves as a base class for all objects that participate in the event-dispatch hierarchy.


A SafariExtension instance represents your extension outside of the web content; an instance of the class is accessible as safari.extension. The counterpart class to SafariExtension for scripts running within the web content is SafariContentExtension.


Instances of the SafariExtensionBar class represent a bar that your extension provides. An extension can add any number of bars to Safari. Adding bars is optional.


A SafariExtensionCompanion object is an app extension for your macOS app that receives and responds to secure messages from your Safari extension. Sending a message to a Safari extension companion is similar to sending a message to an injected script; simply call the dispatchMessage method on the extension companion object. See Communicating with your OS X App for more information on extension companions.


Instances of the SafariExtensionContextMenu class represent a contextual menu that is populated by the extension. Safari displays the contents of this menu as part of its contextual menu.


Instances of the SafariExtensionContextMenuEvent class are used to notify listeners when a context menu is about to be displayed.


Instances of the SafariExtensionContextMenuItem class represent individual menu items within an extension’s context menu.


Instances of the SafariExtensionContextMenuItemCommandEvent class are used to send command events from a context menu item.


Instances of the SafariExtensionContextMenuItemValidateEvent class are used to notify listeners when a context menu is about to be displayed.


Safari extensions have a global page, represented by the SafariExtensionGlobalPage class. The global page is loaded once when the extension is loaded, but it is never displayed to the user. It can contain resources such as scripts, images, and HTML content.


The SafariExtensionMenu class represents menus.


The SafariExtensionMenuItem class represents items in a menu.


Instances of the SafariExtensionMessageEvent encapsulate a message being passed. Message passing is the only way to communicate information from inside the web content area to scripts running outside of it, and vice versa.


The SafariExtensionPopover class represents popovers. You use popovers to present information temporarily. The popover content is layered on top of the existing web content in a special type of window.


Instances of the SafariExtensionPopoverEvent class are used to notify listeners when a popover is about to be displayed.


The SafariExtensionSecureSettings class provides a place for your extension to securely store settings that should persist between sessions. You interact with it in exactly the same way as you interact with the SafariExtensionSettings class.


The SafariExtensionsSettings class provides a place for your extension to store settings that should persist between sessions.


Instances of the SafariExtensionsSettingsChangeEvent class are used to provide a description of a change made to the extension’s settings. A settings change event is sent when your extension changes a setting as well as when a setting is changed outside your extension (for example, a setting changed in the Safari preferences).


Instances of the SafariExtensionToolbarItem represent items that your extension adds to the Safari toolbar. Users can select which toolbar items are shown by selecting Customize Toolbar in the same way that they can add and remove toolbar items provided by Safari.


The SafariNamespace class is a namespace that provides access to the Safari Extensions functionality outside of the web content area.


Instances of the SafariNavigateEventClassRef class are used to notify listeners when the user navigates to a new webpage.


Instances of the SafariOpenEvent class are used to notify listeners when a tab or window is opened.


The SafariPrivateBrowsing class allows you to determine whether Safari currently has Private Browsing enabled. Private Browsing mode disables the ability for Safari to store cookies, browsing history, search history, caches, and Autofill information. If Private Browsing is enabled, you should make efforts not to track the user’s browsing behavior and respect their decision to browse privately.


Reader is a Safari feature that allows users to read online articles in a continuous, clutter-free view, with no ads or visual distractions. Reader concatenates multipage articles into a single scrolling pane.


Instances of the SafariValidateEvent class encapsulate a validate event. User interface elements such as contextual menu items and toolbar buttons send a validate event when they are about to display. You can prevent the element from displaying by listening for validate events and marking the element as disabled.


Instances of the SafariWebPageProxy class serve as a proxy objects, allowing objects outside of the web content to communicate with the SafariContentWebPage object.