modifying-taxonomic-filterpar posthog
Guides safe modification of the TaxonomicFilter — PostHog's multi-tab picker for events, actions, properties, cohorts, and more. Front-loads the empirical…
npx skills add https://github.com/posthog/posthog --skill modifying-taxonomic-filterModifying the TaxonomicFilter
The TaxonomicFilter is the picker users hit to choose any "thing PostHog
knows about" — events, properties, actions, cohorts, groups. It's the
on-ramp into almost every analytics and replay configuration. Code lives
in frontend/src/lib/components/TaxonomicFilter/.
The unbreakable rule: changes that demote items users actually pick are regressions, even with all tests passing. Read "Product reality" before deciding any change is safe. Ordering, promotion, or position-0 changes need explicit human sign-off — don't let an agent decide alone.
Product reality (last refreshed 2026-05-02, 90-day window)
Ratios from production telemetry. Re-run via references/refreshing-product-reality.md when older than ~3 months.
How users pick
- Top three rows carry ~80% of selections (position 0: ~56%, position 1: ~15%, position 2: ~8%). Demoting a popular item out of the top three is a real-user regression.
- ~34% selection rate. Two of every three opens close without a pick. p50 dwell ~7s, p90 ~53s — most opens are quick glances.
- Selection paths: ~65% via search, ~19% browsed-no-search, ~16% from recents, <1% from pinned items.
What users select
| Source group type | Share |
|---|---|
events | ~40% |
event_properties | ~30% |
person_properties | ~14% |
cohorts | ~2% |
email_addresses | ~2% |
actions | ~2% |
pageview_urls | ~1% |
| everything else | <1% |
What users search for (share of top-8 terms)
| Term | Share |
|---|---|
email | ~29% |
url | ~22% |
user | ~12% |
utm | ~10% |
page | ~9% |
path | ~8% |
current | ~6% |
country | ~5% |
email and url are over half the top-8. They're the entire reason
PROMOTED_PROPERTIES_BY_SEARCH_TERM (in infiniteListLogic.ts) maps
them to $email and $current_url at position 0. Touching
promotion or ordering needs explicit human sign-off.
Empty searches
email, url, utm, path against cohorts, event_feature_flags,
session_properties produce most empty-result events — users type the
same canonical terms across every tab. Tab order, suggested-filters
aggregation, and shortcut routing are how they get to the right answer.
Input mode
~93% typed, ~7% pasted. Both feed inputMode on taxonomic_filter_search_query.
Telemetry is a contract
Five events validate every change. Treat property shapes as a public API:
taxonomic filter closed—dwellMs,hadSelectiontaxonomic filter item selected—sourceGroupType,wasFromRecents,wasFromPinnedList,wasQuickFilter,hadSearchInput,position,querytaxonomic_filter_search_query—searchQuery,groupType,inputMode,pastedFractiontaxonomic filter empty result—groupType,searchQuerytaxonomic filter category dropdown opened— A/B variant
Adding properties: fine. Removing dead ones: fine. Renaming or repurposing silently is the worst case — dashboards keep working and start lying.
Variants you might not see locally
TAXONOMIC_FILTER_CATEGORY_DROPDOWN resolves to 'control' (tab pills)
or 'pill' (suffix dropdown). Bug reports that don't reproduce locally
are usually a variant mismatch. Touching tab rendering means testing both.
Pre-change checklist
- Read references when relevant: architecture, common-pitfalls (X/Y matrix), call-sites (smoke tests), testing-patterns
- Test both
controlandpilldropdown variants if you touched tabs - Confirm telemetry payloads still have the same property shape
- Ordering / promotion / position-0 -> human sign-off, not agent judgement
hogli test frontend/src/lib/components/TaxonomicFilter/