# Two-level taxonomy model

This guide shows how to create a two-level taxonomy model that lets you select parent categories that displays reference fields to add related sub-categories.

**Do you have suggestions?:**
[Join our community](https://hygraph-community.slack.com) to suggest new recipe ideas!

This guide shows how to create a two-level taxonomy model that lets you select parent categories that display reference fields to add related sub-categories.

You'll create an enumeration for the parent categories, two sub-category models, a category selector component, and a final sample model for a drinks page that lets you add some basic information about the drink, and select parent categories and sub-categories for it.

![Two-level taxonomy model](https://hygraph.com/images/docs/recipes/taxonomy/two-level-taxonomy-model.png)

This recipe is a great option if you need a taxonomy setup that allows referencing sub-category entries based on the parent category selected. A setup like this ensures that after selecting a parent category, editors will only be able to reference sub-categories related to it.

**Note:**

[Taxonomies](https://hygraph.com/docs/developer-guides/schema/taxonomies) are now available in Hygraph. This eliminates the need for any manual configuration, and simplifies content organization and ensures consistency across your schema. Contact our sales team for access.

This image shows what a frontend using this setup could look like:

![Two-level taxonomy - frontend visual example](https://hygraph.com/images/docs/recipes/taxonomy/two-level-taxonomy-model-example.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, [<strong>you can sign up here.</strong>](https://app.hygraph.com/signup)
- `REQUIRED:` You need to have a Hygraph project. Look into the following section to learn more about your options.

### What you can do

Use this guide to create a **Two-level taxonomy** model. You have two options:

- `OPTION 1:` [**Create a project.**](https://hygraph.com/docs/getting-started/quickstart#create-a-project) This is the way to go if you want to follow the entire tutorial for learning purposes.
- `OPTION 2:` **Use an existing project of yours.** This is the way to go if you already have a project and want to add this model. In this case, you may need to adjust parts of the tutorial to your own project schema.

**Note:**
- Take [<strong>plan limits</strong>](https://hygraph.com/pricing) into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our [**Getting Started Tutorial!**](https://hygraph.com/docs/getting-started/tutorial/tutorial-overview)

#### Not in the mood to start building?

[**Clone the entire cookbook**](https://hygraph.com/docs/recipes/taxonomy/section-index#taxonomy-cookbook)

This is the way to go if you're curious about how we built the taxonomy recipes but don't want to follow the step-by-step creation process. This project contains the entire **Taxonomy Cookbook** so you can compare recipes or look into what instances they contain.

## Core concepts

In this guide, you'll work with different schema elements to create a **Two-level taxonomy model**. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models, adding fields, reusable components, and sidebar widgets, integrating remote sources, and establishing relationships with other models.
- **Enumerations:** an enumeration is a predefined set of values representing a list of possible options. You can use them to group values within a type.
- **Component**: a pre-defined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once and then fill them with different content every time you use it in a content entry.
- **Basic component field**: A component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one or allow multiple component instances to be added to the content entry.
- **References:** References are relations between two or more content entries in your project. With references, you can reuse content entries by connecting them. Once the relation is configured, you can also create related content directly from the content form.

## Step-by-step guide

[Video](https://www.youtube.com/watch?v=dALBVJe261o)

This video follows the same step-by-step tutorial offered in this document.

### 1. Create the enumeration

Our two-level taxonomy model will contain an enumeration field to select a drink type.

Navigate to the **Schema builder** of your Hygraph project, and click `+Add` next to **Enumerations** on the left sidebar. We'll use the following information to create the first one:

| Field        | Input  |
| ------------ | ------ |
| Display name | Drinks |
| API ID       | Drinks |

The next step is to add enumeration values, which are the options you will get when using this later as a dropdown menu.

For every enumeration value, you need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID |
| ------------ | ------ |
| Wine         | wine   |
| Juice        | juice  |

Finally, click `Add enumeration` to save.

We've only added two values because the next step involves creating one model for each of the values that we created here, and we don't want you to waste time creating endless models that would not add quality to the current example.

Since the focus of this guide is the taxonomy, what matters the most is the dynamic where we use an enumeration field to set conditional visibility for reference fields linking the models we will create next.

### 2. Create the sub-category models

We will create two models for our sub-categories. For the sake of this example, we will only include a couple of fields to store basic information, but you may want to add more fields depending on your needs.

To create the first model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input        |
| ------------- | ------------ |
| Display name  | Drink - Wine |
| API ID        | DrinkWine    |
| API ID Plural | DrinkWines   |

Click `Add Model` to save.

Let's add fields to this model. We will add a `Single line text` field to use as category name, and a `Rich Text` field for the category description.

For the category name, add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Name                         |
| Settings    | API ID                | name                         |
| Settings    | Description           | Add a name here              |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validations | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

This configuration ensures all category entries are created with the names as titles, for quick identification in the content table. These titles must also be unique, which will avoid editors adding the wrong entry when selecting categories.

Next, you want include a rich text field for the description, which will also allow some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab         | Field                 | Input                    |
| ----------- | --------------------- | ------------------------ |
| Settings    | Display name          | Description              |
| Settings    | API ID                | description              |
| Settings    | Description           | Write a description here |
| Validations | `Make field required` | Select this checkbox     |

Click `Add` to save.

We created a model for the categories because creating categories as content entries means they can be easily referenced in other models and components later on. This setup also makes adding new categories or editing existing ones very easy.

Since our second category model will contain the same set of fields, we will go ahead and duplicate the model that we've just created, and then edit its details.

In the **Drink - Wine** model, click the 3 dots context menu at the top of the screen, and select `Duplicate`.

![Duplicate model](https://hygraph.com/images/docs/recipes/taxonomy/duplicate-category-model.png)

The system will duplicate the model and will rename it to **Copy of (model name).**

Click on the `Settings` tab at the top and replace the existing information with the following:

| Field         | Input         |
| ------------- | ------------- |
| Display name  | Drink - Juice |
| API ID        | DrinkJuice    |
| API ID Plural | DrinkJuices   |

Click `Update Model` to save.

In the next step, we will create a component for category selection that uses what we've built so far.

### 3. Create the component

In this section you'll create a component for category selection, that we'll later include in the final model as a basic component field.

**Pro Tip:**

Creating a component for the two-level taxonomy setup, allows you potentially reuse it in multiple models.

Since the different levels of category selection would exist at the same level in the schema if added to a model directly, this setup also helps when querying the data, as the query would clearly show these fields as part of the category selection component.

In the **Schema builder**, click `+Add` next to **Components** and use the following information:

| Field         | Input                        |
| ------------- | ---------------------------- |
| Display name  | Two-level taxonomy component |
| API ID        | TwoLevelTaxonomyComponent    |
| API ID Plural | TwoLevelTaxonomyComponents   |

Click `Add component` to save.

Now that you've created the component itself, it's time to add fields to it. You'll add an enumeration field using the enumeration you built earlier, and two reference fields that link to the models you created in the previous step.

This simplified example focuses on linking categories, so make sure to carefully think what other fields your component might need when working on a taxonomy setup for your own project.

Find the `Enumeration` field on the right sidebar, click `Add`, and use the following information to create the enumeration:

| Tab      | Field        | Input                                     |
| -------- | ------------ | ----------------------------------------- |
| Settings | Display name | Drink selector                            |
| Settings | API ID       | drinkSelector                             |
| Settings | Enumeration  | Use the dropdown menu to select `Drinks`. |
| Settings | Description  | Select a drink from the menu              |

Click `Add` to save.

**Pro Tip:**

For the purpose of this example, we're not allowing multiple values. If your category selection requires more than one parent category being selected at the same time, consider allowing multiple values here.

This enumeration field will allow us to set conditions for the 2 reference fields we're about to add. **We did not make this field required because conditional visibility does not support required fields.**

Finally, we will add two reference fields that connect the models we created in the previous step. Referencing the category models here will allow editors to quickly link category content entries directly from the content form.

Add a `Reference` field from the right sidebar, using the following information:

| Tab       | Field                                   | Input                                                                               |
| --------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
| Define    | `Allow only one model to be referenced` | Select this radio button.                                                           |
| Define    | Model to reference                      | use the dropdown to select `Drink - Wine`                                           |
| Define    | Reference direction                     | Use the radio button to select `One-way reference`                                  |
| Define    | Relation cardinality                    | One to Many                                                                         |
| Define    | `Allow multiple (…)`                    | Select this checkbox                                                                |
| Configure | Display name                            | Wine                                                                                |
| Configure | API ID                                  | wine                                                                                |
| Configure | Description                             | Select one or more types of wine                                                    |
| Configure | Show based on condition                 | Select this checkbox and then use the dropdowns to select `Drink selector is Wine.` |

Click `Add` to save.

We'll repeat the process to add the final reference, using the following information:

| Tab       | Field                                   | Input                                                                                |
| --------- | --------------------------------------- | ------------------------------------------------------------------------------------ |
| Define    | `Allow only one model to be referenced` | Select this radio button.                                                            |
| Define    | Model to reference                      | use the dropdown to select `Drink - Juice`                                           |
| Define    | Reference direction                     | Use the radio button to select `One-way reference`                                   |
| Define    | Relation cardinality                    | One to Many                                                                          |
| Define    | `Allow multiple (…)`                    | Select this checkbox                                                                 |
| Configure | Display name                            | Juice                                                                                |
| Configure | API ID                                  | juice                                                                                |
| Configure | Description                             | Select one or more types of juice                                                    |
| Configure | Show based on condition                 | Select this checkbox and then use the dropdowns to select `Drink selector is Juice.` |

Click `Add` to save.

In the next step, we will create the **Two-level Taxonomy model**, which will contain a couple of basic information fields and a basic component field for the component we've just created.

### 2. Create the final model

For this example, we'll create a basic model for a drinks page. We'll add a drink name & description, and a component field for category selection.

To create this model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input                    |
| ------------- | ------------------------ |
| Display name  | Two-level Taxonomy Model |
| API ID        | TwoLevelTaxonomyModel    |
| API ID Plural | TwoLevelTaxonomyModels   |

Click `Add Model` to save.

This model will contain a `Single line text` field for the drink name, a `Rich Text` field for the drink description, and a `Basic component` field for category selection.

First, we'll add the title. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Drink name                   |
| Settings    | API ID                | drinkName                    |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validations | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

This configuration ensures that all the resulting content entries contain a unique title that will allow easy identification in the content table.

Next, you want to include a rich text field for the description, which will also allow some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab      | Field        | Input       |
| -------- | ------------ | ----------- |
| Settings | Display name | Description |
| Settings | API ID       | description |

Click `Add` to save.

Next, you will add the basic component field.  Find the `Basic component` field on the right sidebar, using the following information:

| Tab      | Field              | Input                                                      |
| -------- | ------------------ | ---------------------------------------------------------- |
| Settings | Display name       | Category selector                                          |
| Settings | API ID             | categorySelector                                           |
| Settings | Description        | Select a category and subcategories                        |
| Settings | Select a component | Use the dropdown to select `Two-level taxonomy component`. |

Click `Add` to save.

Your model is ready! This is how you build a two-level taxonomy model in Hygraph where the sub-categories that editors can select are tied to the parent category.

## Resulting content form

If you followed this tutorial, your resulting content form should look like this:

[Video: Resulting content form](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xa2yjau307w5ekz6486x)

When using the category selection component, editors will be able to use a dropdown menu to select a parent category, which will determine which reference field will display to select sub-categories.

In this example, the editor creates a content entry about orange juice and when selecting categories for the drink, they select that it’s a juice of the citrus variety.

## Useful links

- [Components documentation:](https://hygraph.com/docs/developer-guides/schema/components) Learn more about components, available component field types, and how to use them.
- [Enumerations:](https://hygraph.com/docs/developer-guides/schema/using-enumerations) Learn more about enumerations and how to configure them.
- [References:](https://hygraph.com/docs/developer-guides/schema/references) Learn more about the different reference field types and how to configure them.