This is a beta release of documentation for Magento 2.4, published for previewing soon-to-be-released functionality. Content in this version is subject to change. Links to the v2.4 code base may not properly resolve until the code is officially released.

categoryList query

Edit on GitHub
Log an Issue

The categoryList query searches for categories that match the criteria specified in filters. It replaces the deprecated category query, which allowed you to search by category ID only.

This query does not support pagination. Use the categories query if you expect to return a large number of categories.

The categoryList query supports the following types of filters. You can specify multiple filters in a query.

  • Category ID
  • Category name
  • URL key
  • URL path

If you do not provide any filter input, the query returns the root category.

The query returns a CategoryTree object. The top level of the CategoryTree object provides details about the queried category. This object includes the children attribute, which contains an array of its immediate subcategories. To return multiple category levels in a single call, define the response so that it contains up to ten nested children options.

You cannot return the entire category tree if it contains more than ten sublevels unless the queryDepth parameter in the GraphQL di.xml file has been reconfigured.

Use the breadcrumbs attribute to return information about the parent categories of the queried category.

Syntax

1
2
3

categoryList (
   filters: CategoryFilterInput
): CategoryTree

Example usage

Return the category tree of a top-level category

The following query returns information about category IDs 11 and 20 and two levels of subcategories. In the sample data, category IDs 11 and 20 are assigned to the Men and Women categories, respectively.

Request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  categoryList(filters: {ids: {in: ["11", "20"]}}) {
    children_count
    children {
      id
      level
      name
      path
      url_path
      url_key
      children {
        id
        level
        name
        path
        url_path
        url_key
      }
    }
  }
}

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

{
  "data": {
    "categoryList": [
      {
        "children_count": "8",
        "children": [
          {
            "id": 13,
            "level": 3,
            "name": "Bottoms",
            "path": "1/2/11/13",
            "url_path": "men/bottoms-men",
            "url_key": "bottoms-men",
            "children": [
              {
                "id": 18,
                "level": 4,
                "name": "Pants",
                "path": "1/2/11/13/18",
                "url_path": "men/bottoms-men/pants-men",
                "url_key": "pants-men"
              },
              {
                "id": 19,
                "level": 4,
                "name": "Shorts",
                "path": "1/2/11/13/19",
                "url_path": "men/bottoms-men/shorts-men",
                "url_key": "shorts-men"
              }
            ]
          },
          {
            "id": 12,
            "level": 3,
            "name": "Tops",
            "path": "1/2/11/12",
            "url_path": "men/tops-men",
            "url_key": "tops-men",
            "children": [
              {
                "id": 14,
                "level": 4,
                "name": "Jackets",
                "path": "1/2/11/12/14",
                "url_path": "men/tops-men/jackets-men",
                "url_key": "jackets-men"
              },
              {
                "id": 15,
                "level": 4,
                "name": "Hoodies & Sweatshirts",
                "path": "1/2/11/12/15",
                "url_path": "men/tops-men/hoodies-and-sweatshirts-men",
                "url_key": "hoodies-and-sweatshirts-men"
              },
              {
                "id": 16,
                "level": 4,
                "name": "Tees",
                "path": "1/2/11/12/16",
                "url_path": "men/tops-men/tees-men",
                "url_key": "tees-men"
              },
              {
                "id": 17,
                "level": 4,
                "name": "Tanks",
                "path": "1/2/11/12/17",
                "url_path": "men/tops-men/tanks-men",
                "url_key": "tanks-men"
              }
            ]
          }
        ]
      },
      {
        "children_count": "8",
        "children": [
          {
            "id": 22,
            "level": 3,
            "name": "Bottoms",
            "path": "1/2/20/22",
            "url_path": "women/bottoms-women",
            "url_key": "bottoms-women",
            "children": [
              {
                "id": 27,
                "level": 4,
                "name": "Pants",
                "path": "1/2/20/22/27",
                "url_path": "women/bottoms-women/pants-women",
                "url_key": "pants-women"
              },
              {
                "id": 28,
                "level": 4,
                "name": "Shorts",
                "path": "1/2/20/22/28",
                "url_path": "women/bottoms-women/shorts-women",
                "url_key": "shorts-women"
              }
            ]
          },
          {
            "id": 21,
            "level": 3,
            "name": "Tops",
            "path": "1/2/20/21",
            "url_path": "women/tops-women",
            "url_key": "tops-women",
            "children": [
              {
                "id": 23,
                "level": 4,
                "name": "Jackets",
                "path": "1/2/20/21/23",
                "url_path": "women/tops-women/jackets-women",
                "url_key": "jackets-women"
              },
              {
                "id": 24,
                "level": 4,
                "name": "Hoodies & Sweatshirts",
                "path": "1/2/20/21/24",
                "url_path": "women/tops-women/hoodies-and-sweatshirts-women",
                "url_key": "hoodies-and-sweatshirts-women"
              },
              {
                "id": 25,
                "level": 4,
                "name": "Tees",
                "path": "1/2/20/21/25",
                "url_path": "women/tops-women/tees-women",
                "url_key": "tees-women"
              },
              {
                "id": 26,
                "level": 4,
                "name": "Bras & Tanks",
                "path": "1/2/20/21/26",
                "url_path": "women/tops-women/tanks-women",
                "url_key": "tanks-women"
              }
            ]
          }
        ]
      }
    ]
  }
}

Return breadcrumb information

The following query returns breadcrumb information about categories that have the name Tops.

Request:

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  categoryList(filters: {name: {match: "Tops"}}) {
    id
    level
    name
    breadcrumbs {
      category_id
      category_name
      category_level
      category_url_key
    }
  }
}

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

{
  "data": {
    "categoryList": [
      {
        "id": 12,
        "level": 3,
        "name": "Tops",
        "breadcrumbs": [
          {
            "category_id": 11,
            "category_name": "Men",
            "category_level": 2,
            "category_url_key": "men"
          }
        ]
      },
      {
        "id": 21,
        "level": 3,
        "name": "Tops",
        "breadcrumbs": [
          {
            "category_id": 20,
            "category_name": "Women",
            "category_level": 2,
            "category_url_key": "women"
          }
        ]
      }
    ]
  }
}

Input attributes

You must specify the filters attribute as input to your query.

Attribute Data type Description
filters CategoryFilterInput Contains filter definitions

CategoryFilterInput object

The CategoryFilterInput object defines the filters to be used in this query.

Attribute Data type Description
ids FilterEqualTypeInput Filters by the specified category IDs
name FilterMatchTypeInput Filters by the display name of the category
url_key FilterEqualTypeInput Filters by the part of the URL that identifies the category
url_path FilterEqualTypeInput Filters by the URL path for the category

FilterEqualTypeInput object

Use the FilterEqualTypeInput object to construct filters that search by category ID or URL key.

Attribute Data type Description
eq String Use this attribute to exactly match the specified string. For example, to filter on a specific URL key, specify a value like shorts-women
in [String] Use this attribute to filter on an array of values. For example, to filter on category IDs 4, 5, and 6, specify a value of ["4", "5", "6"]

FilterMatchTypeInput object

Use the FilterMatchTypeInput object to construct a filter that matches the specified display name.

Attribute Data type Description
match String Use this attribute to perform a fuzzy match on the specified string. For example, to filter on a specific category name, specify a value such as Tops

Output attributes

The query returns a CategoryTree object, which implements CategoryInterface. The CategoryTree object can contain the following attribute and all attributes defined in CategoryInterface:

Attribute Data type Description
children CategoryTree An array containing the next level of subcategories. By default, you can specify up to 10 levels of child categories
© 2020 Magento. All rights reserved.