Craft supports user-managed, hierarchical taxonomies for content via categories.

Categories are one of Craft’s built-in element types, and are represented throughout the application as instances of craft4:craft\elements\Category.

With the release of Craft 4.4, we began consolidating features of other element types into entries.

As part of that process, we introduced a console command that can automate the conversion of categories to structure sections:

php craft entrify/categories myCategoryGroupHandle

Read more about this transition on our blog.

Every category belongs to a category group, which defines…

• …a name;
• …a handle (used when referencing the group in queries and templates);
• …the maximum number of levels categories can be nested, within the group;
• …the format of category URIs;
• …which template should be rendered when a category’s URL is accessed;
• …which fields categories in the group should have;

To create a new category group, go to Settings → Categories and click New Category Group.

Each category group has its own field layout, which allows you to customize the data that’s associated with each category in the group. By default, every category will have a Title field (the category name). Any available field type can be added to a category group’s field layout.

When you’ve defined at least one category group, Categories will appear in the control panel’s primary navigation. Clicking it will take you to the category index. From there, you can choose a category group from the sidebar, and add/reorder/delete categories within it:

Select the “Structure” sort option to view and manipulate the categories’ hierarchy. Double-click any element to open a slideout.

You can also click a category’s title to visit its edit page just like an entry.

When you create a category, you have the following options:

• Fill out the category fields (if you didn’t define any, the only field available will be Title)
• Edit the slug (it’s automatically populated based on the title).
• Choose a Parent category. The new category will have a hierarchical relationship with its parent. This is helpful for creating taxonomies with multiple levels. You also have the option of creating a new category while assigning the Parent.

::: tip You can only nest categories up to the level specified in the Max Level field Category Group settings. If it’s empty, the nesting level is unlimited. :::

To assign categories to things (entries, assets, users, etc.), you must first create a Categories field.

Each Categories field is connected to a single category group. Whatever you attach the field to will store relations to categories selected from that group.

You can fetch categories in your templates or PHP code using category queries.

::: code

{# Create a new category query #}
{% set myCategoryQuery = craft.categories() %}

// Create a new category query
$myCategoryQuery = \craft\elements\Category::find();

:::

Once you’ve created a category query, you can set parameters on it to narrow down the results, and then execute it by calling .all(). An array of Category objects will be returned.

We can display a navigation for all the categories in a category group called “Topics” by doing the following:

1. Create a category query with craft.categories().
2. Set the group parameter on it.
3. Fetch the categories with .all().
4. Loop through the categories using a nav tag to create the navigation HTML.

{# Create a category query with the 'group' parameter #}
{% set myCategoryQuery = craft.categories()
  .group('topics') %}

{# Fetch the categories #}
{% set categories = myCategoryQuery.all() %}

{# Display the navigation #}
<ul>
  {% nav category in categories %}
    <li>
      <a href="{{ category.url }}">{{ category.title }}</a>
      {% ifchildren %}
        <ul>
          {% children %}
        </ul>
      {% endifchildren %}
    </li>
  {% endnav %}
</ul>

::: tip To maintain the exact order you see in the control panel, add orderBy('lft ASC') to your query:

{% set myCategoryQuery = craft.categories()
  .group('topics')
  .orderBy('lft ASC') %}

:::

When you’ve attached a categories field to another type of element, you can query for those elements when you have a reference to a category.

For example, if we were building a blog with dedicated “Topic” (category) pages, we might build a query like this to look up posts:

{% set posts = craft.entries()
  .relatedTo({
    targetElement: category,
    field: 'topics',
  })
  .all() %}

Category queries support the following parameters:

!!!include(docs/.artifacts/cms/4.x/categories.md)!!!