Pin and lock page tabs

In HERE Core UI Components v24.1 or later, you can control page tab positioning and interaction through pinning. There are two modes: platform-led locking, where developers designate specific page tabs as fixed and non-closable, and user-led pinning, where end users pin frequently used tabs to the front of the tab strip.

Both modes use the pinned property of the Page interface.

How it works

The pinned property accepts one of two values:

pinned value	Set by	Closable	Draggable	Layout locked	Tab strip position
'platform'	Developer	No	No	Yes	Leftmost
'user'	End user	Yes (close button hidden; unpin to close)	Yes (within pinned section)	No	After platform-pinned tabs
Omitted	—	Yes	Yes	No	After all pinned tabs

Tab strip order is always enforced as: platform-pinned → user-pinned → normal tabs. This ordering also applies in the tab search dropdown.

For the end-user experience including context menu items and tab search interactions, see Parts of windows in Browser.

Platform-led locking

To designate a page tab as locked, set pinned: 'platform' on the page. Platform-pinned tabs are positioned at the absolute start of the tab strip. Users cannot close, drag, or reorder them, and the page layout is automatically locked (equivalent to setting isLocked: true).

You can set pinned when creating a window:

const windowRequest: BrowserCreateWindowRequest = {
  workspacePlatform: {
    pages: [
      {
        pageId: "locked-dashboard",
        title: "Dashboard",
        pinned: "platform",
        layout: {
          content: [
            {
              type: "stack",
              content: [
                {
                  type: "component",
                  componentName: "view",
                  componentState: { url: "https://example.com/dashboard" }
                }
              ]
            }
          ]
        }
      },
      {
        pageId: "normal-page",
        title: "Research",
        layout: { /* ... */ }
      }
    ]
  }
};

You can also update a page at runtime using the Browser module:

const browser = fin.Platform.wrapSync(identity).Browser;
const browserWindow = browser.wrapSync(windowIdentity);

// Lock a page tab
await browserWindow.updatePage({
  pageId: "my-page-id",
  page: { pinned: "platform" }
});

User-led pinning

Users can pin and unpin tabs through the right-click context menu and the tab search dropdown. See Parts of windows in Browser for details on the user-facing interactions.

To programmatically pin or unpin a tab as a user action:

// Pin
await browserWindow.updatePage({
  pageId: "my-page-id",
  page: { pinned: "user" }
});

// Unpin
await browserWindow.updatePage({
  pageId: "my-page-id",
  page: { pinned: null }
});

Custom context menu templates

If you build a custom page tab context menu template, two new values are available on PageTabContextMenuOptionType:

• PageTabContextMenuOptionType.Pin — sets pinned: 'user' on the page
• PageTabContextMenuOptionType.Unpin — clears the pinned state

For details on customizing context menus, see Customize Browser features.

Persistence

The pinned state is persisted as part of the page definition in workspacePlatform.pages. When a workspace is saved and restored, pinned states and tab ordering are preserved.

Relationship to content locking

Page pinning is related to but distinct from content locking. Content locking (isLocked) prevents changes to the layout within a page. Platform-led pinning (pinned: 'platform') controls the page tab behavior — preventing close, drag, and reorder — and additionally locks the page layout automatically. You do not need to set both isLocked and pinned: 'platform'; the pinned state implies layout locking.