How to use category metafields in your theme

After you create a category metafield and enable storefront access, you can query it with GraphQL.

You can send the query from JavaScript, but changes made this way are client-side.

info

We recommend testing new GraphQL queries in the Storefront API playground first.

However, Stencil themes can run GraphQL queries in front matter. BigCommerce makes the response available server-side, so you can use the GraphQL data in your template.

For example, this query searches the custom namespace for the test_content key on the current category. Adding it to the theme front matter makes the response available as gql in the template.

---
category:
    shop_by_price: true
    products:
        limit: {{theme_settings.categorypage_products_per_page}}
gql: "query categoryById($categoryId: Int!) {
    site {
        category(entityId: $categoryId) {
            metafields(namespace:\"custom\",keys: [\"test_content\"]) {
                edges {
                    node {
                        key
                        value
                    }
                }
            }
        }
      }
    }
"
---

If the metafield contains raw HTML, render it in the category template with triple braces ({{{ }}}):

<div class="page-content" id="product-listing-container">
    {{#each gql.data.site.category.metafields.edges}}
        {{{node.value}}}
    {{/each}}
    {{> components/category/product-listing}}
    {{{region name="category_below_content"}}}
</div>

Alternatively, if the metafield was used to enable/disable functionality per category. It could be checked within a condition like so:

{{#each gql.data.site.category.metafields.edges}}
    {{#eq node.value "Yes"}}
       The flag was enabled for this category.
    {{/eq}}
{{/each}}

If you have more than one metafield key selected in your query, you can perform a check based on key name:

{{#each gql.data.site.category.metafields.edges}}
    {{#and (if node.key '==' "test_flag") (if node.value '==' "Yes") }}
        The flag was enabled for this category.
    {{/and}}
    {{#if node.key '===' "test_content"}}
        {{{node.value}}}
    {{/if}}
{{/each}}