Custom theme integration

Manually place TreeNav navigation when auto-detection doesn't work.

When you need custom integration

  • Auto-detection doesn't find your theme's filter area
  • You want navigation in a non-standard location
  • Your theme has unique structure
  • You want full control over placement

Finding the right selector

Step 1: Inspect your theme

  1. Open your store in a browser
  2. Navigate to a collection page
  3. Right-click on the filter area
  4. Click Inspect or Inspect Element

Step 2: Identify the container

Look for a wrapper element:

  • Class names with filter, facets, sidebar
  • ID attributes
  • Data attributes like data-section-type

Good containers:

<div class="collection-sidebar">
<aside id="product-filters">
<div data-facets-wrapper>

Step 3: Build the selector

By class:

.collection-sidebar

By ID:

#product-filters

By attribute:

[data-facets-wrapper]

Multiple classes:

.sidebar.filters-area

Nested:

.collection__content .sidebar-filters

Step 4: Test the selector

In browser console:

document.querySelector('.your-selector')

If it returns an element, the selector works.

Configuring custom position

  1. Go to theme editor → App embeds → TreeNav Tree
  2. Set Desktop filters location to Custom position
  3. Enter your selector in Custom CSS selector
  4. Choose Placement:
    • Inside (start) – First child
    • Inside (end) – Last child
    • Before container – Sibling before
    • After container – Sibling after
  5. Repeat for mobile if different

Placement options explained

Given this container:

<div class="filters-sidebar">
  <div class="existing-filter">Price</div>
  <div class="existing-filter">Color</div>
</div>

Inside (start):

<div class="filters-sidebar">
  <nav class="treenav">...</nav>  <!-- TreeNav -->
  <div class="existing-filter">Price</div>
  <div class="existing-filter">Color</div>
</div>

Inside (end):

<div class="filters-sidebar">
  <div class="existing-filter">Price</div>
  <div class="existing-filter">Color</div>
  <nav class="treenav">...</nav>  <!-- TreeNav -->
</div>

Before container:

<nav class="treenav">...</nav>  <!-- TreeNav -->
<div class="filters-sidebar">
  <div class="existing-filter">Price</div>
  <div class="existing-filter">Color</div>
</div>

After container:

<div class="filters-sidebar">
  <div class="existing-filter">Price</div>
  <div class="existing-filter">Color</div>
</div>
<nav class="treenav">...</nav>  <!-- TreeNav -->

Different selectors for desktop and mobile

Many themes have different structures for desktop and mobile.

Desktop: Sidebar visible in main content

Mobile: Filters in a drawer/modal

Configure each separately:

  1. Set Desktop filters location to Custom position
  2. Enter desktop selector
  3. Set Mobile filters location to Custom position
  4. Enter mobile selector

Finding mobile selector

  1. Use browser responsive mode (or actual device)
  2. Open the filter drawer
  3. Inspect the drawer container
  4. Find a unique selector

Display as dropdown

For horizontal/topbar layouts, enable Display as dropdown:

  • Tree appears in a collapsed button/heading
  • Expands on click
  • Good for space-constrained areas

Example: Custom sidebar

Theme structure:

<div class="collection-page">
  <aside class="collection-filters">
    <div class="filter-group">...</div>
  </aside>
  <main class="products">...</main>
</div>

Configuration:

  • Selector: .collection-filters
  • Placement: Inside (start)

Result:

<aside class="collection-filters">
  <nav class="treenav">...</nav>
  <div class="filter-group">...</div>
</aside>

Example: Above product grid

Goal: Show tree above products, not in sidebar

Theme structure:

<div class="collection-page">
  <div class="collection-header">
    <h1>Collection Title</h1>
  </div>
  <div class="products-wrapper">
    ...
  </div>
</div>

Configuration:

  • Selector: .products-wrapper
  • Placement: Before container
  • Enable Display as dropdown for compact display

Debugging custom integration

  1. Enable Show debug panel
  2. Check if your selector is found
  3. Verify placement is correct
  4. Adjust as needed

Common issues:

  • Selector too specific (element changes)
  • Selector too general (multiple matches)
  • Element loads dynamically (JS)

Dynamic/JavaScript themes

Some themes load content via JavaScript. If your selector isn't found:

  1. The element might not exist on initial page load
  2. TreeNav might inject before the element is created
  3. Contact support for advanced solutions

Fallback: Manual block placement

If custom selector doesn't work, add TreeNav as a regular section:

  1. Add TreeNav Breadcrumb or Drilldown as app blocks
  2. Position manually in the template
  3. These work without auto-detection

Testing your integration

  1. Check desktop collection pages
  2. Check mobile collection pages
  3. Test multiple collections
  4. Verify navigation functions correctly
  5. Test across different browsers

Next steps