@nut-tree/element-inspector/macos

Element Types

Element types are platform dependent. @nut-tree/element-inspector provides a set of factory functions to create WindowElementQuery objects. These factory functions are grouped by platform.

On macOS, the following element types are available:

application

An application element represents the top-level container for an application's user interface. It serves as the root element that contains all other UI elements within that application, such as windows, menus, and dialogs.

browser

A browser element represents a web browser view or web content area within an application. This includes embedded web views, Safari browser windows, or any control that displays web-based content with navigation capabilities.

busyIndicator

A busy indicator (also known as a spinner or activity indicator) shows that the application is processing a task. It typically appears as a spinning wheel or animated graphic to indicate ongoing activity without showing specific progress.

button

A button is an object that a user interacts with to perform an action such as the OK and Cancel buttons on a dialog box. The button control is a simple control to expose because it maps to a single command that the user wishes to complete.

cell

A cell element represents an individual data container within a table, outline view, or collection view. Cells can contain text, images, or other controls and are typically part of a larger data structure with rows and columns.

checkBox

A check box is an object used to indicate a state that users can interact with to cycle through that state. Check boxes either present a binary (Yes/No), (On/Off), or tertiary (On, Off, Indeterminate) option to the user.

colorWell

A color well is a control that displays a color and allows users to select or change that color. When clicked, it typically opens a color picker or color panel where users can choose from available colors or create custom colors.

column

A column element represents a vertical section within a table, outline view, or browser view. Columns organize data vertically and typically have headers that describe the type of content contained within that column.

comboBox

A combo box is a control that combines a text field with a drop-down list of selectable options. Users can either type directly into the text field or select from the predefined options in the drop-down menu.

dateField

A date field is a specialized text field designed for entering and displaying dates. It may include built-in validation for date formats and can integrate with date pickers or calendar controls for easier date selection.

disclosureTriangle

A disclosure triangle is a small triangular control used to expand or collapse sections of content. When pointing right, the content is collapsed; when pointing down, the content is expanded. Common in outline views and expandable lists.

dockItem

A dock item represents an application icon or file in the macOS Dock. Users can click dock items to launch applications, switch between running applications, or access recently used documents and folders.

drawer

A drawer is a sliding panel that extends from the edge of a window to provide additional interface elements or information. Drawers can slide out from any edge of a window and are commonly used for supplementary tools or settings.

grid

A grid control organizes content in a two-dimensional layout with rows and columns. Unlike tables, grids are typically used for displaying collections of similar items, such as photos, icons, or tiles, in a structured visual arrangement.

group

A group control represents a logical collection of related interface elements. Groups provide visual and structural organization, often with a border or background, to separate different sections of functionality within a window or view.

growArea

A grow area (or resize corner) is a control that allows users to resize a window by dragging. It's typically located in the bottom-right corner of resizable windows and appears as a small textured area or corner indicator.

handle

A handle is a control element that users can drag to perform actions such as resizing, moving, or adjusting the position of interface elements. Examples include splitter handles between panes or drag handles on movable items.

heading

A heading element represents a title or section header within a document or interface. Headings provide hierarchical structure and help organize content into logical sections, similar to headings in a document or web page.

helpTag

A help tag (tooltip) is a small pop-up window that appears when hovering over an interface element. It provides brief explanatory text or additional information about the function or purpose of the element underneath the cursor.

image

Image controls display graphical content such as photos, icons, diagrams, or illustrations. They can be static decorative elements or interactive controls that respond to user actions like clicking or dragging.

incrementor

An incrementor (stepper) is a control with up and down arrow buttons that allows users to increase or decrease a numeric value incrementally. It's often paired with a text field to show the current value and allow direct editing.

layoutArea

A layout area represents a region within an interface that contains and organizes other elements according to specific layout rules. It defines how child elements are positioned and sized within the available space.

layoutItem

A layout item is an individual element within a layout area. It represents a single component that participates in the parent layout's arrangement system, following the layout rules defined by its container.

levelIndicator

A level indicator is a control that displays a continuous or discrete level value, such as volume, signal strength, or battery level. It typically appears as a horizontal bar that fills based on the current level value.

list

A list control displays a collection of items in a vertical arrangement. Users can select one or more items from the list, and lists often support features like sorting, filtering, and keyboard navigation through the items.

matte

A matte is a background or container element that provides a visual foundation for other interface elements. It typically has a subtle texture or color that helps define interface boundaries and visual hierarchy.

A menu control displays a collection of commands or options that users can select. Menus can appear as drop-down lists from menu bar items, contextual menus from right-clicks, or pop-up menus from various interface elements.

A menu bar is the horizontal bar typically located at the top of the screen (in macOS) that contains the main menu items for an application. It provides access to the application's primary commands and options organized into categories like File, Edit, and View.

A menu bar item is an individual item within the menu bar, such as "File," "Edit," or "Help." When clicked, menu bar items typically display drop-down menus containing related commands and options.

