ListView Metadata Type Reference

The ListView metadata type defines the columns, record ownership scope (filterScope), filter criteria (filters and booleanFilter), and audience sharing (sharedTo) for an object’s list view in Lightning Experience and Salesforce Mobile. Introduced in API version 14.0, version-controlling ListView files ensures support teams, sales reps, and queue managers get standardized operational views immediately upon deployment.

In Salesforce DX projects, list views live inside their parent object folder at force-app/main/default/objects/<ObjectName>/listViews/<ListViewName>.listView-meta.xml.

Key Metadata Fields#

Production-Grade XML Example#

Below is a Queue-backed Case list view (force-app/main/default/objects/Case/listViews/Tier_3_Escalation_Queue_View.listView-meta.xml) shared with a Public Group and Role:

<?xml version="1.0" encoding="UTF-8"?>
<ListView xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Tier_3_Escalation_Queue_View</fullName>
    <booleanFilter>1 AND (2 OR 3)</booleanFilter>
    <columns>CASES.CASE_NUMBER</columns>
    <columns>ACCOUNT.NAME</columns>
    <columns>CASES.SUBJECT</columns>
    <columns>CASES.STATUS</columns>
    <columns>CASES.PRIORITY</columns>
    <columns>CASES.CREATED_DATE</columns>
    <columns>CORE.USERS.ALIAS</columns>
    <filterScope>Queue</filterScope>
    <filters>
        <field>CASES.CLOSED</field>
        <operation>equals</operation>
        <value>0</value>
    </filters>
    <filters>
        <field>CASES.PRIORITY</field>
        <operation>equals</operation>
        <value>High,Critical</value>
    </filters>
    <filters>
        <field>CASES.ESCALATED</field>
        <operation>equals</operation>
        <value>1</value>
    </filters>
    <label>Tier 3 Escalation Queue</label>
    <queue>Tier_3_Engineering_Queue</queue>
    <sharedTo>
        <group>Tier_3_Support_Engineers</group>
        <roleAndSubordinatesInternal>VP_Customer_Support</roleAndSubordinatesInternal>
    </sharedTo>
</ListView>

Querying ListView with SOQL#

You can query ListView records directly in standard SOQL:

-- Find all ListViews on Case and check whether they are SOQL-compatible
SELECT Id, Name, DeveloperName, SobjectType, IsSoqlCompatible, LastViewedDate
FROM ListView
WHERE SobjectType = 'Case'
ORDER BY Name ASC

Frequently asked questions

Where are ListView files stored in SFDX source format?

In SFDX source format, ListView files are decomposed inside the parent object's directory at force-app/main/default/objects/ObjectName/listViews/ListViewName.listView-meta.xml.

What are the valid values for filterScope in a ListView?

Common filterScope values are Everything (all accessible records), Mine (records owned by the running user), Queue (records owned by a specific Queue specified in the queue field), Delegated, and MyTerritory.

How do I restrict who can see a deployed ListView?

Include a sharedTo block in the ListView XML referencing specific groups, roles, rolesAndSubordinates, or allInternalUsers. Avoid deploying private single-user list views via CI/CD.

What is the system field nomenclature used inside ListView columns and filters?

ListView metadata uses legacy uppercase database column names for standard system fields, such as ACCOUNT.NAME, CORE.USERS.ALIAS, CREATED_DATE, LAST_UPDATE, and RECORDTYPE.

Can I query existing ListViews using standard SOQL?

Yes. The ListView object is queryable in standard SOQL and returns Id, Name, DeveloperName, SobjectType, IsSoqlCompatible, and LastViewedDate.