Front Matter Reference
On This Page
Front Matter Restrictions
You can use front matter to specify attributes on the tops of pages in your
<theme-name>/templates/pages/subdirectory, but you cannot use front matter to accomplish this on pages in the following subdirectories:
<theme-name>/templates/components/<theme-name>/templates/layout/<theme-name>/templates/pages/custom/
- Indent using only spaces. (YAML forbids tabs to avoid inconsistent encoding of tabs across platforms.) An indent of even one space indicates a child.
- Front matter on a given page cannot exceed 64 KB.
- If a front-matter directive contains an invalid option, Stencil CLI will silently ignore that option.
Global Attributes
Global attributes are available on all pages.
| Attribute | Option with Sample Assignment | Default Value | Details and Other Allowable Values/Results |
|---|---|---|---|
| customer: | Customer attributes are always included, and are available if the active shopper is logged in. | ||
| addresses: true | true – on address page null – on all other pages | Boolean indicating whether to retrieve addresses for this customer. No filtering available. Default sorting is by address id, from lowest to highest. null or false: Do not retrieve addresses. true: Retrieve addresses. | |
| returns: true | true – on returns page; null – on all other pages | Boolean indicating whether to retrieve product-return requests for this customer. No filtering available.true: Retrieve requests. null or false: Do not retrieve requests. | |
| wishlists: limit: <number> |
null | null: No wishlists displayed.
<number> limits the number of wishlists displayed. If <number> is not defined, retrieves an unlimited number of wishlists. |
|
| orders: limit: <number> |
null | Contains all orders, complete or not.
null: no orders displayed. <number> limits the number of orders displayed. If <number> is not defined, displays 20 orders. (Default sorting is by order id, from lowest to highest.) |
|
| recently_viewed_products: | null | Boolean indicating whether to display recently viewed products. No filtering available. |
|
| products: | (When filtering/limiting, products' default sorting is by order id, from lowest to highest.) | ||
| featured: limit: <number> |
null | null: No featured products displayed. <number> limits the number of featured products displayed. If <number> is not set, defaults to 4 products. |
|
| new: limit: <number> |
null | null: No new products displayed. <number> limits the number of new products displayed. Maximum allowable value is 25. If <number> is not defined, defaults to 8 products. |
|
| top_sellers: limit: <number> |
null | null: No top-selling products displayed.
<number> limits the number of top sellers displayed. If <number> is not defined, defaults to all top sellers. |
|
| carousel: true | null | Boolean indicating whether to display a carousel on storefront.
No filtering available. null or false: No carousel display. |
|
| blog: | (Default sorting is by published_date, from most-recent to earliest.) This does not work on the blog page. See [Blog Attributes](https://developer.bigcommerce.com/stencil-docs/reference-docs/front-matter-reference#front-matter-attributes-reference_blog). | ||
| recent_posts: limit: <number> |
20 | null: No recent blog posts displayed.
<number> limits the number of recent blog posts displayed. If <number> is not defined, defaults to the maximum of 20 blog posts. |
|
| summary: <number> | 100 |
<number> sets the number of characters to display in each blog-post summary.
If <number> is not defined, displays 100 characters. |
|
| cart: true | false | Boolean indicating whether to retrieve cart data. true: Return cart data. false: Do not return cart data. |
|
| categories: true | false | Boolean indicating whether to retrieve the category tree during an AJAX request.
true: Retrieve the category tree. false: Do not retrieve the category tree. |
|
| description: true | false |
Boolean indicating whether to retrieve category descriptions dynamically from the database.
Set to true for themes that must display category descriptions when pages render. (This can slow page loads.) |
|
| shop_by_brand: | limit: <number> | null | Typically used in a footer or sidebar. null: Do not display this brand list. <number> limits the number of brands to return. If <number> is not defined, returns 10 brands, ordered by the number of products per brand. |
Category Attributes
Category attributes are available in the context of a category.
| Attribute | Option with Sample Assignment | Default Value | Details |
|---|---|---|---|
| category: | |||
| shop_by_price: | false | Boolean indicating whether to display Shop-by-Price controls. | |
| products: limit: <number> |
16 | Defines the number of products displayed per page for this category. Range of possible values is 1–100 products. |
Blog Attributes
Blog attributes are available in the context of a blog.
| Attribute | Sub-Attribute | Option with Sample Assignment | Default Value | Details |
|---|---|---|---|---|
| blog: | ||||
| posts: | (Default sorting is by published_date, from most-recent to earliest.) | |||
| limit: <number> | null | null: No blog posts displayed. <number> limits the number of blog posts displayed. Maximum is 20 blog posts per page. |
||
| pages: <number> | 5 | null: No pagination. <number> sets the number of pages to display in pagination links. If <number> is not defined, defaults to 5 pages. | ||
| summary: <number> | 250 |
<number> sets the number of characters to display in each blog-post summary. If <number> is not defined, displays 250 characters. |
Product Attributes
Product attributes are available in the context of a product.
| Attribute | Option with Sample Assignment | Default Value | Details |
| product: | (When filtering/limiting, products' default sorting is by order id, from lowest to highest.) | ||
| videos: limit: <number> |
[unlimited] | If product.videos is not defined, no videos are returned. If product.videos is defined, the default behavior is to return all videos. If product.videos.limit is also defined, <number> sets the maximum number of videos returned. | |
| images: limit: <number> |
[unlimited] | If product.images is not defined, no images are returned. If product.images is defined, you must also define product.images.limit, which throttles the number of images returned. The maximum allowable value for this option's <number> parameter is 5 images. | |
| reviews: true limit: <number> |
[false] | Boolean indicating whether to display product reviews. If product.reviews is present, and is not explicitly set to "false", reviews will appear. If <number> is not defined, defaults to 10 reviews (When filtering/limiting reviews, default sorting is by review id, from lowest to highest). | |
| related_products: limit: <number> |
[unlimited] | Displays products that are related by name. <number> limits the number of products displayed. If <limit> is absent or undefined, the default behavior is to display all related products. Inserting “limit:” with no integer will display 0 products. | |
| similar_by_views: limit: <number> |
[unlimited] | Displays products similar to those displayed in the current page context. <number> limits the number of products displayed. If <limit> is absent or undefined, default is to display 4 products. |
Brand Attributes
Brand attributes are available in the context of a brand.
| Attribute | Option with Sample Assignment | Default Value | Details |
| brand: | |||
| products: limit: <number> |
50 | Defines the number of products displayed per page for this brand. Range of possible values is 1–50 products. |
Brand List Attributes
These attributes are available in the context of a list of brands.
| Attribute | Option with Sample Assignment | Default Value | Details |
| brands: | (When retrieving a collection of brands, default sorting is by brand id, from lowest to highest.) | ||
| limit: <number> | 50 | Sets the number of brands displayed in the list. If <limit> is not defined, returns all brands, up to a maximum of 50. |
Cart Attributes
Cart attributes are available in the context of a shopper’s cart.
| Attribute | Sub-Attribute | Option with Sample Assignment | Default Value | Details |
| cart | ||||
| suggestions: | Suggested products to display to shopper, based on cart contents. |
|||
| limit: <number> | null | null: Do not display suggested products. <number> limits the number of suggested products to return. If <number> is not defined, returns 4 suggested products. |
Search Attributes
Search attributes are available in the context of a search results page.
| Attribute | Sub-Attribute | Option with Sample Assignment | Default Value | Details |
| search | ||||
| product_results: | ||||
| limit: <number> | 16 | Defines the number of product search results displayed per page. Range of possible values is 1–100 products. |