A menu button is a control that looks like a button but displays a menu when clicked or pressed. It combines the visual appearance of a button with the functionality of a menu, often indicated by a small arrow or other visual cue.

A menu item represents an individual command or option within a menu. Menu items can perform actions when selected, open submenus, or represent toggleable states. Examples include "New," "Save," "Copy," and "Paste."

outline

An outline control displays hierarchical data in an expandable tree structure. Users can expand and collapse branches to navigate through different levels of the hierarchy, similar to a file system browser or organizational chart.

popUpButton

A pop-up button displays the currently selected option and shows a menu of alternative choices when clicked. Unlike combo boxes, pop-up buttons don't allow text entry and limit selection to the predefined options in the menu.

A popover is a temporary view that appears above other content when triggered by user interaction. Popovers contain additional controls or information related to the element that triggered them and typically include an arrow pointing to the source.

progressIndicator

A progress indicator shows the completion status of a lengthy operation. It can be determinate (showing specific progress as a percentage) or indeterminate (showing that work is happening without indicating completion time).

radioButton

A radio button consists of a small circular button and associated text that represents one choice in a group of mutually exclusive options. Only one radio button in a group can be selected at a time, and selecting one deselects the others.

radioGroup

A radio group is a container that holds multiple radio buttons representing mutually exclusive choices. The group ensures that only one radio button within the group can be selected at any time and manages the selection behavior.

relevanceIndicator

A relevance indicator shows the significance or ranking of an item, commonly used in search results or rating systems. It typically appears as a series of dots, stars, or bars that indicate how closely an item matches search criteria or user preferences.

row

A row element represents a horizontal line of data within a table, list, or outline view. Rows contain cells or other elements that display related information organized across the width of the container.

ruler

A ruler is a measurement guide typically found in document editing applications. It shows units of measurement (inches, centimeters, points) and helps users position text, images, and other elements with precision.

rulerMarker

A ruler marker is an indicator on a ruler that shows specific positions such as tab stops, margins, or indents. Users can typically drag ruler markers to adjust document formatting and layout settings.

scrollArea

A scroll area is a container that can display content larger than its visible bounds. When content exceeds the visible area, scroll bars appear to allow users to navigate through the hidden portions of the content.

scrollBar

A scroll bar enables users to navigate through content that extends beyond the visible area of a container. It consists of a track, thumb (draggable indicator), and optional arrow buttons for fine control over scrolling position.

sheet

A sheet is a modal dialog that slides down from the title bar of its parent window. Sheets are used for document-specific tasks and maintain a clear relationship with the window that presented them, unlike standalone dialog boxes.

slider

A slider control allows users to select a value from a continuous range by dragging a thumb along a track. Sliders are commonly used for settings like volume, brightness, or any numeric value that benefits from analog-style input.

splitGroup

A split group is a container that divides available space between multiple panes or views. The split group manages the overall layout and resizing behavior of the split arrangement.

splitter

A splitter is a divider between panes in a split view that users can drag to resize the adjacent panes. It provides visual separation and interactive control over how space is allocated between different areas of the interface.

staticText

Static text is a read-only text element that displays information to users without accepting input. It's used for labels, instructions, status messages, and other textual content that users need to read but not modify.

systemWide

A system-wide element represents interface components that span across multiple applications or the entire system, such as the menu bar, dock, or system-level dialogs that appear above all other content.

tabGroup

A tab group is a container control that organizes multiple pages of content using tabs. Users can switch between different pages by clicking on the corresponding tab, similar to file folder tabs or browser tabs.

table

A table control displays data in rows and columns with optional headers. Tables are ideal for presenting structured data where users need to compare information across different categories or perform operations on specific data items.

textArea

A text area is a multi-line text input control that allows users to enter and edit larger amounts of text. Unlike single-line text fields, text areas can contain line breaks and typically include scrolling capabilities for longer content.

textField

A text field is a single-line input control where users can enter and edit text. Text fields are commonly used for names, addresses, search queries, and other short text inputs throughout user interfaces.

timeField

A time field is a specialized input control designed for entering and displaying time values. It may include built-in formatting for hours, minutes, and seconds, and can integrate with time picker controls for easier time selection.

A toolbar is a horizontal or vertical bar containing buttons and other controls that provide quick access to frequently used commands and tools. Toolbars typically appear below the menu bar or along the edges of windows.

unknown

An unknown element represents an interface component that doesn't match any of the standard element types. This classification is used when the system cannot determine the specific type of an element or when dealing with custom controls.

valueIndicator

A value indicator displays a numeric or measurable value in a visual format. Examples include gauges, meters, or any control that represents a current value within a defined range, such as CPU usage or disk space indicators.

window

A window is a rectangular area on screen that contains an application's user interface elements. Windows have frames with title bars, close/minimize/maximize buttons, and content areas where the application's main interface is displayed.