In this guide, you'll learn how to customize your store theme by managing templates that define the structure of your website pages. Templates declare JSON blocks that, once rendered, determine the set of components for your website pages, such as the homepage, product page, search results page, etc.

The Store Theme app already implements basic templates for each page of your store, defined within its blocks.json or blocks.jsonc files. These templates enable your store to display VTEX Store Framework default components, even if you haven’t made any custom configurations in the code. By managing templates, you can create a custom theme for your website by adding or removing blocks to meet your business needs.

Declare all your blocks in the blocks.jsonc file, or create as many files and folders as needed within the store folder to organize store blocks and templates. You can also declare blocks in the blocks subfolder. The only difference is that jsonc files allow you to add comments to the code.

Since blocks are pieces of code exported by VTEX Store Framework apps, whenever a block is used in your theme, the app behind it must be declared in your Store Theme dependencies list.

The dependencies object within the manifest.json file of your Store Theme app specifies the names and versions of various apps. These apps are pre-listed, as the default Store Theme code already defines templates that use blocks exported by them.

When declaring a new block in your Store Theme app, check if the app blocking it is listed as a dependency. If not, open the manifest.json file and add the app name and desired version to the dependencies list, following this format: "vtex.{appName}": "{majorVersion}.x".

Replace the values between the curly braces based on your scenario.

To better understand how to manage blocks within your Store Theme app, follow the steps below to see the structure of the predefined homepage template:

1. Open the Store Theme app using the code editor of your choice.
2. Go to store and then blocks.
3. Access home and then home.jsonc. You'll see a result similar to the following:

As you can see above, the default store.home homepage template declares the following blocks:

• list-context.image-list#demo
• flex-layout.row#deals
• rich-text#shelf-title
• flex-layout.row#shelf
• info-card#home
• rich-text#question
• rich-text#link
• newsletter

This means that your default store homepage will comprise the components defined by these blocks.

To build more complex components, the home.jsonc file includes each block’s declaration and configuration, using the block's props and, if necessary, other blocks.

More than simply declaring a block in the block list template, you must also define its behavior when rendered as a component. To do this, use the block's props, as shown in the Clarifying block naming and properties section, and include other child blocks to configure it, as detailed in Defining blocks composition.

Still in the home.jsonc file, use ctrl+f and search for the rich-text#question block. This block renders a component that displays markdown text to users.

The rich-text#question block has two props: text and blockClass. The text prop specifies the content the component will display, while blockClass defines an ID used for customization.

To check the available props of the app behind the rich-text block, see the Configuration section within the Rich Text app documentation. Note that the exported block's name is simply rich-text, whereas Store Theme uses rich-text#block. This is because you can use a # symbol after the block's official name to easily identify it when inserting it into the theme's code and better organize the theme.

All the props available to configure a block can be found in the documentation of its exporting app or in the block's own documentation (if applicable).

Still in the home.jsonc, search for theshelf#home block.

Note that it declares another block to your blocks list, which in turn declares other blocks below in a list called children:

In the example above, product-summary.shelf requires other blocks as children, such as product-summary-name, to render the component properly.

As previously mentioned, a component can be a crossroad for multiple blocks. Therefore, one of your theme blocks may need to list other blocks to achieve the desired rendering on the UI.

To build a component using multiple blocks, the main block can declare a blocks list, such as shelf#home, or a children list, as seen in the product-summary.shelf block.

As explained in Understand the block composition, the choice between using a blocks or children list depends on the composition of the blocks being declared.