Custom Links
Custom Links in Salesforce are admin-configured URL-based actions that appear on record pages, list views, and home pages, allowing users to navigate to external websites, internal Salesforce pages, or Visualforce pages with dynamic context from the current record.
Definition
Custom Links in Salesforce are admin-configured URL-based actions that appear on record pages, list views, and home pages, allowing users to navigate to external websites, internal Salesforce pages, or Visualforce pages with dynamic context from the current record. Each Custom Link has a label, a URL (which can include merge fields like {!Account.Name} to inject record data), a display type (link, button, sidebar component), and a behavior (open in new window, open in same window, open in popup).
Custom Links predate Lightning Web Components and Quick Actions; they were the original Salesforce mechanism for adding navigation outside the standard page chrome. In Lightning Experience they still work but are usually superseded by Custom Buttons, Quick Actions, or LWC components that produce better-integrated experiences. Most established orgs hold Custom Links from years of accumulated customization; the modern admin pattern is to maintain existing Custom Links and build new navigation through Lightning-native constructs.
Why Custom Links persist as the legacy navigation pattern under modern Lightning
Where Custom Links live in setup
Object Manager, pick the object, Buttons, Links, and Actions. The page lists every Custom Link, Custom Button, and Quick Action on the object. Custom Links are the URL-based subset; Custom Buttons are the action subset (which can also be URL-based or JavaScript-based in Classic); Quick Actions are the modern Lightning replacement for both in most use cases. Click into a Custom Link to edit the URL pattern, the display type, and the merge field references.
Merge fields and the dynamic URL pattern
Custom Link URLs support merge fields that inject record data at click time. A Custom Link to a Google search for the current Account might be https://www.google.com/search?q={!Account.Name}. The merge field {!Account.Name} resolves to the actual Account Name when the user clicks. Merge fields work for any field on the current record, plus standard system fields ($User.Id, $Organization.Id). The pattern is powerful for context-rich navigation; users land on the external site pre-scoped to the current record.
Display types and the placement question
Custom Links can display as a Link (text in a related section on the record page), a Button (visible action on the record header), a sidebar component (on home pages), or via the Page Layout's Custom Links section (the most common Classic placement). Lightning Record Pages render Custom Links in a related section by default; admins can add them to the Highlights Panel or other regions through Lightning App Builder. The display type drives where users actually see the link.
Custom Links vs Custom Buttons vs Quick Actions
Three navigation constructs with overlapping use cases. Custom Links: URL-based, display as text links, support merge fields. Custom Buttons: URL-based or JavaScript-based in Classic, display as buttons. Quick Actions: Lightning-native, support record-create or record-update inline without navigation, display as buttons in the action bar. Modern Lightning admin pattern: use Quick Actions for inline record actions, use Custom Buttons (URL-based) for navigation that produces a button experience, use Custom Links for navigation that produces a text-link experience or that the org has been using since before Quick Actions existed.
JavaScript Custom Buttons and the Lightning incompatibility
Classic Custom Buttons could execute JavaScript directly in the URL (javascript: protocol). Lightning does not support JavaScript Buttons; they fail silently or produce errors. Orgs migrating from Classic to Lightning typically have JavaScript Buttons that need replacement with Lightning Components, Quick Actions, or Custom Buttons that call a Visualforce page or a Lightning Component. This is a significant migration cost for orgs heavy on Classic JavaScript Buttons; budget for the rewrite as part of any Lightning Experience rollout.
Behavior options: same window, new window, popup
Custom Links support three click behaviors: open in same window (replaces the current Salesforce page), open in new browser window (preserves the Salesforce session), open in a popup window (specific dimensions, no browser chrome). Most Custom Links use open-in-new-window because users want to keep their Salesforce context. Open in same window is appropriate for navigation that replaces the current view entirely; popup is rarely the right choice in modern UX. The behavior is per-Link configuration.
Maintenance, audit, and the modernization path
Custom Links accumulate. A typical Lightning org has Custom Links from the Classic era that work but feel dated. The audit discipline: list every Custom Link, identify which still serve a workflow, identify which are obsolete (the external site changed, the workflow retired), modernize where it makes sense (replace with Quick Action, LWC, or Custom Button), document the rest. Most orgs do this lazily; the visible result is record pages with sections of stale links nobody clicks.
How to build or modernize Custom Links
The pattern: for new navigation in 2026, default to Quick Actions or Custom Buttons. Use Custom Links when the org culture or existing infrastructure makes them the right choice. For legacy Custom Links, maintain working ones and replace JavaScript-based ones during Lightning migration.
- Decide whether Custom Link is the right construct
For inline record actions, Quick Action. For Lightning-native button experiences, Custom Button. For text-link navigation or org-cultural consistency with existing Custom Links, Custom Link.
- Open Buttons, Links, and Actions in Object Manager
Object Manager, pick the object, Buttons, Links, and Actions, New Custom Link.
- Write the URL with merge fields for dynamic context
Use the merge field picker to insert record data. Test the URL with a real record to confirm the merge fields resolve correctly.
- Pick the display type and behavior
Link, Button, or sidebar. Same window, new window, or popup. Most Custom Links default to Link + new window.
- Add the Custom Link to the page layout or Lightning Record Page
The Link exists but is invisible until placed. Add via Page Layout (Classic-style placement) or Lightning App Builder (Lightning placement).
- Test as an end user
Click the link on a real record. Confirm the URL resolves correctly, the destination works, the behavior matches expectation.
- Audit existing Custom Links during Lightning migration
For each Custom Link, decide: keep, modernize to Quick Action, retire. Document the decision and execute through your normal change pipeline.
Dynamic URL that injects record data via {!Object.Field} merge syntax.
Link, Button, or sidebar component. Drives visual placement.
Open in same window, new window, or popup.
Custom Link is invisible until added to a page layout or Lightning Record Page.
Whether the Custom Link should be replaced by Quick Action, LWC, or Custom Button.
- JavaScript Custom Buttons do not work in Lightning. Migration requires rewriting as LWC or Quick Action.
- Custom Links are invisible until added to a layout. Building the Link without placing it is a common omission.
- Merge fields that reference non-existent fields produce empty URL segments. Test against a real record before declaring done.
- Open in popup window is rarely the right modern UX choice. New window preserves the Salesforce session; popup feels dated.
- Stale Custom Links accumulate. The cleanup is rarely scheduled and the result is record pages with sections of links nobody clicks.
Trust & references
Cross-checked against the following references.
- Custom Links referenceSalesforce
- Buttons and Links overviewSalesforce
Straight from the source - Salesforce's reference material on Custom Links.
- Define Custom LinksSalesforce Help
- Custom Buttons and LinksSalesforce Help
- Quick Actions OverviewSalesforce 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 Custom Links used for?
Q2. Do JavaScript Custom Buttons work in Lightning Experience?
Q3. What's the modern replacement for JavaScript Custom Buttons?
Discussion
Loading discussion…