Get help on Discord

Mix explicit list items with dynamic documentList in Structure Builder

3 replies
Last updated: Nov 30, 2025
In the structure builder, is it possible to mix explicitly defined list items with a dynamic documentList?For example showing a list item at the top of the pane for categories, and then the list of all posts below, instead of having to drill down one more level to "all posts".
AI Update

Yes, you can absolutely mix explicitly defined list items with a dynamic documentList in the same pane! This is a common pattern in the Structure Builder and exactly the kind of flexible organization it was designed to support.

Here's how you can achieve what you're describing - showing a "Categories" list item at the top, followed by all posts:

// sanity.config.ts
import {structureTool} from 'sanity/structure'

export default defineConfig({
  plugins: [
    structureTool({
      structure: (S) =>
        S.list()
          .title('Content')
          .items([
            // Explicit list item for browsing by category
            S.listItem()
              .title('Posts by Category')
              .child(
                S.documentList()
                  .title('Categories')
                  .filter('_type == "category"')
              ),
            
            // Divider for visual separation (optional)
            S.divider(),
            
            // All posts as a document list
            ...S.documentTypeListItems().filter(
              listItem => listItem.getId() === 'post'
            ),
            
            // Or you could be more explicit:
            // S.documentTypeListItem('post').title('All Posts'),
            
            // Add other document types
            ...S.documentTypeListItems().filter(
              listItem => !['post', 'category'].includes(listItem.getId())
            )
          ])
    })
  ]
})

The key insight is that the items array in S.list() accepts any combination of:

  • S.listItem() - Custom list items that can open child lists or documents
  • S.documentTypeListItem() - Convenience method for standard document type lists
  • S.documentList() - Filtered document lists
  • S.divider() - Visual separators

You can even get more creative by mixing in filtered document lists directly:

S.list()
  .title('Posts')
  .items([
    // Browse by category
    S.listItem()
      .title('By Category')
      .child(/* category browser */),
    
    // Recently published
    S.listItem()
      .title('Recent Posts')
      .child(
        S.documentList()
          .title('Recently Published')
          .filter('_type == "post"')
          .params({})
      ),
    
    S.divider(),
    
    // All posts
    S.documentTypeListItem('post').title('All Posts')
  ])

The Structure Builder is incredibly flexible - you're not limited to the default "drill down" pattern. You can flatten your structure, mix different types of navigation, and organize content however makes the most sense for your editors. The Structure Builder documentation has more examples of creative ways to organize your content.

Show original thread
3 replies

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Get started for freeExplore the demo

Was this answer helpful?