Safari AppleScript Commands and Properties on macOS

This article provides a comprehensive reference to the AppleScript dictionary exposed by the Safari web browser on macOS. It covers the core classes, properties, and specific commands available in the Safari Suite and Standard Suite for automating web browsing tasks, managing tabs and windows, extracting webpage data, and executing JavaScript directly through macOS automation scripts.

Safari Suite Commands

The Safari Suite contains commands specific to web browsing operations.

  • add reading list item (verb): Adds a new item to the user's Reading List.
    • Direct Parameter (text): The URL of the item to be added.
    • and preview text (text, optional): A string of text to use as the preview for the item.
    • with title (text, optional): A string to specify the title of the item.
  • do JavaScript (verb): Applies a string of JavaScript code to a document. Note that "Allow JavaScript from Apple Events" must be enabled in Safari's Develop menu for this command to work.
    • Direct Parameter (text): The JavaScript code to evaluate.
    • in (tab or document, optional): The specific tab or document where the script should run.
    • Result (any): Returns the result of the JavaScript evaluation.
  • email contents (verb): Emails the contents of a specified tab or document using the default macOS mail client.
    • of (tab or document, optional): The target tab or document to email.
  • search the web (verb): Searches the web using Safari's currently selected default search engine.
    • for (text): The search query string.
    • in (tab or document, optional): The specific tab or document in which to load the search results.
  • show bookmarks (verb): Opens and displays the bookmarks view in Safari.

Safari Suite Classes and Properties

Safari's scripting architecture revolves around three primary objects: document, tab, and window.

Document

A document represents an open webpage. In modern tabbed browsing, a window's document corresponds to the webpage loaded in its currently active tab.

  • URL (text, read/write): The current web address of the document. Setting this property navigates the document to the new URL.
  • source (text, read-only): The raw HTML source code of the loaded webpage.
  • text (text, read-only): The rendered plain text content of the webpage, stripped of HTML tags.
  • name (text, read-only): The title of the webpage or document.
  • modified (boolean, read-only): Returns true if the document has been modified since it was last saved or loaded.

Tab

A tab represents an individual browser tab contained within a window element.

  • URL (text, read/write): The URL currently loaded in the tab. Modifying this value forces the tab to load the new URL.
  • source (text, read-only): The raw HTML source code of the webpage inside the tab.
  • text (text, read-only): The plain text content of the webpage inside the tab.
  • index (integer, read-only): The ordered position of the tab within its parent window, counting from left to right.
  • name (text, read-only): The title of the webpage currently displayed in the tab.
  • visible (boolean, read-only): Indicates whether the tab is currently visible on the screen.

Window (Safari Suite Extensions)

Safari extends the Standard Suite window class with properties to manage tabbed browsing. A window contains tabs as elements.

  • current tab (tab, read/write): The active, currently visible tab in the window. You can switch active tabs by setting this property to a different tab object.
  • document (document, read-only): The document associated with the window's active tab.

Standard Suite Commands and Properties

Safari also exposes the AppleScript Standard Suite, which is required to manipulate application states, windows, and the creation of new elements.

Standard Commands

  • make: Creates a new object. Commonly used in Safari as make new document (opens a new window/tab depending on preferences) or make new tab at end of tabs of window 1.
  • close: Closes a specified object, such as a window, tab, or document.
  • count: Returns the number of elements of a particular class within an object (e.g., counting tabs in a window).
  • delete: Deletes an object (can be used to close tabs).
  • duplicate: Duplicates an object.
  • exists: Verifies if a specific object (like a tab or window) is present.
  • move: Moves an object to a new location (e.g., reordering tabs across or within windows).
  • open: Opens a file or URL in Safari.
  • print: Prints a document or window.
  • quit: Terminates the Safari application.

Standard Application Properties

  • frontmost (boolean, read-only): Indicates whether Safari is the active, frontmost application on macOS.
  • name (text, read-only): The name of the application ("Safari").
  • version (text, read-only): The version number of the Safari application.

Standard Window Properties

  • bounds (rectangle, read/write): A four-item list of integers specifying the bounding coordinates (left, top, right, bottom) of the window on the screen.
  • closeable (boolean, read-only): Indicates if the window has a close box.
  • id (integer, read-only): The unique identifier for the window, persistent for the life of the window.
  • index (integer, read/write): The front-to-back ordering number of the window. Setting a window's index to 1 brings it to the front.
  • miniaturizable (boolean, read-only): Indicates if the window can be minimized to the Dock.
  • miniaturized (boolean, read/write): Indicates whether the window is currently minimized to the Dock. Setting this to true minimizes the window.
  • name (text, read-only): The title of the window (usually matches the title of the current tab).
  • resizable (boolean, read-only): Indicates if the window size can be changed.
  • visible (boolean, read/write): Indicates whether the window is currently visible on the screen.
  • zoomable (boolean, read-only): Indicates if the window can be zoomed (maximized).
  • zoomed (boolean, read/write): Indicates whether the window is currently zoomed. Setting this to true maximizes the window.