Custom Console Component
A Custom Console Component in Salesforce is an admin-added or developer-built Lightning component, Visualforce page, or Canvas app that you place in a defined region of a Salesforce console app.
Definition
A Custom Console Component in Salesforce is an admin-added or developer-built Lightning component, Visualforce page, or Canvas app that you place in a defined region of a Salesforce console app. Those regions include the page sidebars, the utility bar at the bottom, the highlights panel, and related-list areas. The component adds functionality the standard layout does not provide, such as showing data from an outside system next to the open record, giving agents a notes or scratchpad tool, or embedding a third-party web app inside the workspace.
Custom Console Components exist because agents who work inside a console need fast access to context that lives outside the current record. A support agent on a case might need order history, contract terms, and a billing snapshot. Pulling that context into the console keeps the agent in one screen instead of switching tabs and apps.
How Custom Console Components fit into a console app
The console regions a component can occupy
A console app is built from a Lightning page in the Lightning App Builder, plus a utility bar that the standard layout does not give you. Custom Console Components slot into both. On the page itself you can drop a component onto a sidebar, the main region, the highlights panel area, or alongside related lists. The Three Regions template gives you a 50 percent main region with two 25 percent sidebars, which suits wide agent monitors. Pinned-region templates keep a header or sidebar in place while the agent moves between subtabs, so a component there stays visible the whole time. The utility bar is a separate fixed footer that opens tools in docked panels. Where you place a component changes how it behaves. A pinned sidebar component is always on screen, good for a timer or an agent-state widget. A utility-bar component is hidden until the agent clicks its icon, good for an occasional tool like a notes panel or a knowledge lookup. Picking the right region is the first design decision, because it sets how often the agent sees the component and how much room it has.
Lightning, Visualforce, or Canvas
A Custom Console Component can be one of three build types, and the choice shapes everything after it. A Lightning Web Component (or an older Aura component) is the current path for new work. You configure it in the metadata file, expose it, and add it on a console page or in the utility bar. A Visualforce page is the legacy path. Visualforce components still render on console pages, but the utility bar does not support Visualforce pages or components, so a Visualforce footer tool is not an option in a Lightning console app. A Canvas app is the right pattern when you need to embed an existing external web application. Canvas renders that app in an iframe, hands it a signed request carrying the user and org identity, and lets it draw any web content. Teams use Canvas to bring a billing portal, an analytics dashboard, or a chat tool into the workspace without rebuilding it in Salesforce. For most net-new components, Lightning is the answer; reach for Canvas only when the thing you want to show already lives on the open web.
Configuring a Lightning Web Component for the console
To use an LWC as a Custom Console Component, you edit its js-meta.xml configuration file. Set isExposed to true so the component appears in the App Builder and App Manager. Then declare the targets where it can be used. The lightning__AppPage target makes it available to drop onto a console Lightning page, including as a navigation item in a custom console app. The lightning__UtilityBar target makes it available to add to the app utility bar. A component can declare both. Inside a targetConfigs block you expose design properties, so an admin can configure the component from App Manager without touching code, for example passing a default record type or a feature toggle. You can also add a single SVG file named after the component to give it a custom icon in the utility bar; there is a one-SVG-per-folder limit. After the metadata is set, you open the console app, add the component to a page region or the utility bar, and assign the app. No Apex is required for placement, though the component itself may call Apex for data.
Talking to the console with the Lightning Console JavaScript API
A component that ignores the rest of the console feels like a static box. The Lightning Console JavaScript API is what makes it feel native. From a Lightning component you can read the active workspace tab, open new tabs and subtabs, set a tab label or icon, refresh the open record, and fire toast notifications. There is a Workspace API for tab control, a Utility Bar API for opening and closing the docked panel and setting its label or highlight state, and a Navigation Item API for the items along the top. A notes utility, for example, can read which case the agent is viewing and save the note against it, then flash its utility-bar icon when there is unsaved work. Without these APIs the component has no idea what record the agent is on. With them, the component participates in the agent workflow and reacts as the agent moves around. This API is the Lightning replacement for the older toolkit described next, and it is the one to use for any Lightning console build.
The Classic console and the Integration Toolkit
Before Lightning Experience, console apps ran in Salesforce Classic and Custom Console Components were almost always Visualforce pages. Those pages talked to the console through the Salesforce Console Integration Toolkit, a browser JavaScript API usually written as sforce.console. It did the same kinds of jobs the Lightning Console JavaScript API does now: open primary tabs and subtabs, refresh content, set tab titles, and react to events. A Visualforce page using the toolkit had to load the toolkit first, with different setup depending on whether the code ran inside a Visualforce page or a third-party domain. Many of these older pages still work in Lightning Experience as is, through a compatibility bridge that maps a set of Classic toolkit methods onto the Lightning API. That compatibility is helpful for migration, but it is not a reason to build new components on the toolkit. If you are starting fresh, build a Lightning Web Component and use the Lightning Console JavaScript API. Treat the Classic toolkit as something you maintain, not something you adopt.
Designing components agents actually use
A Custom Console Component takes up screen space that the agent could be using for the record. That makes restraint part of the design. Salesforce suggests keeping the utility bar to a small number of utilities with short labels, because a crowded footer is hard to scan under call pressure. Performance matters just as much. A component that paints in well under a second feels instant; one that stalls on an external call feels broken, and agents stop opening it. When the data comes from an outside system, Salesforce Connect external objects are often a cleaner path than a bespoke API call inside every component, because external objects render like native objects and can be queried and related like them. Plan for the empty and error states too, since an agent who sees a blank panel does not know if it is loading or broken. The components that survive in production are the ones that load fast, show only what the agent needs, and keep working when the network is slow. Build for the agent on their worst day, not the demo on a fast laptop.
How to add a Custom Console Component to a console app
Here is the common path: add an existing Lightning component to a console app as a Custom Console Component, either on the page or in the utility bar. This assumes the component is already built and exposed with the right target.
- Expose the component for the console
In the component js-meta.xml file, set isExposed to true and add the target you need: lightning__AppPage to place it on a console page, or lightning__UtilityBar to add it to the utility bar. Add design properties under targetConfigs if admins should configure it.
- Open the console app in Setup
Go to Setup, then App Manager. Find your Lightning console app and choose Edit. This opens the app in the Lightning Experience App Manager where both the pages and the utility bar are configured.
- Place it on a page or in the utility bar
For a page region, edit the relevant console Lightning page in the Lightning App Builder and drag your component into a sidebar, the main region, or the highlights area. For the utility bar, open the Utility Bar Items section, add a utility, and select your component.
- Set properties and save
Fill in any exposed design properties, set the utility label and icon if it is a utility, then save. For a page, activate it and assign it to the app and the right profiles or app contexts.
- Verify in the running console
Open the console app as an agent would, navigate to a record, and confirm the component renders, reads the active record, and responds when you move between tabs.
Lets the component be dropped onto a console Lightning page region, such as a sidebar or the main area, or used as a navigation item.
Lets the component be added to the app utility bar as a docked panel tool, hidden until the agent clicks its icon.
Expose inputs that an admin can fill in from App Manager, so one component can be reused with different configuration and no code change.
Add a single SVG file named for the component to give a utility-bar item a custom icon; only one SVG is allowed per component folder.
- The utility bar does not support Visualforce pages or components. A footer tool must be a Lightning component.
- A utility bar built through the App Manager wizard can be assigned to only one app; assigning the same bar to several apps needs the Metadata API.
- Keep the utility bar short. Salesforce recommends no more than about ten utilities with brief labels so agents can scan it quickly.
- Use the Lightning Console JavaScript API for new components, not the Classic sforce.console toolkit, which is kept working only for migration.
Prefer this walkthrough as its own page? How to Custom Console Component in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Custom Console Component.
Hands-on resources to go deeper on Custom Console Component.
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. Which three building blocks can a Custom Console Component be made from?
Q2. Why would a team embed an external web app as a Canvas-based Custom Console Component?
Q3. Which API lets a Custom Console Component interact with the rest of the console?
Discussion
Loading discussion…