SfSkills Domains Docs GitHub

Home / admin / list-views-and-compact-layouts

list-views-and-compact-layouts

Use when designing or reviewing list views, compact layouts, highlights panels, and search-result presentation so users can scan, find, and act on records quickly across desktop and mobile.

Open the skill folder on GitHub

Use this skill when users are losing time before they even open a record. List views, compact layouts, and search layouts all shape how quickly a user can browse, triage, and select the next record, but they solve different problems and should not be treated as interchangeable UI settings.

Before Starting

Gather this context before working on anything in this domain:

Questions to Ask Before Configuring

Ask these before opening Setup. Each one maps to a behaviour in references/gotchas.md that turns a reasonable-looking configuration into a broken one.

AskWhy it mattersWhat a good answer adds
"Who is the audience for this view, and did anyone decide it should be public?"A list view with no sharedTo element is public; the broadest audience is encoded as an absence, so nobody reviews itAn explicit sharing target (group, role, roleAndSubordinates, queue) or a written decision that public is intended
"Is this view meant to follow a queue?"filterScope = Queue plus a queue developer name is a different object from a filtered view, and every queue already auto-creates oneEither a queue name that must deploy first, or a decision to use the auto-created view instead of authoring a rival
"What are the exact column tokens on this object?"Standard-field columns are legacy tokens, not API names (PC_Email for PersonEmail), so hand-written columns render blankA retrieved list view to harvest tokens from, instead of guesses
"Which record types exist, and which compact layout does each one get?"compactLayoutAssignment sits on the object and on every record type; an unassigned layout renders nowhereAn assignment map: object default plus one line per record type
"Does any field we want in the highlights panel hold free text?"Text area, long text area, rich text area, and multi-select picklist cannot go in a compact layout — the deploy failsA short formula or text field to carry the summary, with the long field left on the record page
"Are these views migrating between orgs, and by what mechanism?"ListView and SearchLayouts reject the package.xml wildcard and ListView members need Object.ViewUniqueNameA manifest that retrieves the encompassing object rather than a wildcard that silently returns nothing
"Which manifest member form does each type need — bare or object-qualified?"Everything nested in an object takes <Object>.<Name>; CompactLayout is the one the guide never spells out, so the bare fullName looks right and fails the manifest deployA manifest written as Case.Case_Intake, and a plan to validate it with --manifest, not only --source-dir
"Who owns list-view creation on this object after go-live?"Sprawl is a permission decision: "Manage Public List Views" also lets a user edit or delete every public view in the orgA named owner and the narrower "Manage Shared List Views" permission where it fits

What a proper configuration adds over just doing it: views that survive a sandbox refresh because they are in source, a highlights panel that actually deploys and renders on every record type, and a public-view inventory small enough that the next admin can tell which queue is authoritative.

Core Concepts

List views, compact layouts, and search layouts each own a different stage of user navigation. List views are for browsing and filtering record sets. Compact layouts are for fast record recognition in highlights and mobile contexts. Search layouts shape how search results present records. When teams blur those responsibilities, they keep editing the wrong metadata and users still cannot find what they need.

List Views Are Working Surfaces

List views help users answer "what should I work on next?" They need a clear audience, strong filters, and only the columns required for triage. The best list view is not the one with the most data. It is the one that lets the intended persona decide quickly whether to open the record or move on.

Compact Layouts Are Scan Layers

Compact layouts are not mini page layouts. They should expose the few fields that identify the record and its current state, especially in highlights panels and mobile-first experiences. If a compact layout tries to summarize everything, it stops helping anyone.

Search Layouts And List Views Are Separate Concerns

Search results answer "which record is this?" while list views answer "which set of records should I process?" Changing search result columns does not fix a weak list view, and adding more list view columns does not improve global search behavior.

None Of These Features Are Security Controls

Fields appearing or not appearing in a compact layout or list view do not change object, field, or record access. Good UX configuration depends on security, but it does not replace it.

All Three Live Inside The Object

None of these is a standalone folder in Metadata API terms. Everything below is nested in the object's own definition, which is why "retrieve the object" is usually the right move and a wildcard usually is not.

