Console Tab
A Console Tab in Salesforce is one of the individual tabs that appear at the top of a Service Console or Sales Console app, each representing an open record or workspace.
Definition
A Console Tab in Salesforce is one of the individual tabs that appear at the top of a Service Console or Sales Console app, each representing an open record or workspace. The console interface is built around the idea that an agent often needs several records open simultaneously, so the app holds them as parallel tabs rather than forcing a back-and-forth navigation through individual record pages.
The tab system has two levels. Primary tabs hold the main record an agent is working on (a Case, an Account, an Opportunity). Subtabs hold related records opened from inside a primary tab (the Contact who owns the Case, an attached Order). Subtabs stack underneath their primary, and closing the primary closes all its subtabs together. The structure mirrors a one-customer-many-related-records-open workflow that is common in support and sales.
How Console Tabs work in Lightning console apps
Primary tabs vs subtabs
A primary tab represents an independent record at the top level of the console: a Case the agent is solving, an Opportunity the rep is closing. A subtab is a related record nested inside a primary tab: the Contact linked to that Case, the Asset on the Opportunity. Subtabs are visually rendered below the primary tab as a second row, and they belong to that primary. Closing the primary tab closes every subtab beneath it.
How tabs are created
Tabs open through several routes: clicking a record link from inside the console (opens as a subtab of the current primary or as a new primary depending on the link source), navigating from a list view (new primary tab), opening from a global action (new primary), or programmatically through the Lightning workspaceAPI. The console app preserves which records were open when the user closes the app and re-opens them on next login if pinning is enabled.
Tab limits and what happens when you hit them
Console apps cap the number of open tabs (typically 20-25 primary tabs in Lightning, with subtabs counted separately under each primary). Hitting the cap surfaces a warning and prevents new tabs from opening; the user must close some first. This is intentional: console performance degrades sharply with too many open records because each tab keeps server state and DOM in memory.
The workspaceAPI for developers
Salesforce ships a Lightning workspaceAPI that lets LWC and Aura components inspect and manipulate console tabs programmatically. Methods include getEnclosingTabId, openTab, openSubtab, focusTab, closeTab, setTabLabel, setTabIcon, and refreshTab. A custom button in a Case detail can open a related Knowledge article as a subtab, refresh the Case on save, or close the current tab and open the next one in a queue. This is how custom console workflows like call wrap-up automation and guided next steps are built.
Pinned tabs and session restoration
A pinned tab persists across sessions: the user closes the console, comes back tomorrow, and the pinned tab reopens to the same record. Pinning is per user and per tab. Common patterns include pinning the queue list, an internal dashboard, or a Knowledge home tab. Subtabs can be pinned independently of their parent primary.
Tab styling, icons, and labels
Each tab has an icon and a label, both derived from the record object and Name field by default. Custom components can override these through workspaceAPI methods (setTabLabel, setTabIcon) to show progress indicators, warnings, or status. A common pattern is to set the tab icon to a red dot when the Case has an SLA breach, helping the agent spot at-risk Cases in their tab strip without clicking through.
Console Tabs vs the Navigation Menu vs Utility Bar
Console Tabs are the open-record tab strip at the top. The Navigation Menu is the row of top-level objects (Cases, Accounts, Reports). The Utility Bar is the pop-up tray at the bottom for tools like the softphone, notes, and history. Each is a separate piece of the console interface, configured separately in Setup. Conflating them is a common new-admin mistake.
How to configure and work with Console Tabs
Most Console Tab behavior is automatic in standard console apps. Customization happens through app Setup for tab persistence and pinning, and through workspaceAPI for programmatic tab control.
- Choose between Service Console and Sales Console apps
Both are Lightning console apps with the same tab system. Pick the app type when you create the app from Setup, App Manager, New Lightning App, and select Console Navigation.
- Set up the app primary objects and pinned tabs
From the app detail page in Setup, configure which objects appear in the Navigation Menu (Cases, Accounts, Knowledge) and which records should pin by default for new users.
- Configure tab session settings
Decide whether tabs should reopen on next login (User Personalization, Sessions to Reopen). Enable this for high-frequency agents who pick up where they left off. Disable it for shared kiosks.
- Build workspaceAPI components for custom tab control
For automation like after Case save, close this tab and open the next queue Case, build an LWC that calls workspaceAPI.closeTab and workspaceAPI.openTab. The methods are documented in the Lightning Web Components Developer Guide.
- Set up tab focus and refresh patterns
Components that listen for record changes can call refreshTab to update the tab content without a full page reload. This is the modern alternative to apex:actionPoller for keeping a console fresh.
- Train agents on tab limits
Agents who do not know there is a tab cap will hit the limit, get confused, and call IT. A one-paragraph training note covering the cap and how to close stale tabs prevents the ticket.
- Tabs are per user, not per role. Closing a tab affects only the current user; the same record stays open for any other agent who has it.
- The workspaceAPI is Lightning-only. Aura console apps used a different API; legacy code targeting the old API does not work in modern Lightning console apps.
- Subtab limits are separate from primary tab limits and counted per primary. Hitting the subtab cap is unusual but possible on complex Cases with many related records.
- Pinned tabs survive logout but not org refresh. Sandbox refreshes wipe pinned tab state for all users in the sandbox.
- Console apps require a console license; standard Lightning Experience users cannot open a console app without one.
Trust & references
Cross-checked against the following references.
- Lightning Console Apps OverviewSalesforce Help
Straight from the source - Salesforce's reference material on Console Tab.
- Work with Console TabsSalesforce Help
- Set Up a Lightning Console AppSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What are the two types of Console Tabs?
Q2. What's the main advantage of the tab model?
Q3. How are Subtabs different from Primary Tabs?
Discussion
Loading discussion…