# Category Modal

A pop-up modal showing the catalog's top-level categories as a tile grid. Useful for guided shopping flows where you want users to commit to a category before browsing items, or to surface a one-time category selector on first visit.

## Available in

* Catalog modules
* Public Page modules

## When to use

* A "What are you shopping for?" first-visit prompt that introduces users to the catalog.
* Wholesale catalogs where products are very different by category (industrial supplies vs office supplies) and you want the user to choose first.
* Mobile catalog flows where you want to constrain the initial choice to a small set of top-level categories.

For ongoing in-context category browsing, use **Category Sidebar** or **Category Display** instead — those are persistent on the page rather than modal.

## Settings

| Setting                      | Description                                                                                   |
| ---------------------------- | --------------------------------------------------------------------------------------------- |
| **Modal Title**              | Heading shown at the top of the modal. Default: *Categories*.                                 |
| **Auto Open Modal**          | Open the modal automatically when the page loads. Default: Yes.                               |
| **Show Only on First Visit** | Open automatically only on the first visit (subsequent visits won't auto-open). Default: Yes. |
| **Show Category Image**      | Display category images on the tiles. Default: Yes.                                           |
| **Show Category Title**      | Display category titles on the tiles. Default: Yes.                                           |
| **Title Position**           | Where the title sits on the tile: top, bottom, or overlay on the image. Default: bottom.      |
| **Preview**                  | Trigger a preview of the modal in edit mode (so you can verify styling).                      |

## What it depends on

Category Modal draws from the same **Catalog Categories** data as Category Sidebar and Category Display. If that toggle is off on the linked catalog, the modal opens but shows no tiles.

| What to verify                                         | Where                                                                 |
| ------------------------------------------------------ | --------------------------------------------------------------------- |
| **Catalog Categories** toggle is on                    | **Catalogs** → open the catalog → **Settings** → *Catalog Categories* |
| The catalog has been rebuilt after enabling the toggle | **Catalogs** list → **Reprocess** on the catalog row                  |

## How it works

1. On page load, if **Auto Open Modal** is on (and **Show Only on First Visit** allows), the modal opens.
2. The modal renders top-level categories (parent = null) in a responsive grid: 2 cols mobile, 3 cols sm, 4 cols md, 6 cols lg.
3. The user clicks a category tile.
4. The selection writes to `selectedCategory` in the app state and the modal closes.
5. **Catalog Display** filters its items to that category — this is the only way the modal's category selection reaches the product list.

In edit mode the block renders an invisible placeholder (with a dashed border in the editor) so it doesn't block your view of the rest of the page. Use the Preview button to spot-check styling.

{% hint style="info" %}
Set **Show Only on First Visit** to Yes for a non-intrusive first-time experience — repeat visitors don't get re-prompted. Pair with a small Action Button labelled *Browse Categories* that re-opens the modal on demand.
{% endhint %}

## Examples

**First-visit category prompt.** Category Modal at the top of a B2B catalog. Auto Open = Yes, Show Only on First Visit = Yes. New users get a one-time category picker.

**Mobile-first selector.** Category Modal with no auto-open, triggered manually by a Browse Categories button in the sidebar. Title Position = overlay for tighter tiles.

**Category-first design.** Category Modal with Auto Open = Yes, Show Only on First Visit = No. The modal opens every time the catalog loads — appropriate when the catalog is genuinely category-driven.

## Related

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Category Display</strong></td><td>The non-modal alternative — inline grid or dropdown.</td><td><a href="/pages/udRaPvzhitC3MaCaFCJl">/pages/udRaPvzhitC3MaCaFCJl</a></td></tr><tr><td><strong>Category Sidebar</strong></td><td>The persistent sidebar tree alternative.</td><td><a href="/pages/iHgOoEc4CBkQG9A3oaPT">/pages/iHgOoEc4CBkQG9A3oaPT</a></td></tr><tr><td><strong>Modal</strong></td><td>The general-purpose modal block — use for non-category pop-ups.</td><td><a href="/pages/q0VmZaW68R0qPOGtHU51">/pages/q0VmZaW68R0qPOGtHU51</a></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.in8sync.com/client-admin-guide/active-workflows/getting-started/catalog-components/category-modal.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.