SfSkills Domains Docs GitHub

Home / admin / related-list-configuration

related-list-configuration

Configure related lists on Salesforce records — column choice on Page Layouts (max 10 fields per related list), sort field selection, the Spring '24 Enhanced Related Lists component (which adds filtering, mass actions, and 10-row inline display), the choice between Related Lists / Related Lists - Single / Related List - Quick Links in Lightning App Builder, per-record-type related-list assignments, and the View All / pagination UX.

Open the skill folder on GitHub

Related List Configuration

Activate when an admin is configuring, auditing, or troubleshooting a related list on a Salesforce record — what columns appear, in what order, with what sort, and which Lightning App Builder component is used to host it. This is a Page Layout + Lightning Page Builder concern; the related list rendering is driven by the page layout that the user's Profile + Record Type combination resolves to, even on a Lightning record page that uses the new related-list components. Getting this wrong silently changes which fields users see and which they don't.

Before Starting

Gather this context before changing any related-list setting:

Core Concepts

Page Layout owns the related-list contract

A "related list" on any page-layout-driven surface is defined inside the Page Layout XML at <relatedLists>. The entry carries relatedList, an optional sortField / sortOrder, a list of fields (up to 10 for classic), and a list of customButtons exposed at the top of the list. The Lightning record page does not store the column definitions — it stores only the choice of component (classic Related Lists vs. Related Lists - Single vs. Enhanced Related Lists) and which related list (by relationship name) that component should render.

The implication: editing a related list's columns is a Page Layout edit, not a Lightning App Builder edit, even when the resulting record page is 100% Lightning App Builder. Forgetting this routes admins to the wrong tool.

Sort field + sort direction

Each related list has one sort field and one direction. Sort defaults to the parent-relationship-defined order (typically CreatedDate DESC) when not specified. Sort field must be a sortable field type — long text areas, encrypted text, formula fields that reference cross-object lookups, and base64 fields cannot sort. Picking an unsortable field silently falls back to default sort with no error.

The sort field shown when the user clicks View All can differ from the inline sort if the user manually re-sorts the View All grid, but the configured default sort always re-applies on first render.

The Enhanced Related Lists component on a Lightning record page adds:

The cost: Enhanced Related Lists components are heavier on initial render than Related List - Single. On record pages with more than ~6 enhanced related lists visible above the fold, defer some to a tab to avoid First-Paint regressions.

