👀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.
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.
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
Open Screens → + New Screen.
Choose the Notion database to list.
Under Data screens, select List (View Items).
Click Done.
Map Title (required) and other Data fields.
On Behaviour, point Go to Screen at a Details screen.
On Appearance, pick List / Grid / Calendar / Board.
Publish and test on phone and desktop.
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
Data
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
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
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
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
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
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
Open Item On Click / Go to Screen
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.
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
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
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
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
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
View Type
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
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
Troubleshooting
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.
Last updated