> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartble.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizing products into collections and categories

> Understand how collections and categories differ in Cartble, how to create both types, and how collections can appear in your storefront navigation menus.

Cartble gives you two complementary tools for organizing your catalog: **collections** and **categories**. They serve different purposes and live in different parts of the admin. Collections are customer-facing groupings used to curate themed pages on your storefront (for example, "Summer Picks" or "Staff Favorites"). Categories form an internal taxonomy that classifies products for filtering and SEO — they are hierarchical and can be nested arbitrarily deep.

## Collections

Navigate to **Admin → Collections** to manage your collections.

### Collection types

<CardGroup cols={2}>
  <Card title="Manual" icon="hand">
    You hand-pick which resources belong to the collection. Use this for editorial or curated groups where you control membership directly.
  </Card>

  <Card title="Automated" icon="sparkles">
    Cartble populates the collection automatically based on rules you define. Any resource that matches the conditions is included without further action.
  </Card>
</CardGroup>

### Creating a collection

<Steps>
  <Step title="Set the name and slug">
    Enter a **name** (e.g., "Best of 2025"). The **slug** is auto-generated from the name and is used in the storefront URL (`/collections/best-of-2025`). You can edit the slug manually before saving.
  </Step>

  <Step title="Add a description and cover image">
    The description appears on the collection page in your storefront. Upload a **cover image** to give the collection a visual identity.
  </Step>

  <Step title="Choose the collection type">
    Select **Manual** or **Automated**. For automated collections, add one or more rules (see below).
  </Step>

  <Step title="Configure display options">
    * **Featured** — marks the collection as highlighted; themes can use this flag to call out the collection in hero sections or promotional areas.
    * **Show in menu** — makes this collection available as a navigation target when you build menus in **Admin → Navigation**.
  </Step>

  <Step title="Add SEO metadata">
    Optionally enter a custom `seo.title` and `seo.description` for the collection page.
  </Step>
</Steps>

### Automated collection rules

Each rule has three parts:

| Field         | Options                                                                                             |
| ------------- | --------------------------------------------------------------------------------------------------- |
| **Attribute** | Item Title, Price, Promotional Price, Tag, Category, Stock                                          |
| **Relation**  | equals, does not equal, contains, does not contain, greater than, less than, starts with, ends with |
| **Value**     | The string or number to match against                                                               |

You can add as many rules as needed. A resource is included in the collection when it matches **any** of the defined rules.

<Note>
  Automated collections update in real time as resources are created or edited. You do not need to manually add products after a rule is configured.
</Note>

## Categories

Navigate to **Admin → Categories** to manage your category hierarchy.

Categories are organized in a tree structure. Each category can have a parent, and Cartble tracks the full `path` (array of ancestor IDs) and `level` (depth in the tree) automatically.

### Creating a category

<Steps>
  <Step title="Enter a name and slug">
    The slug is auto-generated from the name. It appears in category URLs and internal references.
  </Step>

  <Step title="Select a parent (optional)">
    Leave the parent blank to create a root-level category. Selecting a parent nests the new category underneath it. Cartble prevents circular nesting automatically.
  </Step>

  <Step title="Set display order">
    Use the **Display Order** number to control the sort position among siblings. Lower numbers appear first.
  </Step>

  <Step title="Set visibility status">
    * `active` — visible to customers browsing the storefront
    * `hidden` — suppressed from the storefront (useful for staging or internal-use categories)
  </Step>

  <Step title="Add an image and description">
    Both are optional but improve the browsing experience when your storefront theme renders category pages.
  </Step>

  <Step title="Add SEO metadata">
    Set `metaTitle` and `metaDescription` per category page individually.
  </Step>
</Steps>

<Warning>
  Deleting a parent category does not automatically delete its children. Move or reassign child categories before removing a parent to avoid orphaned entries.
</Warning>

## Collections vs. categories at a glance

|                      | Collections                    | Categories                               |
| -------------------- | ------------------------------ | ---------------------------------------- |
| **Purpose**          | Storefront curation            | Internal taxonomy                        |
| **Structure**        | Flat                           | Hierarchical (tree)                      |
| **Membership**       | Manual or rule-based           | Assigned per resource                    |
| **Navigation menus** | Yes (`showInMenu`)             | Yes (via NavigationItem type `category`) |
| **SEO fields**       | `seo.title`, `seo.description` | `metaTitle`, `metaDescription`           |

## Using collections in navigation

When you toggle **Show in menu** on a collection, it becomes available in the **Navigation Editor** (**Admin → Navigation**) as a link target of type `collection`. Navigation items support dropdown and mega-menu layouts, so you can surface featured collections alongside other links.