Metadata typepackage.xml <name><members>Wildcard *Key elements
ListViewListViewObject.ViewUniqueNameNofilterScope (required), columns, filters, booleanFilter, queue, sharedTo, label, language, division
CompactLayoutCompactLayoutObject.LayoutNameYesfields (ordered by priority), label
SearchLayoutsvia CustomObjectobject nameNolistViewButtons, searchResultsAdditionalFields, lookupDialogsAdditionalFields, customTabListAdditionalFields, searchFilterFields, massQuickActions, excludedStandardButtons
ProfileSearchLayoutsvia CustomObjectobject name—profileName, fields

Enumerated members for the first two are object-qualified: Case.My_Open_Cases, Case.Case_Intake. The guide documents that form for ListView and not for CompactLayout — the compact-layout half is verified by a failed --manifest dry-run rather than by documentation (references/metadata-examples.md § Manifest member form, and gotcha 10 below).

filterScope is the one required element on a list view. Its enumeration is Everything, Mine, MineAndMyGroups, AssignedToMe (ServiceAppointment only), Queue, Delegated, MyTerritory, MyTeamTerritory, Team, SalesTeam, and ScopingRule — and a ScopingRule view only applies its rule when the user selects Filter by scope in Lightning Experience (admin/scoping-rules). Deployable XML for all four types is in references/metadata-examples.md.

Assignment Is Separate From Definition

A compact layout is inert until something names it. compactLayoutAssignment appears twice: once on the CustomObject as the object default, and once inside each RecordType. A record type with no assignment does not inherit visibly in the metadata, so the assignment map has to be written down per record type rather than inferred from the layout list.

Common Patterns

Persona-Specific Working Lists

When to use: Sales, service, or operations teams repeatedly work a filtered subset of records.

How it works: Create a small set of role-oriented list views with meaningful ownership, narrow filters, and only the columns needed for triage. Reserve broad "all records" views for admins or specialized troubleshooting.

Why not the alternative: A long list of near-duplicate public list views creates clutter and weakens trust in every queue.

Five-Second Compact Layout Design

When to use: Users need to recognize status, priority, owner, and key identifiers before opening the record.

How it works: Put the fields that answer "what is this and what state is it in?" into the compact layout. Keep the set short and stable. Use the full page or record page for deep context.

Why not the alternative: Stuffing the highlights area with every useful field makes the scan layer unreadable, especially on mobile.

Search Versus Browse Deliberately Split

When to use: Teams are trying to solve both search discovery and queue processing on the same object.

How it works: Tune search-result presentation for recognition, and tune list views for workflow. Review both with the same persona, but do not assume one setting replaces the other.

Decision Guidance

