> For the complete documentation index, see [llms.txt](https://docs.notionapps.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.notionapps.com/screens-and-components/types-of-screens/list-view-items.md).

# List (View Items)

The **List (View Items)** screen shows many records from a Notion database in one place. It is the main browsing surface for apps: users scan rows, search or filter, and open a details screen when they need more.

{% hint style="info" %}
**Who this guide is for**\
Makers configuring a list of Notion records. This guide explains every List builder option across the **Content**, **Behaviour**, and **Appearance** tabs, including when each control appears.
{% endhint %}

## What the screen is for

### Use List (View Items) when

* Users need to browse many records from one database
* You want search, sorting, grouping, or end-user filters
* Row click should open a **Details** screen
* You may also want an **Add** path into a Create Form

### Do not use it when

* Users only submit new records with no browsing: use **Form (Add Item)**
* Users edit one existing record: use **Form (Update One Item)** or **List (Update Items)**
* Work is claim-and-complete workflow items: use **Work Queue**
* The page is static HTML: use **Content**

## What users see in the live app

* A list, grid, calendar, or board of records (View Type)
* Mapped Title / Description / Caption / Tag / Image fields (depending on layout)
* Optional search, scanner, and in-app filters
* Optional add button when Add New Item is enabled
* Row tap opens the configured Details screen when Open Item On Click is on

## Add List (View Items) in the builder

1. Open **Screens → + New Screen**.
2. Choose the Notion database to list.
3. Under **Data screens**, select **List (View Items)**.
4. Click **Done**.
5. Map Title (required) and other Data fields.
6. On **Behaviour**, point **Go to Screen** at a Details screen.
7. On **Appearance**, pick List / Grid / Calendar / Board.
8. Publish and test on phone and desktop.

![Builder configuration for this screen](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FGYiogZzVBwSDxHo6O0Oz%2Fdata-1786203139-0-00-builder-hero.jpg?alt=media)

![End-user preview of this screen](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FapC3Adktvi9vTtNxU8Rs%2Fdata-1786203139-1-09-preview-closeup.jpg?alt=media)

## Complete Builder Options Reference

List configuration uses three inspector tabs: **Content**, **Behaviour**, and **Appearance**. Per-field styling and validation are edited in the field inspector after you open a Details/Form field — not on these list tabs.

### Content tab

![Annotated builder screenshot: Content](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2F5agxtKxY98RGRFIvmRlU%2Fdata-1786203139-2-01-section-content.jpg?alt=media)

#### Data

![Annotated builder screenshot: Data](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2Fz3frwv7wwTL8uX33wG9Z%2Fdata-1786203139-3-02-section-data.jpg?alt=media)

**Title**

**What it does:**\
Sets the primary property shown as each row’s title. Required for a usable list.

**How to use it:**\
Pick the field users recognize first (name, request summary, ticket title). Avoid IDs unless users search by ID.

**Why / recommended default:**\
Title is the scan target. A common mistake is mapping a weak or empty property, which makes every row look identical.

**Description / Caption**

**What it does:**\
Optional secondary and tertiary text under the title. Hidden in compact List layouts and unavailable in Calendar mode.

**How to use it:**\
Use Description for status or owner; Caption for dates or short metadata. Keep both short for mobile.

**Why / recommended default:**\
Leave blank until the title alone is not enough. Overloading description text makes dense lists hard to scan.

**Color Tag**

**What it does:**\
Maps a select/status-style property to a colored tag on each row, with optional per-option colors.

**How to use it:**\
Point it at Status or Priority. Set colors that match your app theme.

**Why / recommended default:**\
Use for one high-signal status field. A common mistake is tagging a field with too many options, which becomes noisy.

**Image**

**What it does:**\
Shows an image property on each row (List/Grid styles vary).

**How to use it:**\
Map a file/image property. On Appearance, tune Image Style / Fill / Grid Image Style.

**Why / recommended default:**\
Only enable when images add recognition value. Empty image slots waste space.

**Date (Calendar only)**

**What it does:**\
When View Type is Calendar, Date replaces Description/Caption/Tag/Image and places items on the calendar.

**How to use it:**\
Map the date property that should position events. Pair with Title only.

**Why / recommended default:**\
Required for Calendar to be useful. Wrong date fields scatter items incorrectly.

#### Filtering

![Annotated builder screenshot: Filtering](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FBeek50o8z2ulhDIMufH1%2Fdata-1786203139-4-03-section-filtering.jpg?alt=media)

**Filter rows / + Add Filtering**

**What it does:**\
Maker-defined filters that permanently limit which rows appear on this screen (separate from Data Restriction and In-App Filtering).

**How to use it:**\
Add conditions that define this list’s job (for example Status is Open). Use AND/OR as needed.

**Why / recommended default:**\
Prefer a clear fixed filter over teaching users to filter everything manually. A common mistake is duplicating Data Restriction here.

#### Logged-in user property filters

![Annotated builder screenshot: Logged-in user property filters](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2Fcdy8HLbrAsCGR2HUI25x%2Fdata-1786203139-5-04-section-logged-in-user-property-filters.jpg?alt=media)

**Allow logged-in user property filters**

**What it does:**\
Lets filters compare list properties to the signed-in user’s Users-sheet properties (for example Owner equals Me).

**How to use it:**\
Enable when each user should see “my” rows. Requires a linked Users sheet and matching properties. May be plan-gated.

**Why / recommended default:**\
Excellent for private portals. Do not enable for public guest lists — guests have no user profile.

#### Grouping

![Annotated builder screenshot: Grouping](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FzFYHokSs3LhFzd0aubNK%2Fdata-1786203139-6-07-section-grouping.jpg?alt=media)

**Group By / Order / + Add Grouping**

**What it does:**\
Groups rows by a property (feature/beta may apply). Hidden for Calendar. Typically one group level.

**How to use it:**\
Group by Status or Category when users triage by buckets. Choose A→Z or Z→A order.

**Why / recommended default:**\
Skip grouping until the list is long enough that buckets help. Grouping empty or unique fields adds clutter.

#### Sorting

![Annotated builder screenshot: Sorting](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2Fzm2PdBmjMXRl1S3dPZUR%2Fdata-1786203139-7-05-section-sorting.jpg?alt=media)

**Sort By / Order / + Add Sorting**

**What it does:**\
Default sort for the list. Hidden for Calendar.

**How to use it:**\
Sort by newest date or priority. Add multiple levels only when needed.

**Why / recommended default:**\
Default to newest-first for operational lists. Unsorted lists feel unfinished.

#### In-App Filtering

![Annotated builder screenshot: In-App Filtering](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FsNL4Z2f4SahHM4DW3Nj0%2Fdata-1786203139-8-06-section-in-app-filtering.jpg?alt=media)

**Filter Name / Filter Columns / + Add Filter Property**

**What it does:**\
Defines filters end users can change while browsing (distinct from maker Filtering).

**How to use it:**\
Expose 1–3 useful columns (Status, Category, Owner). Name filters clearly.

**Why / recommended default:**\
Use for exploratory browsing. Do not expose every column — mobile filter UIs get heavy.

### Behaviour tab

![Annotated builder screenshot: Behaviour](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2F1yGEzLOub2hSvVPP5c2c%2Fdata-1786203139-9-08-section-behaviour.jpg?alt=media)

#### Open Item On Click / Go to Screen

{% hint style="info" %}
On **List (View Items)**, this control is labeled **Open Item On Click**. The annotated screenshot below is taken from the same Behaviour panel position on a List (Update Items) screen, where the twin control is **Go to Update Screen**.
{% endhint %}

![Annotated builder screenshot: Open Item On Click](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FM8VZoB7yl4FMw4ZQGvgy%2Fdata-1786203139-10-09-section-go-to-update-screen.jpg?alt=media)

**What it does:**\
When on, tapping a row opens the selected Details (or other) screen.

**How to use it:**\
Turn on for browse→details flows. Pick the Details screen for the same database.

**Why / recommended default:**\
On for almost every View List. Leaving it off makes the list feel dead.

#### Add New Item

![Annotated builder screenshot: Add New Item](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2Fm9tAxyHdchnSjE9oggF2%2Fdata-1786203139-11-11-section-add-new-item.jpg?alt=media)

**Add New Item / Go to Screen**

**What it does:**\
Shows an add affordance that opens a Create Form screen.

**How to use it:**\
Enable when users should create records from this list. Point to the matching Form (Add Item).

**Why / recommended default:**\
On for operational intake lists; off for read-only directories.

#### Allow Search

![Annotated builder screenshot: Allow Search](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2F9nrL5su3Z7yl7rhcAaV6%2Fdata-1786203139-12-12-section-allow-search.jpg?alt=media)

**Allow Search / Search Helper Text / Show Scanner / Scan Type**

**What it does:**\
Adds a search bar; optional barcode/QR scanner with type Barcode or QR Code.

**How to use it:**\
Enable search for large lists. Set helper text like “Search requests”. Enable scanner only when users scan codes into the same properties.

**Why / recommended default:**\
Search on for lists over \~20 rows. Scanner off unless the workflow is scan-driven.

#### Screen Visibility Logic

![Annotated builder screenshot: Screen Visibility Logic](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2F1yGEzLOub2hSvVPP5c2c%2Fdata-1786203139-9-08-section-behaviour.jpg?alt=media)

**Status / + Add Logic**

**What it does:**\
Controls who can open this screen (restricted vs unrestricted). Logic filters use the Users sheet on private apps.

**How to use it:**\
Keep unrestricted for shared team lists. Add user-sheet logic when only certain roles should see the screen.

**Why / recommended default:**\
Unrestricted unless the screen is role-sensitive. Do not confuse this with Filtering (which rows) or Data Restriction (which rows per user).

#### Data Restriction

![Annotated builder screenshot: Data Restriction](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2F1yGEzLOub2hSvVPP5c2c%2Fdata-1786203139-9-08-section-behaviour.jpg?alt=media)

**Enabled for this screen**

**What it does:**\
Applies database personalization so each user only sees rows they are allowed to access. Disabled on public apps or when the sheet is not personalized.

**How to use it:**\
Enable for customer/partner portals. Keep off for shared staff desks that should see all open work.

**Why / recommended default:**\
Match the database’s personalization strategy. Enabling without a Users mapping looks like an empty list bug.

### Appearance tab

![Annotated builder screenshot: Appearance](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FPTRpDqLKd391R0wInLWk%2Fdata-1786203139-13-14-section-appearance.jpg?alt=media)

#### View Type

![Annotated builder screenshot: View Type](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FV38ny00dPtSmKenoiHuC%2Fdata-1786203139-14-15-section-view-type.jpg?alt=media)

**View Type**

**What it does:**\
Chooses List, Grid, Calendar, or Board presentation.

**How to use it:**\
List for dense ops queues; Grid for image-heavy catalogs; Calendar for dated work; Board for status columns.

**Why / recommended default:**\
List is the safest default. Calendar requires a Date mapping; Board needs a useful status/select property.

#### Style controls (conditional)

**Grid Column Size / Grid Image Style**

**What it does:**\
Grid density and image crop style when View Type is Grid.

**How to use it:**\
Large for marketing-style cards; Small for denser catalogs.

**Why / recommended default:**\
Large when images matter; Small when titles matter more.

**Image Style / Image Fill**

**What it does:**\
Shape and fit for list/grid images (not Calendar).

**How to use it:**\
Match brand (square vs round). Use Fit for logos; Fill for photos.

**Why / recommended default:**\
Square + Fill is a solid default for photos.

**Default Mode / Allow Mode Change (Calendar)**

**What it does:**\
Calendar starts in Day/Week/Month/Agenda; optional user mode switching.

**How to use it:**\
Month for overview; Week for scheduling teams. Allow Mode Change when users need flexibility.

**Why / recommended default:**\
Month + Allow Mode Change on for most calendar lists.

**View Less Data / Wrap Text / Desktop split view**

**What it does:**\
Compact list density; wrap long text; show list+details side-by-side on wide desktops.

**How to use it:**\
View Less Data for long operational lists. Desktop split view when desktop users triage quickly.

**Why / recommended default:**\
View Less Data on for dense queues; Desktop split view on for staff desktop apps.

### Related setup outside the inspector

#### Edit Navigation

**What it does:**\
Controls nav label, icon, and whether the list appears in guest/signed-in navigation (and Public access on private apps via the screen accordion).

**How to use it:**\
Put primary lists in navigation. Keep secondary lists hidden and open them from buttons.

**Why / recommended default:**\
One primary list in nav beats five competing lists.

#### Field inspector on Details/Form

**What it does:**\
Per-field labels, required, validation, visibility, defaults — configured on Details/Form screens, not on List Data mapping.

**How to use it:**\
After list→details navigation works, polish field-level options on the Details/Form screens.

**Why / recommended default:**\
Do not expect list Data mapping to replace field inspector setup.

## Recommended default setup

| Setting            | Recommended value                                       |
| ------------------ | ------------------------------------------------------- |
| Title              | Primary human-readable property                         |
| Open Item On Click | On → Details screen                                     |
| Add New Item       | On only if users create from this list                  |
| Allow Search       | On for larger lists                                     |
| View Type          | List                                                    |
| Filtering          | Match the list’s job (e.g. open items only)             |
| Data Restriction   | On for personalized portals; off for shared staff desks |

## Testing checklist

* [ ] Title mapping is readable on mobile
* [ ] Row click opens the intended Details screen
* [ ] Add button opens the intended Create Form (if enabled)
* [ ] Maker Filtering shows the expected subset
* [ ] In-app filters work for end users
* [ ] Search finds known records
* [ ] Calendar/Board/Grid layouts render with required fields
* [ ] Data Restriction / visibility behave correctly per persona (`View as user`)

## Troubleshooting

| Symptom                | Likely cause                                   | What to check                       |
| ---------------------- | ---------------------------------------------- | ----------------------------------- |
| List is empty          | Filtering, Data Restriction, or empty DB       | Relax filters; test as another user |
| Row click does nothing | Open Item On Click off or missing Go to Screen | Behaviour tab                       |
| Calendar empty/wrong   | Date not mapped or wrong field                 | Content → Data → Date               |
| Search missing         | Allow Search off                               | Behaviour tab                       |
| Users see others’ rows | Data Restriction off                           | Behaviour → Data Restriction        |

## Best practices

* One list job per screen (Open requests, Closed archive) instead of one mega-list.
* Always pair View List with a Details destination.
* Keep in-app filters few and meaningful.
* Prefer maker Filtering for permanent scope; In-App Filtering for exploration.