List pages (by type)

In this how-to, you'll learn the 3 main ways to list pages in React Bricks.

Depending on where you are working, you can fetch pages:

• inside a brick, using the List component
• inside the React context, using the usePagesPublic hook
• outside the React context, using the fetchPages function

All 3 approaches can filter pages by page type.

They can also:

• filter by custom fields
• sort results
• paginate results

When to use each approach

Use the List component when:

• you are inside a brick
• you want a simple declarative way to render a list of pages

Use usePagesPublic when:

• you are inside React
• you want to fetch pages in a component or hook

Use fetchPages when:

• you are outside the React context
• you need data in places like generateStaticParams
• you want to fetch pages in server-side utilities or other plain functions

1. Inside a brick: use <List>

Docs reference: Render a list of pages with List

The List component is the easiest way to render a list of pages of a certain page type inside a brick.

For example:

import { List } from 'react-bricks/frontend'
 
export default function ProductList() {
  return (
    <List
      of="product"
      where={{
        language: 'en',
        filterBy: {
          category: 'shoes',
          featured: 'true',
        },
      }}
      sort="-publishedAt"
      page={1}
      pageSize={12}
    >
      {({ items, pagination }) => (
        <div>
          {items.map((product) => (
            <div key={product.id}>{product.name}</div>
          ))}
        </div>
      )}
    </List>
  )
}

Here:

• of="product" filters by page type
• filterBy filters by page-level custom fields
• sort="-publishedAt" sorts by publish date descending
• page and pageSize enable pagination

The where object can also filter by tag and language.

2. Inside React: use usePagesPublic

Docs reference: usePagesPublic

When you are inside the React context and want to fetch pages programmatically, use usePagesPublic.

Example:

import { usePagesPublic } from 'react-bricks/frontend'
 
export default function ProductGrid() {
  const { data, error, isFetching } = usePagesPublic({
    type: 'product',
    filterBy: {
      category: 'shoes',
      featured: 'true',
    },
    sort: '-publishedAt',
    usePagination: true,
    page: 1,
    pageSize: 12,
  })
 
  if (isFetching) return <p>Loading...</p>
  if (error || !data) return <p>Unable to load products.</p>
 
  const items = 'items' in data ? data.items : data
 
  return (
    <div>
      {items.map((product) => (
        <div key={product.id}>{product.name}</div>
      ))}
    </div>
  )
}

The configuration object supports:

• type for a single page type
• types for multiple page types
• filterBy for custom fields
• sort for sorting
• usePagination, page, and pageSize for pagination

According to the docs, sort currently supports:

• createdAt
• -createdAt
• publishedAt
• -publishedAt

3. Outside React: use fetchPages

Docs reference: fetchPages

When you need to fetch pages outside React, use fetchPages.

This is useful in places like Next.js generateStaticParams.

Example:

import { fetchPages } from 'react-bricks/frontend'
 
export async function generateStaticParams() {
  const products = await fetchPages(process.env.API_KEY!, {
    type: 'product',
    filterBy: {
      category: 'shoes',
      featured: 'true',
    },
    sort: '-publishedAt',
  })
 
  const items = Array.isArray(products) ? products : products.items
 
  return items
    .map((product) => ({
      slug: product.slug,
    }))
    .flat()
}

Like usePagesPublic, fetchPages supports:

• type or types
• tag
• language
• filterBy
• sort
• pagination options

So the main difference is not the filtering API, but where you are allowed to use it.

Filter by custom fields

Both usePagesPublic and fetchPages document filterBy as an object where:

• each key is a custom field name
• each value is the expected value for that field
• the filters are combined with logical AND

The docs also mention that values should currently be simple values such as strings or arrays of strings, not complex objects.

The List component exposes the same filtering concept through where.filterBy.

So if your page type has custom fields like:

• category
• brand
• featured

you can filter pages using those field names directly.

Choose the right tool

All 3 approaches can list pages by type, filter by custom fields, and sort results.

The main choice is about context:

• use <List> inside bricks
• use usePagesPublic inside React components
• use fetchPages outside React, for example in generateStaticParams