> For the complete documentation index, see [llms.txt](https://ovatheme.gitbook.io/brw/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ovatheme.gitbook.io/brw/brw-menu/custom-taxonomy.md).

# Custom Taxonomy

## Watch The Video Tutorial

{% embed url="<https://youtu.be/KY7hVmq2LEQ>" %}

A **Custom Taxonomy** in BRW is a filterable attribute dimension you define — similar to WooCommerce product attributes, but registered as a real WordPress taxonomy and deeply integrated with the BRW search form.

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><mark style="color:red;"><strong>Vehicle Type</strong></mark><br><mark style="color:pink;"><strong>Term</strong>s: SUV, Sedan, Convertible, Van</mark></td></tr><tr><td><mark style="color:red;"><strong>Fuel Type</strong></mark><br><mark style="color:pink;"><strong>Terms</strong>: Petrol, Diesel, Electric, Hybrid</mark></td></tr><tr><td><mark style="color:red;"><strong>Transmission</strong></mark><br><mark style="color:pink;"><strong>Terms</strong>: Automatic, Manual</mark></td></tr><tr><td><mark style="color:red;"><strong>Amenities</strong></mark><br><mark style="color:pink;"><strong>Terms</strong>: Pool, WiFi, Parking, Kitchen</mark></td></tr></tbody></table>

{% hint style="info" %} <mark style="color:$primary;">**vs WooCommerce Attributes:**</mark> <mark style="color:$primary;"></mark><mark style="color:$primary;">WooCommerce attributes are for variations (size, color). BRW Custom Taxonomies are for search filtering — they show up as filter dropdowns in the BRW search form and can be scoped to specific categories.</mark>
{% endhint %}

### How It Works

Complete setup flow from creation to frontend filter

{% stepper %}
{% step %}

### Create Taxonomy

Add a new taxonomy with slug, name, and labels
{% endstep %}

{% step %}

### Add Terms

Click Manage → add term values (SUV, Sedan, etc.)
{% endstep %}

{% step %}

### Assign to Products

In each product's edit screen, assign terms
{% endstep %}

{% step %}

### Link to Category

In Categories, choose which taxonomies belong to each category
{% endstep %}

{% step %}

### Show in Search

Enable Taxonomy filter in Settings → Search or in per element/shortcode
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**Important:** <mark style="color:red;">After creating a taxonomy here, WordPress registers it as a real taxonomy. You must re-save your WordPress permalinks (Settings → Permalinks → Save) if the taxonomy archive URLs aren't working.</mark>
{% endhint %}

### 1: Taxonomy List

Overview of all created taxonomies and what each column means

All created taxonomies are displayed in a sortable table. Drag rows via the ☰ handle to reorder how they appear in the search form.

| Column              | Description                                                                                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Slug**            | The internal WordPress taxonomy identifier. Used as the taxonomy key in code and URLs. Cannot be changed after saving.                             |
| **Name**            | Plural display name used in the WordPress admin (e.g., "Vehicle Types"). Appears in admin menus.                                                   |
| **Singular Name**   | Singular form of the name used in admin UI labels (e.g., "Vehicle Type").                                                                          |
| **Label**           | The frontend-facing label shown to customers in the search form and product pages (e.g., "Type of Vehicle"). Falls back to Singular Name if empty. |
| **Manage**          | Link (with term count) to the WordPress taxonomy term editor — where you add the actual filter values (e.g., SUV, Sedan, Truck).                   |
| **Enable**          | ✓ indicates the taxonomy is active. Disabled taxonomies are hidden from the search form and not available in category settings.                    |
| **Show in Listing** | ✓ indicates this taxonomy's terms are displayed on product cards in the archive/listing page.                                                      |
| **Actions**         | Per-row quick actions: Edit (✏️), Enable/Disable (👁️), Delete (🗑️), Reorder (☰).                                                                 |

{% hint style="info" %}
**Reordering:** Drag rows by the ☰ handle to change the order. This order determines the sequence in which taxonomy filters appear in the BRW search form.
{% endhint %}

<figure><img src="/files/6VHvzMMCXHq2GBlBBmTT" alt=""><figcaption></figcaption></figure>

### 2: Bulk Actions

Apply actions to multiple taxonomies at once using the checkboxes

Select one or more taxonomies using the checkboxes, then click one of the bulk action buttons in the toolbar.

**Enable:** Activates the selected taxonomies. They become available in the search form and category settings.

**Disable:** Deactivates taxonomies without deleting them. Hidden from search form and categories while disabled.

**Show in Listing**: Enables the "Show in Listing" flag — terms appear on product archive cards.

**Hide in Listing**: Disables the "Show in Listing" flag — terms are hidden from archive cards but still work for filtering.

**Delete**: Permanently removes the taxonomy definition. Does not delete the terms already assigned to products — those remain as orphaned data.

{% hint style="danger" %}
**Deleting a taxonomy** <mark style="color:$danger;">that has terms assigned to products will leave those assignments as orphaned metadata. The terms themselves are deleted from WordPress's term tables automatically, but the product meta data referencing them may remain. Re-creating a taxonomy with the same slug re-activates those assignments.</mark>
{% endhint %}

<figure><img src="/files/2FLDlfh2khznWhgl0xfM" alt=""><figcaption></figcaption></figure>

### 3: Add Taxonomy Popup

Click "Add taxonomy" to open the creation popup

Clicking **Add taxonomy** opens an inline popup form. The same form is used for editing (with the Slug field locked to read-only).

<figure><img src="/files/Fbjh9lzhQPbkDJOl8O0u" alt=""><figcaption></figcaption></figure>

#### Fields Reference

Detailed explanation of each field in the Add / Edit popup

**Slug**

The internal identifier used to register this taxonomy with WordPress. It becomes the taxonomy key in the database and in URLs.

| Rule         | Detail                                                                                 |
| ------------ | -------------------------------------------------------------------------------------- |
| Characters   | Lowercase letters, numbers, and underscores only. No spaces, no uppercase, no hyphens. |
| Max Length   | 32 characters (WordPress taxonomy key limit)                                           |
| Uniqueness   | Must be unique across all BRW taxonomies and WordPress taxonomies                      |
| After saving | The slug is locked (read-only). Changing it would break all term assignments.          |

{% hint style="warning" %}
**Good examples:** `vehicle_type`, `fuel_type`, `transmission`, `boat_class`\
**Bad examples:** `Vehicle Type` (spaces), `vehicleType` (uppercase), `my-taxonomy` (hyphens — WordPress allows these but BRW recommends underscores)
{% endhint %}

**Name**

The **plural** name of the taxonomy used in the WordPress admin. This appears in the admin menu item created for this taxonomy (e.g., under Products), in bulk action messages, and in the Manage link label.

{% hint style="info" %}
**Example:** Slug = `vehicle_type` → Name = *"Vehicle Types"*\
This shows up as a menu item like: Products → Vehicle Types
{% endhint %}

**Singular Name**

The **singular** form used in admin UI labels — for example: "Add new Vehicle Type", "Edit Vehicle Type". Also used as the frontend filter label if Label Frontend is left empty.

{% hint style="info" %}
**Example:** Name = "Vehicle Types" → Singular Name = *"Vehicle Type"*
{% endhint %}

**Label Frontend**

The label shown to customers on the **frontend** — in the search form filter, on product cards, and in the BRW category selector. If left empty, the Singular Name is used as the fallback.

| Singular Name | Label Frontend (example) | Shown to customers as |
| ------------- | ------------------------ | --------------------- |
| Vehicle Type  | *(empty)*                | Vehicle Type          |
| Vehicle Type  | Type of Vehicle          | Type of Vehicle       |
| Fuel Type     | Powered by               | Powered by            |

{% hint style="warning" %}
**Best practice:** Use Label Frontend to write more customer-friendly copy. The admin Name/Singular Name can be technical; Label Frontend should match your brand language.
{% endhint %}

**Enable**

When checked, the taxonomy is **active**:

* Appears in the BRW search form taxonomy filter
* Available for selection in BRW → Categories → Choose Custom Taxonomies
* Can be assigned to products in the product editor

{% hint style="warning" %}
Unchecking does not delete the taxonomy or its terms — it simply hides it everywhere. You can re-enable it at any time.
{% endhint %}

**Show in Listing**

When checked, this taxonomy's assigned terms are displayed on product archive cards. For example, if a Car product has the term "SUV" assigned under Vehicle Type taxonomy, "SUV" appears on its archive card.

{% hint style="info" %}
**Tip:** Enable for key attributes customers scan quickly (Vehicle Type, Transmission). Disable for internal-use taxonomies that shouldn't clutter the listing card.
{% endhint %}

### **4: Manage Terms**

Adding the actual filter values to a taxonomy

Creating a taxonomy only registers the dimension. You still need to add the **terms** (the actual values customers can filter by). Click the link in the **Manage** column — it opens the standard WordPress taxonomy term editor for that taxonomy.

**Example: vehicle\_type taxonomy**

| Term Name   | Slug        | Description            | Count |
| ----------- | ----------- | ---------------------- | ----- |
| SUV         | suv         | Sport Utility Vehicle  | 8     |
| Sedan       | sedan       | Standard saloon car    | 12    |
| Convertible | convertible | Open-top vehicle       | 3     |
| Van         | van         | Cargo or passenger van | 5     |

{% hint style="info" %}
**Workflow:**

1. <mark style="color:$primary;">Click the link in the Manage column (shows term count in parentheses)</mark>
2. <mark style="color:$primary;">Use the "Add New \[Taxonomy Name]" panel on the left to add terms</mark>
3. <mark style="color:$primary;">After adding terms, go to each rental product and assign the relevant terms</mark>
   {% endhint %}

{% hint style="warning" %}
**Term count:** The Manage column shows *(0)* until you add terms. After adding, it updates to show the number of enabled terms, e.g., *(4)*.
{% endhint %}

<div><figure><img src="/files/I3kQ8HHJF6ZlUkdcZ7pN" alt=""><figcaption></figcaption></figure> <figure><img src="/files/rKjDAag0mlTJNSh1H6Wt" alt=""><figcaption></figcaption></figure></div>

### 5: Connect to Category

Link taxonomies to categories for context-aware search filtering

BRW supports scoping taxonomy filters to specific rental categories. When a customer selects a category in the search form, only the taxonomy filters linked to that category appear.

**Example scoping setup**

| Category   | Linked Taxonomies                            | Why                   |
| ---------- | -------------------------------------------- | --------------------- |
| Cars       | Vehicle Type, Fuel Type, Transmission, Seats | Car-specific filters  |
| Boats      | Boat Class, Engine Type, Capacity            | Boat-specific filters |
| Apartments | Amenities, Bedrooms, View Type               | Accommodation filters |

{% hint style="danger" %} <mark style="color:$danger;">**Setup steps**</mark>

1. <mark style="color:red;">Go to</mark> <mark style="color:red;"></mark><mark style="color:red;">**WooCommerce → Settings → Booking & Rental → General**</mark>
2. <mark style="color:red;">Set</mark> <mark style="color:red;"></mark>*<mark style="color:red;">"Show Taxonomy Depending On Category"</mark>* <mark style="color:red;"></mark><mark style="color:red;">to</mark> <mark style="color:red;"></mark><mark style="color:red;">**Based on each category**</mark>
3. <mark style="color:red;">Go to</mark> <mark style="color:red;"></mark><mark style="color:red;">**BRW → Categories**</mark><mark style="color:red;">, edit or add a category</mark>
4. <mark style="color:red;">In the</mark> <mark style="color:red;"></mark>*<mark style="color:red;">"Choose Custom Taxonomies"</mark>* <mark style="color:red;"></mark><mark style="color:red;">multiselect, pick the taxonomies for that category</mark>
5. <mark style="color:red;">Save the category</mark>
6. <mark style="color:red;">Repeat for each category</mark>

<mark style="color:$primary;">**If "Show Taxonomy Depending On Category" = All:**</mark> <mark style="color:$primary;"></mark><mark style="color:$primary;">All enabled taxonomies always appear in the search form regardless of which category is selected. The per-category linking in step 3-5 is ignored.</mark>
{% endhint %}

### 6: Connect to Product

* Go to: **Products >> Add New**
* Choose Category: All Custom Taxonomies of that category will be shown
* Set value for each Custom Taxonomy

Suppose that you choose "Car" category, "Year" custom taxonomy of it will be shown

<figure><img src="/files/SkHiEvqnbPY6fyGwSd3F" alt=""><figcaption></figcaption></figure>

### 7: Display Custom taxonomies

#### In search form

Go to: WooCommerce >> Settings >> Booking & Rental >> Search Settings

* **Hide/ Show Taxonomy in Search Settings**
* **Hide Taxonomy List  (slug):** Insert Slug of Custom Taxonomy to hide Custom Taxonomy in Drop-down&#x20;
* **Require Taxonomy List (slug):** Insert Slug to make Taxonomy List, and require customers to select taxonomy for searching.

<div><figure><img src="/files/Cux8OaS64PJIKHqrF5in" alt=""><figcaption></figcaption></figure> <figure><img src="/files/lfT4eNJGzIj1moBsZwFF" alt=""><figcaption></figcaption></figure></div>

#### In Shortcode/Element Search Form

Check in params/setting of per shortcode/element