# How to Create a Component Hierarchy in Jira

September 23, 2026 ·

<!-- -->

5 min read

[NGPilot](https://ngpilot.com)

Jira components were designed for a flat world: one list, no nesting, no structure. That works at ten components and collapses at fifty — when "SSO" sits next to "Platform" and "Mobile" with nothing expressing that it belongs under "Auth", which belongs under "Platform". Teams end up encoding the architecture in name prefixes and maintaining ever-growing `component in (...)` lists by hand. This guide covers three ways to get a component hierarchy in Jira, and what each one costs.

**Quick answer:** Jira cannot nest components natively. [Component Hierarchy for Jira](https://marketplace.atlassian.com/apps/2232005585/) adds a parent-child tree per project: build it on a project page, pick a full path like `Platform/Auth/SSO` on each issue with a cascading picker, and search whole branches with one JQL function — `inComponentHierarchy("Auth")` — instead of maintained component lists. Every node is a real Jira component, so boards, releases, and reports keep working.

## Why a Flat Component List Stops Working[​](#why-a-flat-component-list-stops-working "Direct link to Why a Flat Component List Stops Working")

The flat model fails in a specific, predictable way: the structure lives in people's heads, and every tool that needs it re-asks for it. A board filter wants the list of platform components. A report wants everything under Auth. A new subcomponent invalidates every one of those lists at once. Multiply by a few areas and a few teams, and "which components make up the platform?" becomes tribal knowledge with a shelf life.

## Method 1 — Naming Conventions (Free, Fragile)[​](#method-1--naming-conventions-free-fragile "Direct link to Method 1 — Naming Conventions (Free, Fragile)")

Rename components into paths: `platform-auth-sso`, `platform-auth-oauth`, `mobile-auth-sso`. Sorting by name fakes a tree view, and the prefix tells humans where things belong.

**Good for:** small projects that need a visible grouping and nothing more.

**What's missing:** the hierarchy is in the string, and nothing queries it. There is no JQL for "everything starting with `platform-auth-` and everything under it" — you still enumerate members. Conventions also rot: one person types `Platform-auth`, another creates `platform-auth-sso-v2`, and every filter built on the prefix quietly misses issues. Structure by convention needs a curator, and curators move on.

## Method 2 — Labels or a Custom Field (Searchable, Unstructured)[​](#method-2--labels-or-a-custom-field-searchable-unstructured "Direct link to Method 2 — Labels or a Custom Field (Searchable, Unstructured)")

Give issues a second axis: a label like `area-auth` or a single-select custom field "Subsystem". JQL can now filter on it.

**Good for:** one level of grouping that only needs to answer "all issues in area X".

**What's missing:** a flat field cannot answer path questions — "everything under Platform, at any depth" becomes another explicit list of values. There is no cascade (pick Auth and SSO must follow), no structure for a service catalog, and now you maintain two parallel truths: the components boards use, and the field reports use. They drift.

## Method 3 — a Real Component Tree (Recommended)[​](#method-3--a-real-component-tree-recommended "Direct link to Method 3 — a Real Component Tree (Recommended)")

[Component Hierarchy for Jira](https://marketplace.atlassian.com/apps/2232005585/) adds the missing dimension on top of components, not instead of them:

1. **Build the tree** on the project page (project sidebar → **Apps** → **Component Hierarchy**): add root nodes, nest children as deep as needed, move subtrees, rename anything. Changes save automatically, and every node is a **real Jira component** — existing components with matching names are adopted, never duplicated.

2. **Pick a path on each issue.** The *Component Hierarchy* field is a cascading picker — level by level from roots to leaves — available on issues, create dialogs, transition screens, and JSM portal requests. Setting it adds the selected nodes' components to the issue automatically (it only ever adds).

3. **Search branches with one clause.** `inComponentHierarchy("Auth")` returns every issue whose path is `Auth` or starts with `Auth/`, at any depth:

   ```
   inComponentHierarchy("Auth") AND status != Done

   inComponentHierarchy("Platform") AND assignee = currentUser()

   not inComponentHierarchy("Deprecated")
   ```

   Two nodes sharing a name at different depths? Add the level: `inComponentHierarchy("Auth", 2)`.

Because queries resolve through the tree, they stay correct as it evolves: rename a node and every issue shows the new name immediately; add a subcomponent tomorrow and every saved filter covering its parent already covers it. No more lists to maintain.

## Bulk-Build the Tree from CSV[​](#bulk-build-the-tree-from-csv "Direct link to Bulk-Build the Tree from CSV")

For a project with an established component list, don't click the tree into existence — import it:

```
Name,Parent

Platform,

Auth,Platform

SSO,Auth

OAuth,Auth

Mobile,
```

A blank `Parent` marks a root; every parent must be defined in its own row. Download the exact template from the project page, fill it in, and import — the import **replaces** the current tree (export first if you want a backup), and the **Sync components** button creates a Jira component for any node still missing one.

## Which Method Should You Use?[​](#which-method-should-you-use "Direct link to Which Method Should You Use?")

| Need                                                         | Use                          |
| ------------------------------------------------------------ | ---------------------------- |
| A visible grouping on a handful of components                | Naming conventions           |
| One flat "subsystem" axis for filtering                      | Label or single-select field |
| A real tree: cascading picker, subtree JQL, service catalogs | Component Hierarchy for Jira |

The third row is the one that survives growth: the tree stays the single source of structure, components stay the single source of truth for boards and reports, and branch queries cost one function call instead of a maintained list. Install [Component Hierarchy for Jira](https://marketplace.atlassian.com/apps/2232005585/), import your existing structure as CSV, and let `inComponentHierarchy()` replace the lists.

## Related Resources[​](#related-resources "Direct link to Related Resources")

* [Build a Component Hierarchy in Jira](/solutions/component-hierarchy-in-jira.md) — the scenario guide: modeling, adoption paths, and search patterns
* [How to Add a Checklist to Jira](/blog/jira-checklist.md) — another way to add missing structure to Jira issues
* [Component Hierarchy for Jira](/apps/component-hierarchy-for-jira.md) — full documentation: the tree editor, the field, JQL, CSV import/export, and troubleshooting

## Related guides

* [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md)
* [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md)
* [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md)
* [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md)
* [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md)

Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links)

**Tags:**

* [jira](/blog/tags/jira.md)
* [components](/blog/tags/components.md)
* [hierarchy](/blog/tags/hierarchy.md)
* [jql](/blog/tags/jql.md)
* [how-to](/blog/tags/how-to.md)
* [project-structure](/blog/tags/project-structure.md)