SituationRecommended ApproachReason
Users need a filtered queue or worklistList ViewThe primary need is browsing a record set and taking action on the next item
Users need to identify a record quickly after opening or in mobileCompact LayoutThe need is high-signal recognition, not detailed editing
Users are finding the wrong records from searchSearch Layout or search-result configurationSearch result presentation is a separate surface from list views
Users need to edit or rearrange many fields on the record itselfPage Layout or Lightning Record PageThat is full-record design, not browse-and-scan configuration
The team wants to hide data from unauthorized usersFix security model insteadThese features do not enforce access controls
  1. Inventory what exists, from two directions. Retrieve the encompassing object (sf project retrieve start --metadata CustomObject:<Object>) to get every list view, compact layout, and the searchLayouts block in one pull, then query SELECT DeveloperName, Name, SobjectType, IsSoqlCompatible FROM ListView WHERE SobjectType = '<Object>' in the org. The query returns views the retrieve cannot — private and auto-created queue views — and the difference between the two lists is the real inventory.
  2. Fill in templates/list-views-and-compact-layouts-template.md. One row per existing view with audience, filters, columns, share scope, and a keep / merge / retire call; then the compact-layout field set and the assignment per record type. This is the artefact the rest of the workflow edits.
  3. Harvest tokens before writing any XML. Copy standard-field columns and searchResultsAdditionalFields values from the retrieved files. Custom fields use their API name; standard fields do not, and guessing produces a blank column or a failed deploy.
  4. Author the metadata from references/metadata-examples.md. Take the queue-scoped view, the booleanFilter + sharedTo view, the compact layout, and the object-level compactLayoutAssignment / recordTypes / searchLayouts block as the starting shapes, and follow the "How to read it" notes rather than editing them by analogy.
  5. Run the checker from the project root — not from inside force-app/ — so the manifest is in scope alongside the source: python3 skills/admin/list-views-and-compact-layouts/scripts/check_list_views_and_compact_layouts.py --manifest-dir . (add --strict to fail on WARN and INFO as well as ERROR). It flags unfiltered public views, dangling booleanFilter indices, filterScope / queue mismatches, compact layouts holding an unsupported field type, compact layouts that no compactLayoutAssignment names, and the package.xml member form — CL-MEM-01 (a bare CompactLayout / ListView member whose file is in the tree) and CL-MEM-02 (a compact layout no manifest declares).
  6. Dry-run both ways — --source-dir and --manifest — then confirm on a phone-width viewport. Open one record of each record type and one list view per persona; re-run the ListView query to confirm DeveloperName and IsSoqlCompatible match what was authored. Re-check references/gotchas.md if the retrieved file differs from what you sent — the search layout's Name field is added back by design.
  7. Record the governance decision. Who may create public views on this object, which auto-created queue views are authoritative, and when the inventory is reviewed again.

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Compact layouts do not replace page layouts - they support recognition and highlights, not full editing or detailed field placement.
  2. Search layout fixes do not change list views - teams often edit the wrong metadata because both features display columns.
  3. List-view sprawl is a governance problem, not just a UX problem - once everyone can create broad public views freely, the object becomes harder to navigate and harder to support.
  4. Field visibility in the UI is still bounded by security - if a user cannot access a field, layout design alone will not make it usable.
  5. "Manage Public List Views" is no longer the only permission for sharing a view - since Summer '26, grant "Manage Shared List Views" so a user can share their own list views with the roles, groups, and territories they belong to; "Manage Public List Views" still works, but it also lets them edit or delete every public list view in the org.
  6. A missing sharedTo element means public, not unshared - the guide states SharedTo is present for shared and private views and absent for public ones, so the widest audience is the one with no markup to review.
  7. "Visible only to me" views are outside Metadata API entirely - they never appear in a retrieve, so a clean org diff is not evidence that users kept their views.
  8. Compact layouts reject four field types at deploy - text area, long text area, rich text area, and multi-select picklist, which is exactly the shortlist an admin reaches for when asked to show "what this record is about".
  9. ListView and SearchLayouts reject the package.xml wildcard while CompactLayout accepts it - the same manifest can therefore ship half the design.
  10. A bare CompactLayout member in package.xml fails the deploy, and --source-dir never tells you - the member has to be Case.Case_Intake, not the layout's own fullName; --source-dir derives the member from the file so it always passes, while --manifest fails with "An object 'Case_Intake' of type CompactLayout was named in package.xml, but was not found in zipped directory".

Deeper treatment, with what happens / when it occurs / how to avoid, in references/gotchas.md.

Output Artifacts

ArtifactDescription
Browse-and-scan UX recommendationGuidance on which surfaces should use list views, compact layouts, or search-result tuning
Configuration review findingsIssues such as over-wide columns, weak filters, and missing high-signal highlight fields
Object worksheetPersona-specific inventory of list views, compact layouts, and search-result intent
objects/<Object>/listViews/*.listView-meta.xmlDeployable list views with filterScope, filters, booleanFilter, and an explicit sharedTo
objects/<Object>/compactLayouts/*.compactLayout-meta.xml plus assignmentsCompact layouts and the compactLayoutAssignment lines that make them render
Checker outputERROR / WARN / INFO lines from scripts/check_list_views_and_compact_layouts.py on the source tree

Reference Files

FileRead it when
references/metadata-examples.mdWriting deployable ListView, CompactLayout, and searchLayouts XML, the package.xml for them, and the post-deploy ListView query
references/gotchas.mdA view or layout deployed cleanly and still behaves wrong, or a retrieve keeps producing a diff nobody wrote
references/examples.mdDesigning the working set for a persona before any XML exists — queue triage and a mobile compact layout, end to end
references/well-architected.mdJustifying the governance tradeoff between user freedom and view sprawl, and locating the official sources behind each claim
references/llm-anti-patterns.mdReviewing output an AI assistant produced in this domain, especially "edit the page layout to change the highlights panel"
templates/list-views-and-compact-layouts-template.mdRunning the inventory in workflow step 2

Package files