# Tooltips for Toolbar Icons with macOS

**URL:** <https://forums.sketchup.com/t/tooltips-for-toolbar-icons-with-macos/343560>\
**Category:** Ruby API\
**Tags:** windows\
**Created:** [January 6, 2026, 7:20am UTC](https://forums.sketchup.com/t/tooltips-for-toolbar-icons-with-macos/343560 "2026-01-06T07:20:38Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![medeek](https://sea2.discourse-cdn.com/sketchup/user_avatar/forums.sketchup.com/medeek/32/10675_2.png) [@medeek](https://forums.sketchup.com/u/medeek)\
**Post date:** [January 6, 2026, 7:20am UTC](https://forums.sketchup.com/t/tooltips-for-toolbar-icons-with-macos/343560/1 "2026-01-06T07:20:38Z")

</div>

A few weeks ago I made an update to the Truss and Wall plugins to try and fix a long standing macOS issue with my toolbars, more specifically with the way the tooltips were displayed.

After some testing by certain power users it was found that when the toolbars are oriented vertically as shown below the tooltip **does show** but the icon does not “darken” or “depress” as it does in Windows.

 ![MacOs Tooltips Vertical](https://global.discourse-cdn.com/sketchup/original/3X/6/5/6569f0ad38a756074282b866e5ab711ff84e3a2a.jpeg)

When the toolbars are oriented horizontally the tooltips **do not** display at all:

 ![MacOs Tooltips Horizonal](https://global.discourse-cdn.com/sketchup/original/3X/7/2/724e0a40ad90b2499a5e0468a3d688bc92db8060.jpeg)

My typical code that defines these toolbar icons is given in the example below:

```auto
cmd3.small_icon = "images/mdkplg_tool_icon48_4.png"
cmd3.large_icon = "images/mdkplg_tool_icon64_4.png"
cmd3.tooltip = 'Draw Truss Set'
cmd3.status_bar_text = 'Draw Truss Set'
cmd3.menu_text = 'Truss Set'
toolbar = toolbar.add_item cmd3

```

Am I doing something wrong here or is this a known issue with macOS. This question is mostly directly at other developers and to the SketchUp gurus who are a pay grade above me.

---

<div class="post-metadata">

**Author:** ![rtches](https://sea2.discourse-cdn.com/sketchup/user_avatar/forums.sketchup.com/rtches/32/131827_2.png) [@rtches](https://forums.sketchup.com/u/rtches)\
**Post date:** [January 6, 2026, 7:34am UTC](https://forums.sketchup.com/t/tooltips-for-toolbar-icons-with-macos/343560/2 "2026-01-06T07:34:35Z")

</div>

this is a known issue with macOS for a long time

---

<div class="post-metadata">

**Author:** ![medeek](https://sea2.discourse-cdn.com/sketchup/user_avatar/forums.sketchup.com/medeek/32/10675_2.png) [@medeek](https://forums.sketchup.com/u/medeek)\
**Post date:** [January 6, 2026, 7:35am UTC](https://forums.sketchup.com/t/tooltips-for-toolbar-icons-with-macos/343560/3 "2026-01-06T07:35:05Z")

</div>

This is what ChatGPT responded with in answer to my question:

You’re not doing anything “wrong” in that snippet — you’ve run into a long-standing **SketchUp-for-macOS toolbar/palette bug/limitation** , not a Ruby API usage issue.

## What’s going on (macOS)

On macOS, extension toolbars are those floating **Tool Palettes**. There’s a known issue where:

- **If a palette is horizontal (snapped to the top edge), tooltips don’t show.** [SketchUp Community+2SketchUp Community+2](https://forums.sketchup.com/t/extension-tool-tips/169303)
- Switching orientation often requires a **SketchUp restart** before tooltips behave again. [SketchUp Community+1](https://forums.sketchup.com/t/extension-tool-palette-issues/122781)
- Related: “hover/press feedback” and command appearance updates are also inconsistent for plugin palettes on macOS (validation/state/visual response not updating as expected). [GitHub+1](https://github.com/SketchUp/api-issue-tracker/issues/210)

SketchUp’s own API issue tracker has this logged as an API/UI bug affecting **tooltips, status bar text, and command appearance** for **plugin toolbars (palettes)** on macOS. [GitHub](https://github.com/SketchUp/api-issue-tracker/issues/210)

## Why your icon doesn’t “darken/depress” like Windows

Windows and macOS are using different native UI implementations for these toolbars/palettes. On macOS, extension palettes have multiple documented UI behavior gaps (including the “pressed/highlight” and command-state rendering). [GitHub+1](https://github.com/SketchUp/api-issue-tracker/issues/210)

If what you _really_ want is a “toggled/checked” look (not just a momentary press effect), the _intended_ API mechanism is a validation proc:

```auto
cmd3.set_validation_proc {
  tool_active? ? MF_CHECKED : MF_UNCHECKED
}

```

…but note: **on macOS palettes this has historically been unreliable** (it’s part of the same family of issues). [GitHub+1](https://github.com/SketchUp/api-issue-tracker/issues/210)

## One small code nit (not the cause, but worth fixing)

This line:

```auto
toolbar = toolbar.add_item cmd3

```

`add_item` returns an integer id, so that overwrites your toolbar object. Prefer:

```auto
toolbar.add_item(cmd3)

```

Again: this isn’t what’s breaking tooltips; it just prevents you from adding more items afterwards.

## Practical workarounds you can suggest to Mac users (today)

1. **Keep extension palettes vertical** (dock to the left side) if they want tooltips. [SketchUp Community+2SketchUp Community+2](https://forums.sketchup.com/t/extension-tool-tips/169303)
2. If they change orientation, **quit + relaunch SketchUp** to get tooltips back. [SketchUp Community+1](https://forums.sketchup.com/t/extension-tool-palette-issues/122781)
3. If you want better “remembered” palette behavior, prefer `toolbar.restore` over `toolbar.show` (more about visibility/positioning than tooltips, but it’s the recommended pattern on Mac). [SketchUp Community](https://forums.sketchup.com/t/managing-tools-bars-on-mac/123564)
4. Encourage power users to place a few critical commands in the **main (top) toolbar** via Customize Toolbar, since the worst behavior tends to be with separate extension palettes. [GitHub](https://github.com/SketchUp/api-issue-tracker/issues/210)

Bottom line: **your command setup is fine** ; the tooltip + visual feedback problems you’re seeing match a **known macOS palette issue in SketchUp**.

---

<div class="post-metadata">

**Author:** ![ateliernab](https://sea2.discourse-cdn.com/sketchup/user_avatar/forums.sketchup.com/ateliernab/32/198399_2.png) [@ateliernab](https://forums.sketchup.com/u/ateliernab)\
**Post date:** [January 6, 2026, 8:28am UTC](https://forums.sketchup.com/t/tooltips-for-toolbar-icons-with-macos/343560/4 "2026-01-06T08:28:16Z")

</div>

Yep, one of the reasons I can’t wait for the new ui.

For this long lasting bug to be fixed

---

<div class="post-metadata">

**Author:** ![DanRathbun](https://sea2.discourse-cdn.com/sketchup/user_avatar/forums.sketchup.com/danrathbun/32/500_2.png) [@DanRathbun](https://forums.sketchup.com/u/DanRathbun)\
**Post date:** [January 6, 2026, 7:13pm UTC](https://forums.sketchup.com/t/tooltips-for-toolbar-icons-with-macos/343560/5 "2026-01-06T19:13:43Z")

</div>

> **I second the AI suggestion here ...**
>
> > [@medeek](#):
> >
> > ## One small code nit (not the cause, but worth fixing)
> > 
> > This line:
> > 
> > ```auto
> > toolbar = toolbar.add_item cmd3
> > 
> > ```
> > 
> > `add_item` returns an integer id, so that overwrites your toolbar object. Prefer:
> > 
> > ```auto
> > toolbar.add_item(cmd3)
> > 
> > ```
> > 
> > Again: this isn’t what’s breaking tooltips; it just prevents you from adding more items afterwards.

… except the AI is incorrect (as it often is) with regard to the return value.  
Here the AI is **confounding** [`Sketchup::Menu#add_item`](https://ruby.sketchup.com/Sketchup/Menu.html#add_item-instance_method) with [`UI::Toolbar#add_item`](https://ruby.sketchup.com/UI/Toolbar.html#add_item-instance_method).  
It is the **former** that returns an `Integer` ID.

The [`UI::Toolbar#add_item`](https://ruby.sketchup.com/UI/Toolbar.html#add_item-instance_method) method is meant for call chaining. Ex:

```ruby
toolbar.add_item(cmd1).add_item(cmd2).add_item(cmd3)

```

The usage pattern …

```ruby
toolbar = toolbar.add_item(cmd)

```

… comes from a **poor** example in the SketchUp Ruby API documentation.

It really makes **no good sense** to assign the `toolbar` reference to the return value of [`toolbar.add_item`](https://ruby.sketchup.com/UI/Toolbar.html#add_item-instance_method) because the code **must have already** assigned a [`UI::Toolbar`](https://ruby.sketchup.com/UI/Toolbar.html) object to the `toolbar` reference (likely via use of the [class constructor](https://ruby.sketchup.com/UI/Toolbar.html#new-class_method).)