When an object has multiple record types, each record type can route to a different Page Layout via the Page Layout Assignment matrix (Setup → Object Manager → Object → Page Layouts → Page Layout Assignment). Because the related-list contract lives on the Page Layout, this means different record types see different related lists, with different columns and sort orders. This is a feature when intentional (e.g., a Service Request record type doesn't need the Opportunities related list) and a bug when accidental (admins forget to update layout B after editing layout A).

Search Filter Fields (lookup dialog parity)

The Search Filter Fields on the parent object's Search Layout control which columns appear in the lookup dialog when a user is selecting a record. These are configured separately from the related list itself, in the Search Layouts area. A user can be unable to find a record in the lookup dialog because the field they're searching by isn't in the Search Filter Fields list — even when the related list happily displays it.

Common Patterns

Pattern 1: Classic Related Lists block on a small Lightning record page

When to use: The record page has 4–8 related lists, all relevant to most users, and the org has not yet adopted the Enhanced Related Lists component.

How it works:

  1. Edit the Page Layout. Add the related lists in priority order (top = most important). For each, set the columns (≤10), sort field, and sort direction.
  2. On the Lightning record page in Lightning App Builder, add the Related Lists component (singular, all-in-one) below the Activity timeline or on a dedicated tab.
  3. The component renders all related lists from the page layout in the order configured.

Why not the alternative: Using Related List - Single × 8 instead requires 8 separate component placements and 8 separate filter/sort decisions, with no consolidated quick-links bar. The all-in-one block is the right default until a related list needs its own dedicated component (e.g., it lives on a different tab from the others).

When to use: Users frequently scroll a long related list looking for the subset that matters (e.g., open vs. closed Cases under an Account).

How it works:

  1. On the Lightning record page, replace Related Lists (or Related List - Single for that one list) with the Enhanced Related Lists component.
  2. Choose the relationship to display. The component reads the same column / sort definition from the underlying Page Layout — there is no separate column picker in App Builder.
  3. Enable the filter and mass-action options the users need. Tell users to use the inline filter chip to filter by Status / Stage / Owner.

Why not the alternative: Building a custom list view tab on the record page (Related List - Single + custom List View component) duplicates configuration and breaks when the user's Page Layout assignment changes. Enhanced Related Lists tracks the Page Layout source automatically.

When to use: Two record types on the same object need genuinely different related-list sets — e.g., the B2C record type doesn't expose the Opportunities related list, while B2B does.

How it works:

  1. Maintain one Page Layout per record type (do not share a layout across divergent record types).
  2. Configure related lists per layout in the intentional shape.
  3. Confirm the Page Layout Assignment matrix routes each (Profile × Record Type) combination correctly — this is the silent failure point.
  4. Document the divergence in the layout description so the next admin doesn't accidentally re-sync the layouts.

Why not the alternative: Sharing one layout across record types and using component-level visibility filters in App Builder to hide related lists works for the visible row data but does not hide the related-list block on the underlying Page Layout — admins editing the layout later may add columns assuming all record types see them.

Decision Guidance

SituationRecommended ApproachReason
Standard record page with several related lists, mostly readClassic Related Lists component, one blockOne place to edit, lowest render cost
One related list users need to filter / mass-act onEnhanced Related Lists for that list onlyFilter + mass actions require Enhanced; keep others classic to limit page weight
Related list with > 10 columns requested inlinePush secondary columns behind View All, keep 10 max inlineClassic related lists silently drop column 11+; inline width also breaks UX
Two record types need different related-list setsSeparate Page Layouts per record type, distinct Page Layout AssignmentComponent visibility filters on App Builder don't hide the underlying related-list block from layout-editing admins
Related list needs to live on a dedicated tab in App BuilderRelated List - Single on the tabSingle component lets you title and place independently; the all-in-one Related Lists block can't be split
Org wants users to discover related lists fast (top of page)Related Lists - Quick Links near the top + full related lists on a tabQuick Links is anchor-only; pairs with full lists for the click-through
Sort field is a formula referencing another objectPick a directly stored field on the child insteadCross-object formulas are not sortable; configuration silently falls back to default sort
Mobile users complain related list looks empty on phoneReorder columns: most important first, max 4 visible inline on mobileMobile applies the same layout but renders fewer columns above the fold

Step-by-step instructions for an AI agent or practitioner working on a related-list configuration request:

  1. Identify the Page Layout that the affected user's (Profile, Record Type) combination resolves to — not the Lightning record page. Confirm by reading the Page Layout Assignment matrix in Setup → Object Manager → <Object> → Page Layouts.
  2. Inventory the related list in question on that Page Layout: relationship name, current columns (order + count), sort field, sort direction, custom buttons. Note any field hidden by FLS for the affected user — those show as blank cells.
  3. Decide the Lightning component for hosting: classic Related Lists (all-in-one), Related List - Single, Related Lists - Quick Links, or Enhanced Related Lists. Apply the decision table above.
  4. Apply the column / sort / filter changes on the Page Layout (max 10 fields for classic; choose a sortable field). If using Enhanced Related Lists, confirm filter and mass-action behavior in the App Builder component properties.
  5. If different record types need different shapes, mirror the changes onto the divergent Page Layout(s) or document the intentional divergence in the layout description.
  6. Validate by impersonating a user from each affected (Profile × Record Type) combination — confirm column visibility, sort default, View All behavior, and mobile parity.
  7. Capture the configuration in the related-list-configuration template (see templates/) so the next admin reading the change knows the intent.

Review Checklist

Run through these before marking related-list configuration work complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Classic related list silently drops the 11th column — adding a 12th field doesn't error; it doesn't appear. Users report "field is missing" and admins waste hours debugging FLS before realizing the cap.
  2. Cross-object formula fields can't be the sort field — the picker accepts them, but at render the sort falls back to default with no warning. The same is true of base64 and long-text-area fields.
  3. Field hidden by FLS appears as a blank cell — not "no access." This is indistinguishable from a layout bug at a glance and is the #1 source of "column is broken" tickets.
  4. Lightning App Builder visibility filter hides the component, not the Page Layout block — admins assume the related list is "removed" but the next admin opening the Page Layout sees it and may edit it under that assumption.
  5. Enhanced Related Lists initial render cost is non-trivial — placing 6+ Enhanced components above the fold has been measured to add hundreds of milliseconds to First Paint on slow networks. Defer to a tab where possible.
  6. Per-record-type related lists diverge silently after a Page Layout clone — admins clone Layout A → Layout B for a new record type, then later add a related list to A only. Layout B drifts. There is no built-in drift detector; only manual review catches it.
  7. Salesforce Mobile App ignores the inline-column count beyond ~4 — the column order on the Page Layout dictates what mobile users see. Putting an "internal" field in position 1 means the customer-facing fields fall off the mobile view.

Output Artifacts

ArtifactDescription
Related-list configuration tableOne row per (Page Layout × related list) with: columns (ordered), sort field, sort direction, Enhanced/classic component choice, per-record-type divergence note
Component placement planLightning record page → which Lightning component (Related Lists / Related List - Single / Enhanced Related Lists / Related Lists - Quick Links) hosts each related list, with rationale
Page Layout Assignment confirmationProfile × Record Type → Page Layout matrix snapshot for the affected layouts
FLS impact noteFields on the configured related lists that are hidden by FLS for any affected Profile, with intent (blank cell is intentional vs. needs FLS grant)
Mobile parity noteConfirmation that the first 4 columns of each related list are the ones mobile users need most

Package files