Toolbar Controls

Native application toolbars contain special controls called toolbar items. The standard toolbar items are buttons (including menu buttons), button groups, and search fields. They are created using a special API and may be rendered differently than the analogous content area controls. In the macOS 26 Liquid Glass UI, toolbar controls are large and use glass effects. In prior UIs, toolbar controls use a textured style with a slightly larger size. In addition, toolbar buttons that have both a label and an icon may use a distinct rendering.

Unlike AppKit, VAqua does not provide a custom API for creating toolbars. Instead, it attempts to provide appropriate layouts and renderings for components located in a non-floatable JToolBar. Recommended toolbar components are buttons, segmented buttons, popup buttons, and text fields (using the search style). In general, toolbar components should not be configured with a style or a size (except for the search style for text fields).

VAqua automatically assigns the toolbarItem style to a toolbar button that displays both a label and an icon. Configuring this style explicitly may be useful if an icon-only button shares a toolbar with buttons that display both icons and labels. Buttons using the toolbarItem style have a distinct rendering that does not mix well with other components.

Segmented buttons can be used to simulate a toolbar button group. For consistency, when segmented buttons are used to simulate a button group, segmented buttons should also be used for individual buttons (using a segmentPosition of only).

One implication of this approach is that components that are to be displayed inside a JToolBar may not return the toolbar-specific layout sizes (e.g., preferred size) until they are actually added as children or descendants of a JToolBar. Most applications will not be affected by this limitation, but applications that perform calculations using the layout sizes should be sure to perform those calculations only after the components are in the JToolBar hierarchy.

Toolbar Panels