Toolbars

A toolbar provides convenient access to frequently used commands, controls, navigation, and search. Items sit in glass capsules that float in a window’s titlebar.

Preview

Anatomy

A group is a Liquid Glass capsule. Three layers make the glass:

• Keyline. A 0.5px dark line outside the shape, heavier on the rounded ends.
• Speculars. A 1px white highlight on the top and bottom inner edges.
• Fill. A soft vertical gradient: darkest (about #F1F1F1 on white) a third of the way down, clearing to white at the bottom.

The glass is translucent, so over the #E6E6E6 sidebar it reads a few steps darker than over a white titlebar. The shadow is almost nothing, 0 8px 15px at 2 to 4% (--p-shadow-glass-control). Depth comes from the rim, not the shadow. The regular size is 36px tall with an 18px radius, and the small size is 24px with a 12px radius. Both are true capsules, so the corners need no squircle.

Items are 32px cells with 2px of padding at each end of the group, so three icons make a 100px group. Glyphs are 13px (10px in small) in #1A1A1A. Hover and pressed states show a 32×28px pill with a 14px radius, inset 4px from the capsule (24×20px with a 10px radius in small). The pill is a blend rather than a flat fill: black at 10% (#E6E6E6 on white), so it follows the gradient underneath. A group with dividers spaces its items 3px apart. Its dividers are 1×20px lines (1×16px in small) at black 15%.

Placement and search

In a window, groups sit in the titlebar 8px from the band edges and 8px apart. The first group sits 16px after the zoom light, and the title follows it 8px later. See windows for the three titlebar layouts. The flat macOS 26 slots (.p-window-toolbar-btn in a .p-window-toolbar-flat row) remain for existing layouts, but glass groups are the default look.

Toolbar search is the standard search field: the 24px capsule matches the small toolbar scale and the 36px -xlarge step matches the regular one.

States

Hover and [aria-pressed="true"] (or .p-active) show the pill. Disabled buttons drop their ink to #BFBFBF and ignore the pointer. Focus uses the standard ring, 3px at 50% blue, inset to follow the pill shape.

When the window loses focus (.p-window-inactive on the window, or .p-inactive on the glass itself), the glass flattens. The gradient and speculars drop away and only the keyline remains.

Dark mode

Dark glass is additive light: white at about 6% at the top rising to 15% at the bottom (about #2C2C2C to #3F3F3F on #1E1E1E). It sits inside a near-black keyline, with bright 1px rims top and bottom. The hover pill and dividers turn lighter than the glass: white at 9% and 18%. Ink is #F5F5F5. Both .p-dark-mode and .p-auto-dark-mode are supported.

Code

<div class="p-toolbar-group" role="toolbar" aria-label="View options">
  <button class="p-toolbar-btn" aria-pressed="true" aria-label="Grid view">
    <i class="ph-bold ph-squares-four"></i>
  </button>
  <div class="p-toolbar-divider" role="separator"></div>
  <button class="p-toolbar-btn" aria-label="List view">
    <i class="ph-bold ph-list"></i>
  </button>
</div>

Icon-only buttons need aria-labels, and toggles should carry aria-pressed so state is announced. With prefers-reduced-transparency the glass becomes an opaque gradient with the same ramp, and with prefers-contrast: more the keyline becomes a solid 1px line in the ink color.