--- title: "Modular Block Previews and Categories" description: "Add preview images and categories to the blocks in a Modular Blocks field so content managers can find and add the right block visually in the entry editor." url: "https://www.contentstack.com/docs/headless-cms/modular-block-previews-and-categories" product: "Contentstack" doc_type: "guide" audience: - developers - admins version: "current" last_updated: "2026-11-03" --- # Modular Block Previews and Categories Preview images and categories help content managers pick the right block in a [Modular Blocks](/docs/headless-cms/modular-blocks) field. Instead of choosing from block names alone, they see an image of each block and can browse blocks by category. * A **preview image** shows what a block looks like, for example a screenshot of the hero banner it renders on your site. * A **category** groups related blocks, for example Heroes, Media, or Calls to Action. Each block belongs to one category at most. You set both in the content type builder or the global field builder. Content managers then see them when they add a block in the entry editor and in [Visual Editor](/docs/headless-cms/navigating-your-website-in-visual-editor). ## Add Categories to a Modular Blocks Field Categories belong to a Modular Blocks field. Create them in the field's properties, then assign blocks to them. To add categories, log in to your [Contentstack account](/login/), and perform the following steps: 1. Go to your [stack](/docs/headless-cms/about-stack) and click the "Content Models" icon in the left navigation panel. 2. Open the content type or global field that contains the Modular Blocks field. 3. Hover over the **Modular Blocks** field and click the **Properties** icon. 4. Select the **Advanced** tab. 5. Under **Add Categories**, type a category name and press **Enter**. Repeat for each category. ![The Add Categories setting in the Advanced tab of the Modular Blocks field properties, with two categories added](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am3a566e247277d6ae/4fdedf0090f3cb195c759860/modular-block-previews-add-categories.png) 6. Click **Save** or **Save and Close**. Removing a category leaves its blocks without a category. The blocks themselves are not affected. ## Add a Preview Image and Category to a Block To add a preview image and category to a block, log in to your [Contentstack account](/login/), and perform the following steps: 1. Go to your [stack](/docs/headless-cms/about-stack) and click the "Content Models" icon in the left navigation panel. 2. Open the content type or global field that contains the Modular Blocks field. 3. Hover over the block, click its vertical ellipsis, and select **Manage Preview and Category**. 4. In the **Manage Preview & Category** modal, add an image under **Add Block Preview**: * **Choose an image**: select an existing image from your assets. * **Upload new image**: select the asset folder to save the image in, then upload a JPEG, PNG, or WEBP file of up to 5 MB. To change the image later, use the same options. To remove it, click the delete icon next to the image. 5. Under **Add category**, select one of the field's categories. 6. Check the **Entry Editor Preview**. It shows the block as content managers see it, both as a card in the block list and as an added block. ![The Manage Preview & Category modal with an uploaded image, the Heroes category selected, and the Entry Editor Preview on the right](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/amc01eca22f0263061/d45af816e021c1e16d16a51d/modular-block-previews-manage-preview-and-category.png) 7. Click **Save** to close the modal. 8. Click **Save** or **Save and Close** to save the content type or global field. Your changes apply only when you save it. **Tip** Use images of the same size and orientation for all the blocks in a field. The block list shows them side by side, so consistent images are easier to compare. ### Blocks in Global Fields When a Modular Blocks field is part of a [global field](/docs/headless-cms/modular-blocks-within-global-fields), set its preview images and categories in the global field builder. Every content type that uses the global field shows them. ## Add Blocks in the Entry Editor Once a Modular Blocks field has a block with a preview image, or has categories, the entry editor shows an **Add Block** dropdown for that field in place of one button per block. A field with neither keeps the buttons. To add a block, perform the following steps: 1. In the Modular Blocks field, click **Add Block**. The dropdown lists the first five blocks, each with its preview image. ![The Add Block dropdown listing five blocks with their preview images, and View All at the bottom](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am9ef119392a3cf816/dcd8990314e601efe0f319ad/modular-block-previews-add-block-dropdown.png) 2. Click a block to add it to the end of the field. If the field has more than five blocks, click **View All** at the bottom of the dropdown. The **Add Block** modal shows every block as a card with its preview image and category. In the modal, you can: * Search for a block by name. * Select a category on the left to show only its blocks. * Select one or more blocks and click **Add**. Each selected block is added to the end of the field. ![The Add Block modal with a search box, a list of categories on the left, and a card for each block showing its preview image and category](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/amb84c3f31e0730ae7/9d129f596a65a973fe4abe07/modular-block-previews-add-block-modal.png) A block you cannot add is shown disabled, and hovering over it shows why. For example, a block has reached its maximum number of instances, or the field has reached its [maximum limit](/docs/headless-cms/minimum-and-maximum-limit). Each block you add shows its preview image next to its title, so you can recognize blocks at a glance. ## Add Blocks in Visual Editor [Visual Editor](/docs/headless-cms/navigating-your-website-in-visual-editor) uses the same preview images and categories. When you add a block, from the [Form](/docs/headless-cms/form) panel or with the **+** icon above or below a block on your page, the **Add Block** modal opens with each block's image and category. Select a block and click **Add**. Visual Editor adds one block at a time. ![The Add Block modal in Visual Editor with a search box, categories on the left, and a card for each block showing its preview image and category](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am56d41cb08a547520/00a973886b2eb483ef966b28/modular-block-previews-visual-editor-add-block-v3.png) In the Form panel, each added block shows its preview image next to its title. Hover over the image to see it larger. For a field without preview images or categories, Visual Editor shows a list of block names as before. ## Preview Images and Categories in the API Preview images and categories are part of the content type and global field schema. A block stores its image in preview\_img, and the field lists its categories in categories. For the schema and its rules, see [JSON Schema for Creating a Content Type](/docs/headless-cms/json-schema-for-creating-a-content-type#modular-blocks).