filter and filterParams

The filter and filterParams properties allow you to customize and limit the documents shown in a list item using GROQ queries. Together, they enable you to build scoped, conditional, and role-based views of your datasets.

filter

• Type: string | ((params: CallbackParams & { childOptions: ChildResolverOptions }) => string)
• Optional: Yes

A GROQ filter string to limit which documents are shown in the list. You can also pass a function that returns a filter string based on the current user.

filterParams

• Type: Record<string, unknown> | ((params: CallbackParams & { childOptions: ChildResolverOptions }) => Record<string, unknown>)
• Optional: Yes

Parameters to be used within the filter GROQ string.

Basic Filtering

You can use filter alongside schemaType to show a subset of documents.

JSON

{
  title: 'Active Authors',
  schemaType: 'author',
  filter: 'isActive == true',
}

Helpers

helpers.listing('author', {
  title: 'Active Authors',
  filter: 'isActive == true',
});

Organized Sub-sections

Filters are commonly used within children to create organized views of the same document type.

JSON

{
  title: 'Authors',
  children: [
    {
      title: 'Active',
      schemaType: 'author',
      filter: 'isActive == true',
    },
    {
      title: 'Inactive',
      schemaType: 'author',
      filter: 'isActive != true',
      hideAddButton: true,
    },
  ],
}

Helpers

helpers.children('Authors', [
  helpers.listing('author', {
    title: 'Active',
    filter: 'isActive == true',
  }),
  helpers.listing('author', {
    title: 'Inactive',
    filter: 'isActive != true',
    hideAddButton: true,
  }),
]);

Using Filter Parameters

Use filterParams to pass dynamic values to your GROQ query.

JSON

{
  title: 'Authors from GROQ',
  filter: '_type == $author',
  filterParams: {
    author: 'author',
  },
}

Helpers

helpers.filters({
  title: 'Authors from GROQ',
  filter: '_type == $author',
  filterParams: {
    author: 'author',
  },
});

Multiple Document Types

You can create a mixed list of multiple document types by using a more complex GROQ filter.

JSON

{
  title: 'Authors + Homepage from GROQ',
  filter: '_type == $author || _type == $homepage',
  filterParams: {
    author: 'author',
    homepage: 'homepage',
  },
}

Helpers

helpers.filters({
  title: 'Authors + Homepage from GROQ',
  filter: '_type == $author || _type == $homepage',
  filterParams: {
    author: 'author',
    homepage: 'homepage',
  },
});

Function-based Filtering

You can pass a function to both filter and filterParams to dynamically control the list based on the current user. The following two examples achieve the exact same result:

1. Using Dynamic Filter String

In this approach, you return the entire GROQ string from the filter function.

JSON

{
  title: 'My Posts',
  schemaType: 'post',
  filter: ({ currentUser }) => `author == "${currentUser.id}"`,
}

Helpers

helpers.listing('post', {
  title: 'My Posts',
  filter: ({ currentUser }) => `author == "${currentUser.id}"`,
});

2. Using Dynamic Filter Parameters

In this approach, you keep the filter string static and use a function for filterParams to pass the user ID.

JSON

{
  title: 'My Posts',
  schemaType: 'post',
  filter: 'author == $userId',
  filterParams: ({ currentUser }) => ({
    userId: currentUser.id,
  }),
}

Helpers

helpers.listing('post', {
  title: 'My Posts',
  filter: 'author == $userId',
  filterParams: ({ currentUser }) => ({
    userId: currentUser.id,
  }),
});

3. Combining Both

You can also combine both for more complex logic.

JSON

{
  title: 'My Role-based Documents',
  schemaType: 'post',
  filter: ({ currentUser }) => currentUser.roles.includes('administrator')
    ? 'status == $status'
    : 'author == $userId && status == $status',
  filterParams: ({ currentUser }) => ({
    status: 'published',
    userId: currentUser.id,
  }),
}

Helpers

helpers.listing('post', {
  title: 'My Role-based Documents',
  filter: ({ currentUser }) =>
    currentUser.roles.includes('administrator')
      ? 'status == $status'
      : 'author == $userId && status == $status',
  filterParams: ({ currentUser }) => ({
    status: 'published',
    userId: currentUser.id,
  }),
});

Combined with Roles & Workspaces

Filters work seamlessly with other properties like roles and workspaces.

JSON

{
  title: 'Internal Authors',
  schemaType: 'author',
  workspaces: ['admin-workspace'],
  roles: ['administrator'],
  filter: 'isInternal == true',
}

Helpers

helpers.listing('author', {
  title: 'Internal Authors',
  workspaces: ['admin-workspace'],
  roles: ['administrator'],
  filter: 'isInternal == true',
});

Dynamic Filter based on Workspace (Callback)

You can define the filter and filterParams dynamically using workspace context:

JSON

{
  schemaType: 'author',
  filter: ({ workspace }) => workspace === 'production' ? 'status == "active"' : 'true',
}

Helpers

helpers.listing('author', {
  filter: ({ workspace }) => (workspace === 'production' ? 'status == "active"' : 'true'),
});