Categories and navigation

Query the category tree, build navigation menus, display breadcrumbs and fetch category detail pages using Propeller's GraphQL API.

Fetching categories

Use the categories query to retrieve the category tree. Categories have a parent-child hierarchy that you can use to build nested navigation.

query GetCategories($language: String) {
  categories {
    items {
      ... on Category {
        categoryId
        name(language: $language) {
          value
        }
        parent {
          categoryId
          name(language: $language) {
            value
          }
        }
        categoryPath {
          categoryId
          name(language: $language) {
            value
          }
        }
      }
    }
    itemsFound
    page
    pages
  }
}

The response includes:

• parent — the direct parent category (null for top-level categories)
• categoryPath — the full hierarchy from root to the current category, useful for building breadcrumbs

Filtering categories

The categories query accepts a CategorySearchInput to narrow results:

Filter	Description
categoryId	Find categories by one or more IDs
parentCategoryId	Find child categories of a specific parent
name	Find categories by name (text search)
slug	Find categories by URL slug
language	Language to use when searching by name or slug
hidden	Filter by visibility (Y or N)
sortField	Sort results by name, dateCreated or dateChanged
sortOrder	Sort direction: ASC (default) or DESC
page / offset	Pagination controls

To fetch only top-level categories, filter by the root parent ID. The root category ID varies per Propeller installation:

query GetTopLevelCategories($language: String) {
  categories(filter: { parentCategoryId: [1] }) {
    items {
      ... on Category {
        categoryId
        name(language: $language) {
          value
        }
      }
    }
  }
}

To fetch subcategories of a specific category:

query GetSubcategories($parentId: [Int!], $language: String) {
  categories(filter: { parentCategoryId: $parentId }) {
    items {
      ... on Category {
        categoryId
        name(language: $language) {
          value
        }
      }
    }
  }
}

Category detail page

Fetch detailed information for a single category by slug:

query GetCategoryDetails($slug: String, $language: String) {
  category(slug: $slug) {
    categoryId
    name {
      language
      value
    }
    description {
      language
      value
    }
    shortDescription {
      language
      value
    }
    slug(language: $language) {
      value
    }
    parent {
      categoryId
      name(language: $language) {
        value
      }
    }
    categoryPath {
      categoryId
      name(language: $language) {
        value
      }
      slug(language: $language) {
        value
      }
    }
  }
}

Use categoryPath to build a breadcrumb from the root category down to the current one.

Building a breadcrumb

The categoryPath field returns the full hierarchy as an ordered array. Each entry contains the category name, slug and ID, which you can map to your breadcrumb component.

This also works on the product query — products have a categoryPath field that returns the hierarchy of their assigned category.

Products within a category

To display products from a specific category, use the products query with a categoryId filter:

query GetCategoryProducts($categoryId: Int, $language: String) {
  products(input: { categoryId: $categoryId }) {
    items {
      ... on Product {
        productId
        names(language: $language) {
          value
        }
        price {
          gross
          net
        }
      }
      ... on Cluster {
        names(language: $language) {
          value
        }
        defaultProduct {
          productId
          price {
            gross
            net
          }
        }
      }
    }
    itemsFound
    page
    pages
  }
}

This returns both products and clusters within the category. Combine with pagination, filters and sorting as described in Querying products.

Next steps

• Understanding products and categories — how clusters, products and attributes work
• Querying products — filtering, pagination and search
• Media and assets — product images, videos and documents